Merge pull request #252 from MiaoDX: Update MCP to use server_fastmcp with venv Python

This PR modernizes the MCP setup with comprehensive improvements: **Key Improvements:** ✅ Virtual environment auto-detection (venv, .venv, $VIRTUAL_ENV) ✅ Module-based imports (python -m skill_seekers.mcp.server_fastmcp) ✅ Eliminates 'module not found' errors from missing dependencies ✅ No need for --break-system-packages or global installs ✅ Clean project isolation with venv ✅ Prepares for v3.0.0 when server.py will be removed **Bug Fixes:** 🐛 Fixed 41 instances of server_fastmcp_fastmcp → server_fastmcp typo 🐛 Updated tests to accept -e ".[mcp]" format 🐛 Updated tests for module reference format **Files Changed:** 13 files (+312/-154 lines) **Testing:** All 1386 tests passing (verified) Co-Authored-By: MiaoDX <miaodx@hotmail.com> Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-18 13:39:20 +03:00
parent d2c1040c65 ce4d90eea4
commit 6f39fc273f
13 changed files with 234 additions and 76 deletions
--- a/docs/guides/MCP_SETUP.md
+++ b/docs/guides/MCP_SETUP.md
@@ -134,16 +134,28 @@ python3 -c "import mcp; print(mcp.__version__)"

 **For HTTP-based agents (Cursor, Windsurf, IntelliJ):**

-Old config (v2.3.0):
+Old config (v2.3.0 - DEPRECATED):
 ```json
 {
  "command": "python",
-  "args": ["-m", "skill_seekers.mcp.server", "--http", "--port", "3000"]
+  "args": ["-m", "skill_seekers.mcp.server_fastmcp", "--http", "--port", "3000"]
 }
 ```

-New config (v2.4.0):
+New config (v2.4.0+):
 ```json
+# For stdio transport (Claude Code, VS Code + Cline):
+{
+  "type": "stdio",
+  "command": "python3",
+  "args": ["-m", "skill_seekers.mcp.server_fastmcp"]
+}
+
+# For HTTP transport (Cursor, Windsurf, IntelliJ):
+# Run server separately:
+# python3 -m skill_seekers.mcp.server_fastmcp --transport http --port 3000
+#
+# Then configure agent with URL:
 {
  "url": "http://localhost:3000/sse"
 }
@@ -316,9 +328,9 @@ pwd
 ### Claude Code (stdio transport)

 **Config Location:**
- **macOS**: `~/Library/Application Support/Claude/mcp.json`
- **Linux**: `~/.config/claude-code/mcp.json`
- **Windows**: `%APPDATA%\Claude\mcp.json`
+- **macOS**: `~/.claude.json`
+- **Linux**: `~/.claude.json`
+- **Windows**: `~/.claude.json`

 **Configuration:**

@@ -326,8 +338,10 @@ pwd
 {
  "mcpServers": {
    "skill-seeker": {
-      "command": "python",
-      "args": ["-m", "skill_seekers.mcp.server_fastmcp"]
+      "type": "stdio",
+      "command": "python3",
+      "args": ["-m", "skill_seekers.mcp.server_fastmcp"],
+      "env": {}
    }
  }
 }
@@ -338,16 +352,17 @@ pwd
 {
  "mcpServers": {
    "skill-seeker": {
+      "type": "stdio",
      "command": "/usr/local/bin/python3.11",
-      "args": ["-m", "skill_seekers.mcp.server_fastmcp"]
+      "args": ["-m", "skill_seekers.mcp.server_fastmcp"],
+      "env": {}
    }
  }
 }
 ```

 **Setup Steps:**
-1. Create config directory: `mkdir -p ~/Library/Application\ Support/Claude`
-2. Edit config: `nano ~/Library/Application\ Support/Claude/mcp.json`
+1. Edit config: `nano ~/.claude.json`
 3. Paste configuration above
 4. Save and exit
 5. Restart Claude Code
@@ -843,6 +858,79 @@ Agent: ✅ Uploaded to Google Gemini

 ---

