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/.claude/mcp_config.example.json
+++ b/.claude/mcp_config.example.json
@@ -1,11 +1,13 @@
 {
  "mcpServers": {
    "skill-seeker": {
-      "command": "python3",
+      "type": "stdio",
+      "command": "/path/to/your/Skill_Seekers/.venv/bin/python3",
      "args": [
-        "/REPLACE/WITH/YOUR/PATH/Skill_Seekers/mcp/server.py"
+        "-m",
+        "skill_seekers.mcp.server_fastmcp"
      ],
-      "cwd": "/REPLACE/WITH/YOUR/PATH/Skill_Seekers",
+      "cwd": "/path/to/your/Skill_Seekers",
      "env": {}
    }
  }
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -187,10 +187,10 @@ skill-seekers enhance-status output/react/ --watch
 skill-seekers package output/react/ --target gemini --dry-run

 # Test MCP server (stdio mode)
-python -m skill_seekers.mcp.server
+python -m skill_seekers.mcp.server_fastmcp

 # Test MCP server (HTTP mode)
-python -m skill_seekers.mcp.server --transport http --port 8765
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765
 ```

 ## 🔧 Key Implementation Details
@@ -546,10 +546,10 @@ See `docs/ENHANCEMENT_MODES.md` for detailed documentation.

 ```bash
 # stdio mode (Claude Code, VS Code + Cline)
-python -m skill_seekers.mcp.server
+python -m skill_seekers.mcp.server_fastmcp

 # HTTP mode (Cursor, Windsurf, IntelliJ)
-python -m skill_seekers.mcp.server --transport http --port 8765
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765
 ```

 ## 📋 Common Workflows
--- a/README.md
+++ b/README.md
@@ -1143,7 +1143,7 @@ Skill Seekers MCP server supports 2 transport modes:
  "mcpServers": {
    "skill-seeker": {
      "command": "python3",
-      "args": ["-m", "skill_seekers.mcp.server"],
+      "args": ["-m", "skill_seekers.mcp.server_fastmcp"],
      "cwd": "/path/to/Skill_Seekers"
    }
  }
@@ -1175,7 +1175,7 @@ Skill Seekers MCP server supports 2 transport modes:
 ```bash
 # Start server manually (runs in background)
 cd /path/to/Skill_Seekers
-python3 -m skill_seekers.mcp.server --transport http --port 8765
+python3 -m skill_seekers.mcp.server_fastmcp --transport http --port 8765

 # Or use auto-start script
 ./scripts/start_mcp_server.sh
@@ -1326,7 +1326,7 @@ All agents have access to these 18 tools:
 lsof -i :8765

 # Use different port
-python3 -m skill_seekers.mcp.server --transport http --port 9000
+python3 -m skill_seekers.mcp.server_fastmcp --transport http --port 9000

 # Update agent config with new port
 ```
@@ -1348,7 +1348,7 @@ tail -f logs/mcp_server.log
 ```bash
 # Restart agent completely (quit and relaunch)
 # For HTTP transport, ensure server is running:
-ps aux | grep "skill_seekers.mcp.server"
+ps aux | grep "skill_seekers.mcp.server_fastmcp"

 # Test server directly
 curl http://localhost:8765/health
--- 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', {})
--- a/example-mcp-config.json
+++ b/example-mcp-config.json
@@ -1,11 +1,14 @@
 {
  "mcpServers": {
    "skill-seeker": {
-      "command": "python3",
+      "type": "stdio",
+      "command": "/path/to/your/Skill_Seekers/.venv/bin/python3",
      "args": [
-        "/mnt/1ece809a-2821-4f10-aecb-fcdf34760c0b/Git/Skill_Seekers/mcp/server.py"
+        "-m",
+        "skill_seekers.mcp.server_fastmcp"
      ],
-      "cwd": "/mnt/1ece809a-2821-4f10-aecb-fcdf34760c0b/Git/Skill_Seekers"
+      "cwd": "/path/to/your/Skill_Seekers",
+      "env": {}
    }
  }
 }
--- a/examples/http_transport_examples.sh
+++ b/examples/http_transport_examples.sh
@@ -12,57 +12,57 @@
 python -m skill_seekers.mcp.server_fastmcp

 # HTTP transport on default port 8000
-python -m skill_seekers.mcp.server_fastmcp --http
+python -m skill_seekers.mcp.server_fastmcp --transport http

 # =============================================================================
 # CUSTOM PORT
 # =============================================================================

 # HTTP transport on port 3000
-python -m skill_seekers.mcp.server_fastmcp --http --port 3000
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 3000

 # HTTP transport on port 8080
-python -m skill_seekers.mcp.server_fastmcp --http --port 8080
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 8080

 # =============================================================================
 # CUSTOM HOST
 # =============================================================================

 # Listen on all interfaces (⚠️ use with caution in production!)
-python -m skill_seekers.mcp.server_fastmcp --http --host 0.0.0.0
+python -m skill_seekers.mcp.server_fastmcp --transport http --host 0.0.0.0

 # Listen on specific interface
-python -m skill_seekers.mcp.server_fastmcp --http --host 192.168.1.100
+python -m skill_seekers.mcp.server_fastmcp --transport http --host 192.168.1.100

 # =============================================================================
 # LOGGING
 # =============================================================================

 # Debug logging
-python -m skill_seekers.mcp.server_fastmcp --http --log-level DEBUG
+python -m skill_seekers.mcp.server_fastmcp --transport http --log-level DEBUG

 # Warning level only
-python -m skill_seekers.mcp.server_fastmcp --http --log-level WARNING
+python -m skill_seekers.mcp.server_fastmcp --transport http --log-level WARNING

 # Error level only
-python -m skill_seekers.mcp.server_fastmcp --http --log-level ERROR
+python -m skill_seekers.mcp.server_fastmcp --transport http --log-level ERROR

 # =============================================================================
 # COMBINED OPTIONS
 # =============================================================================

 # HTTP on port 8080 with debug logging
-python -m skill_seekers.mcp.server_fastmcp --http --port 8080 --log-level DEBUG
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 8080 --log-level DEBUG

 # HTTP on all interfaces with custom port and warning level
-python -m skill_seekers.mcp.server_fastmcp --http --host 0.0.0.0 --port 9000 --log-level WARNING
+python -m skill_seekers.mcp.server_fastmcp --transport http --host 0.0.0.0 --port 9000 --log-level WARNING

 # =============================================================================
 # TESTING
 # =============================================================================

 # Start server in background and test health endpoint
-python -m skill_seekers.mcp.server_fastmcp --http --port 8765 &
+python -m skill_seekers.mcp.server_fastmcp --transport http --port 8765 &
 SERVER_PID=$!
 sleep 2
 curl http://localhost:8765/health | python -m json.tool
@@ -117,4 +117,4 @@ curl http://localhost:8000/health
 curl -v http://localhost:8000/health

 # Follow server logs
-python -m skill_seekers.mcp.server_fastmcp --http --log-level DEBUG 2>&1 | tee server.log
+python -m skill_seekers.mcp.server_fastmcp --transport http --log-level DEBUG 2>&1 | tee server.log
--- a/setup_mcp.sh
+++ b/setup_mcp.sh
@@ -20,6 +20,7 @@ NC='\033[0m' # No Color
 # Global variables
 REPO_PATH=$(pwd)
 PIP_INSTALL_CMD=""
+PYTHON_CMD=""  # Will be set after detecting venv
 HTTP_PORT=3000
 HTTP_AGENTS=()
 STDIO_AGENTS=()
@@ -60,6 +61,44 @@ echo "Step 2: Repository location"
 echo "Path: $REPO_PATH"
 echo ""

+# =============================================================================
+# STEP 2.5: DETECT VIRTUAL ENVIRONMENT
+# =============================================================================
+echo "Step 2.5: Detecting virtual environment..."
+
+# Check for existing venv
+if [ -d "$REPO_PATH/.venv" ]; then
+    VENV_PATH="$REPO_PATH/.venv"
+    echo -e "${GREEN}✓${NC} Found virtual environment: .venv"
+elif [ -d "$REPO_PATH/venv" ]; then
+    VENV_PATH="$REPO_PATH/venv"
+    echo -e "${GREEN}✓${NC} Found virtual environment: venv"
+elif [ -n "$VIRTUAL_ENV" ]; then
+    VENV_PATH="$VIRTUAL_ENV"
+    echo -e "${GREEN}✓${NC} Already in virtual environment: $VIRTUAL_ENV"
+else
+    VENV_PATH=""
+    echo -e "${YELLOW}⚠${NC} No virtual environment found"
+fi
+
+# Set Python command for MCP configuration
+if [ -n "$VENV_PATH" ]; then
+    PYTHON_CMD="$VENV_PATH/bin/python3"
+    if [ -f "$PYTHON_CMD" ]; then
+        VENV_PYTHON_VERSION=$($PYTHON_CMD --version 2>&1 | cut -d' ' -f2)
+        echo "  Using venv Python: $PYTHON_CMD"
+        echo "  Version: $VENV_PYTHON_VERSION"
+    else
+        echo -e "${RED}✗${NC} Virtual environment Python not found at $PYTHON_CMD"
+        echo "  Falling back to system python3"
+        PYTHON_CMD="python3"
+    fi
+else
+    PYTHON_CMD="python3"
+    echo "  Using system Python: $(which python3)"
+fi
+echo ""
+
 # =============================================================================
 # STEP 3: INSTALL DEPENDENCIES
 # =============================================================================
@@ -69,11 +108,19 @@ echo "Step 3: Installing Python dependencies..."
 if [[ -n "$VIRTUAL_ENV" ]]; then
    echo -e "${GREEN}✓${NC} Virtual environment detected: $VIRTUAL_ENV"
    PIP_INSTALL_CMD="pip install"
+    # Update PYTHON_CMD if not already set to venv Python
+    if [[ "$PYTHON_CMD" != "$VIRTUAL_ENV"* ]]; then
+        PYTHON_CMD="$VIRTUAL_ENV/bin/python3"
+        echo "  Using venv Python: $PYTHON_CMD"
+    fi
 elif [[ -d "venv" ]]; then
    echo -e "${YELLOW}⚠${NC} Virtual environment found but not activated"
    echo "Activating venv..."
    source venv/bin/activate
    PIP_INSTALL_CMD="pip install"
+    # Update PYTHON_CMD to use the activated venv
+    PYTHON_CMD="$REPO_PATH/venv/bin/python3"
+    echo -e "${GREEN}✓${NC} Using venv Python: $PYTHON_CMD"
 else
    echo -e "${YELLOW}⚠${NC} No virtual environment found"
    echo "It's recommended to use a virtual environment to avoid conflicts."
@@ -92,7 +139,10 @@ else
        if [[ -d "venv" ]]; then
            source venv/bin/activate
            PIP_INSTALL_CMD="pip install"
+            # Update PYTHON_CMD to use the newly created venv
+            PYTHON_CMD="$REPO_PATH/venv/bin/python3"
            echo -e "${GREEN}✓${NC} Virtual environment created and activated"
+            echo "  Using venv Python: $PYTHON_CMD"
        fi
    else
        echo "Proceeding with system install (using --user --break-system-packages)..."
@@ -106,8 +156,8 @@ read -p "Continue? (y/n) " -n 1 -r
 echo ""

 if [[ $REPLY =~ ^[Yy]$ ]]; then
-    echo "Installing package in editable mode..."
-    $PIP_INSTALL_CMD -e . || {
+    echo "Installing package with MCP dependencies in editable mode..."
+    $PIP_INSTALL_CMD -e ".[mcp]" || {
        echo -e "${RED}❌ Failed to install package${NC}"
        exit 1
    }
@@ -123,9 +173,13 @@ echo ""
 # =============================================================================
 echo "Step 4: Testing MCP server..."

+# Determine which Python to use for testing
+TEST_PYTHON="${PYTHON_CMD:-python3}"
+
 # Test stdio mode
 echo "  Testing stdio transport..."
-timeout 3 python3 -m skill_seekers.mcp.server_fastmcp 2>/dev/null || {
+echo "  Using: $TEST_PYTHON"
+timeout 3 $TEST_PYTHON -m skill_seekers.mcp.server_fastmcp 2>/dev/null || {
    if [ $? -eq 124 ]; then
        echo -e "  ${GREEN}✓${NC} Stdio transport working"
    else
@@ -136,9 +190,9 @@ timeout 3 python3 -m skill_seekers.mcp.server_fastmcp 2>/dev/null || {
 # Test HTTP mode
 echo "  Testing HTTP transport..."
 # Check if uvicorn is available
-if python3 -c "import uvicorn" 2>/dev/null; then
+if $TEST_PYTHON -c "import uvicorn" 2>/dev/null; then
    # Start HTTP server in background
-    python3 -m skill_seekers.mcp.server_fastmcp --http --port 8765 > /dev/null 2>&1 &
+    $TEST_PYTHON -m skill_seekers.mcp.server_fastmcp --transport http --port 8765 > /dev/null 2>&1 &
    HTTP_TEST_PID=$!
    sleep 2

@@ -349,11 +403,8 @@ sys.path.insert(0, 'src')
 from skill_seekers.mcp.agent_detector import AgentDetector
 detector = AgentDetector()

-# Determine server command based on install type
-if '$VIRTUAL_ENV':
-    server_command = 'python -m skill_seekers.mcp.server_fastmcp'
-else:
-    server_command = 'skill-seekers mcp'
+# Use the detected Python command
+server_command = '$PYTHON_CMD -m skill_seekers.mcp.server_fastmcp'

 config = detector.generate_config('$agent_id', server_command, $HTTP_PORT)
 print(config)
@@ -381,14 +432,18 @@ except:
 # Parse new config
 new = json.loads('''$GENERATED_CONFIG''')

-# Merge (add skill-seeker, preserve others)
+# Merge (add skill-seeker to GLOBAL mcpServers, preserve others)
+# Handle the structure: { \"mcpServers\": { ... }, \"/path/to/project\": { \"mcpServers\": { ... } } }
 if 'mcpServers' not in existing:
    existing['mcpServers'] = {}
+
+# Add/update skill-seeker in the global mcpServers section
 existing['mcpServers']['skill-seeker'] = new['mcpServers']['skill-seeker']

-# Write back
+# Write back with proper formatting
 with open('$config_path', 'w') as f:
    json.dump(existing, f, indent=2)
+    f.write('\n')  # Add trailing newline
 " 2>/dev/null || {
                            echo -e "  ${RED}✗${NC} Failed to merge config"
                            continue
@@ -450,7 +505,7 @@ if [ ${#SELECTED_AGENTS[@]} -gt 0 ]; then
                echo "Starting HTTP server on port $HTTP_PORT..."

                # Start server in background
-                nohup python3 -m skill_seekers.mcp.server_fastmcp --http --port $HTTP_PORT > /tmp/skill-seekers-mcp.log 2>&1 &
+                nohup $PYTHON_CMD -m skill_seekers.mcp.server_fastmcp --transport http --port $HTTP_PORT > /tmp/skill-seekers-mcp.log 2>&1 &
                SERVER_PID=$!

                sleep 2
@@ -471,10 +526,10 @@ if [ ${#SELECTED_AGENTS[@]} -gt 0 ]; then
            2)
                echo "Manual start command:"
                echo ""
-                echo -e "${GREEN}python3 -m skill_seekers.mcp.server_fastmcp --http --port $HTTP_PORT${NC}"
+                echo -e "${GREEN}$PYTHON_CMD -m skill_seekers.mcp.server_fastmcp --transport http --port $HTTP_PORT${NC}"
                echo ""
                echo "Or run in background:"
-                echo -e "${GREEN}nohup python3 -m skill_seekers.mcp.server_fastmcp --http --port $HTTP_PORT > /tmp/skill-seekers-mcp.log 2>&1 &${NC}"
+                echo -e "${GREEN}nohup $PYTHON_CMD -m skill_seekers.mcp.server_fastmcp --transport http --port $HTTP_PORT > /tmp/skill-seekers-mcp.log 2>&1 &${NC}"
                ;;
            3)
                echo "Skipping HTTP server start"
@@ -565,11 +620,14 @@ else
    echo -e "${GREEN}{"
    echo "  \"mcpServers\": {"
    echo "    \"skill-seeker\": {"
-    echo "      \"command\": \"python3\","
+    echo "      \"type\": \"stdio\","
+    echo "      \"command\": \"$PYTHON_CMD\","
    echo "      \"args\": ["
-    echo "        \"$REPO_PATH/src/skill_seekers/mcp/server_fastmcp.py\""
+    echo "        \"-m\","
+    echo "        \"skill_seekers.mcp.server_fastmcp\""
    echo "      ],"
-    echo "      \"cwd\": \"$REPO_PATH\""
+    echo "      \"cwd\": \"$REPO_PATH\","
+    echo "      \"env\": {}"
    echo "    }"
    echo "  }"
    echo -e "}${NC}"
@@ -580,7 +638,7 @@ else
        echo "${CYAN}For Cursor/Windsurf (HTTP):${NC}"
        echo ""
        echo "1. Start HTTP server:"
-        echo "   ${GREEN}python3 -m skill_seekers.mcp.server_fastmcp --http --port 3000${NC}"
+        echo "   ${GREEN}$PYTHON_CMD -m skill_seekers.mcp.server_fastmcp --transport http --port 3000${NC}"
        echo ""
        echo "2. Add to agent config:"
        echo -e "${GREEN}{"
@@ -644,10 +702,10 @@ echo "    - Cursor: ~/.cursor/logs/"
 echo "    - VS Code: ~/.config/Code/logs/"
 echo ""
 echo "  • Test MCP server:"
-echo "    ${CYAN}python3 -m skill_seekers.mcp.server_fastmcp${NC}"
+echo "    ${CYAN}$PYTHON_CMD -m skill_seekers.mcp.server_fastmcp${NC}"
 echo ""
 echo "  • Test HTTP server:"
-echo "    ${CYAN}python3 -m skill_seekers.mcp.server_fastmcp --http${NC}"
+echo "    ${CYAN}$PYTHON_CMD -m skill_seekers.mcp.server_fastmcp --transport http${NC}"
 echo "    ${CYAN}curl http://127.0.0.1:8000/health${NC}"
 echo ""
 echo "  • Run tests:"
--- a/src/skill_seekers/mcp/README.md
+++ b/src/skill_seekers/mcp/README.md
@@ -21,10 +21,11 @@ This MCP server allows Claude Code to use Skill Seeker's tools directly through

 ```bash
 # From repository root
-pip3 install -r mcp/requirements.txt
-pip3 install requests beautifulsoup4
+pip3 install -e ".[mcp]"
 ```

+**Note:** The `[mcp]` extra installs FastMCP and all required dependencies.
+
 ### 2. Quick Setup (Automated)

 ```bash
@@ -40,17 +41,20 @@ pip3 install requests beautifulsoup4

 ### 3. Manual Setup

-Add to `~/.config/claude-code/mcp.json`:
+Add to `~/.claude.json`:

 ```json
 {
  "mcpServers": {
    "skill-seeker": {
+      "type": "stdio",
      "command": "python3",
      "args": [
-        "/path/to/Skill_Seekers/mcp/server.py"
+        "-m",
+        "skill_seekers.mcp.server_fastmcp"
      ],
-      "cwd": "/path/to/Skill_Seekers"
+      "cwd": "/path/to/Skill_Seekers",
+      "env": {}
    }
  }
 }
--- a/src/skill_seekers/mcp/agent_detector.py
+++ b/src/skill_seekers/mcp/agent_detector.py
@@ -27,9 +27,9 @@ class AgentDetector:
            "name": "Claude Code",
            "transport": "stdio",
            "config_paths": {
-                "Linux": "~/.config/claude-code/mcp.json",
-                "Darwin": "~/Library/Application Support/Claude/mcp.json",
-                "Windows": "~\\AppData\\Roaming\\Claude\\mcp.json",
+                "Linux": "~/.claude.json",
+                "Darwin": "~/.claude.json",
+                "Windows": "~/.claude.json",
            },
        },
        "cursor": {
--- a/tests/test_setup_scripts.py
+++ b/tests/test_setup_scripts.py
@@ -62,9 +62,11 @@ class TestSetupMCPScript:
    def test_requirements_txt_path(self, script_content):
        """Test that script uses pip install -e . (v2.0.0 modern packaging)"""
        # v2.0.0 uses '-e .' (editable install) instead of requirements files
-        # The actual command is "$PIP_INSTALL_CMD -e ."
-        assert " -e ." in script_content or " -e." in script_content, (
-            "Should use '-e .' for editable install (modern packaging)"
+        # v2.7.0 PR #252 uses '-e ".[mcp]"' with MCP extra dependencies
+        # The actual command is "$PIP_INSTALL_CMD -e ." or "$PIP_INSTALL_CMD -e ".[mcp]""
+        has_editable = " -e ." in script_content or " -e." in script_content or '-e ".' in script_content
+        assert has_editable, (
+            "Should use '-e .' or '-e \".[mcp]\"' for editable install (modern packaging)"
        )

        # Should NOT reference old requirements.txt paths
@@ -121,9 +123,10 @@ class TestSetupMCPScript:
    def test_json_config_path_format(self, script_content):
        """Test that JSON config examples use correct format (v2.4.0 MCP 2025 upgrade)"""
        # MCP 2025 uses module import: python3 -m skill_seekers.mcp.server_fastmcp
-        # Config should show the server_fastmcp.py path for stdio examples
-        assert "server_fastmcp.py" in script_content, (
-            "Config should reference server_fastmcp.py (MCP 2025 upgrade)"
+        # v2.7.0 PR #252 uses module reference format, not file path
+        # Config should show the module reference: skill_seekers.mcp.server_fastmcp
+        assert "skill_seekers.mcp.server_fastmcp" in script_content, (
+            "Config should reference skill_seekers.mcp.server_fastmcp module (MCP 2025 upgrade)"
        )

    def test_no_hardcoded_paths(self, script_content):