fix(mcp): add uvx PATH preflight check and actionable guidance (#5600)

src/openhuman/mcp/config_servers/spawn_env.rs

@@ -148,6 +148,14 @@ fn version_manager_dirs() -> Vec<PathBuf> {
         push_if_dir(&mut dirs, home.join(".cargo").join("bin"));
         dirs.extend(nvm_latest_bin_dir(&home));
     }
+    #[cfg(windows)]
+    {
+        if let Some(local_app_data) = dirs::data_local_dir() {
+            push_if_dir(&mut dirs, local_app_data.join("Programs").join("uv").join("bin"));
+            push_if_dir(&mut dirs, local_app_data.join("Programs").join("uv"));
+            push_if_dir(&mut dirs, local_app_data.join("bin"));
+        }
+    }
     for fixed in ["/opt/homebrew/bin", "/usr/local/bin", "/usr/local/sbin"] {
         push_if_dir(&mut dirs, PathBuf::from(fixed));
     }

src/openhuman/mcp/config_servers/stdio.rs

@@ -311,4 +311,28 @@ mod tests {
             "expected Node.js guidance, got: {err}"
         );
     }
+
+    #[tokio::test]
+    async fn initialize_missing_uvx_mentions_uv_and_docs_link() {
+        let client = McpStdioClient::new(
+            "uvx".to_string(),
+            Vec::new(),
+            vec![("PATH".to_string(), "/openhuman/does-not-exist".to_string())],
+            None,
+            McpClientIdentityConfig::default(),
+        );
+        let err = client
+            .initialize()
+            .await
+            .expect_err("missing uvx must fail");
+        let msg = err.to_string();
+        assert!(
+            msg.contains("uv (Python)"),
+            "expected uv guidance, got: {msg}"
+        );
+        assert!(
+            msg.contains("https://docs.astral.sh/uv/"),
+            "expected uv docs link, got: {msg}"
+        );
+    }
 }