+### Issue: "skill-seeker · ✘ failed" Connection Error
+
+**Symptoms:**
+- MCP server shows as "failed" when running `/mcp` in Claude Code
+- Cannot access Skill Seeker tools
+- Error: "ModuleNotFoundError: No module named 'skill_seekers'"
+
+**Solution 1: Install Package and MCP Dependencies**
+
+```bash
+# Navigate to Skill Seekers directory
+cd /path/to/Skill_Seekers
+
+# Install package with MCP dependencies
+pip3 install -e ".[mcp]"
+```
+
+**Solution 2: Fix ~/.claude.json Configuration**
+
+Common configuration problems:
+- Using `python` instead of `python3` (doesn't exist on macOS)
+- Missing `"type": "stdio"` field
+- Missing `"cwd"` field for proper working directory
+- Using deprecated `server` instead of `server_fastmcp`
+
+**Correct configuration:**
+
+```json
+{
+  "mcpServers": {
+    "skill-seeker": {
+      "type": "stdio",
+      "command": "python3",
+      "args": [
+        "-m",
+        "skill_seekers.mcp.server_fastmcp"
+      ],
+      "cwd": "/full/path/to/Skill_Seekers",
+      "env": {}
+    }
+  }
+}
+```
+
+**Verify Installation:**
+
+```bash
+# Test module import
+python3 -c "from skill_seekers.mcp import server_fastmcp; print('✓ Module OK')"
+
+# Test server startup
+cd /path/to/Skill_Seekers
+python3 -m skill_seekers.mcp.server_fastmcp
+# Should start without errors (Ctrl+C to stop)
+```
+
+**Validate JSON Configuration:**
+
+```bash
+# Check JSON syntax
+python3 -m json.tool < ~/.claude.json > /dev/null && echo "✓ JSON valid"
+```
+
+**Restart Claude Code:**
+
+After fixing configuration:
+1. Quit Claude Code completely (don't just close window)
+2. Kill any background processes: `pkill -f skill_seekers`
+3. Reopen Claude Code
+4. Test with `/mcp` command
+
+---
+
 ### Issue: "ModuleNotFoundError: No module named 'mcp'"

 **Solution:**
--- a/docs/guides/MULTI_AGENT_SETUP.md
+++ b/docs/guides/MULTI_AGENT_SETUP.md
@@ -8,7 +8,7 @@ The setup script automatically detects and configures:

 | Agent | Transport | Config Path (macOS) |
 |-------|-----------|---------------------|
-| **Claude Code** | stdio | `~/Library/Application Support/Claude/mcp.json` |
+| **Claude Code** | stdio | `~/.claude.json` |
 | **Cursor** | HTTP | `~/Library/Application Support/Cursor/mcp_settings.json` |
 | **Windsurf** | HTTP | `~/Library/Application Support/Windsurf/mcp_config.json` |
 | **VS Code + Cline** | stdio | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
--- a/docs/guides/SETUP_QUICK_REFERENCE.md
+++ b/docs/guides/SETUP_QUICK_REFERENCE.md
@@ -10,7 +10,7 @@

 | Agent | Transport | Auto-Detected | Config Path (macOS) |
 |-------|-----------|---------------|---------------------|
-| Claude Code | stdio | ✅ | `~/Library/Application Support/Claude/mcp.json` |
+| Claude Code | stdio | ✅ | `~/.claude.json` |
 | Cursor | HTTP | ✅ | `~/Library/Application Support/Cursor/mcp_settings.json` |
 | Windsurf | HTTP | ✅ | `~/Library/Application Support/Windsurf/mcp_config.json` |
 | VS Code + Cline | stdio | ✅ | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
@@ -278,7 +278,7 @@ docs/MCP_SETUP.md               # MCP integration guide

 ### Config Paths (macOS)
 ```
-~/Library/Application Support/Claude/mcp.json
+~/.claude.json
 ~/Library/Application Support/Cursor/mcp_settings.json
 ~/Library/Application Support/Windsurf/mcp_config.json
 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
--- a/docs/guides/TESTING_GUIDE.md
+++ b/docs/guides/TESTING_GUIDE.md
@@ -260,7 +260,7 @@ Test MCP server and all 18 MCP tools.
@pytest.mark.asyncio
 async def test_mcp_list_configs():
    """Test list_configs MCP tool."""
-    from skill_seekers.mcp.server import app
+    from skill_seekers.mcp.server_fastmcp import app

    # Call list_configs tool
    result = await app.call_tool('list_configs', {})