Extend options for Claude MCP integration + Clarify to which extent the instructions have been tested

Author: ndaelman-hu

templates/README.md

@@ -4,19 +4,49 @@ This folder contains MCP server configuration templates for different editors an
 
 ## Quick Setup
 
-### VS Code
+### VS Code (verified)
 1. Copy `vscode-mcp.json` to `.vscode/mcp.json` in your project root
 2. Start the server either directly from the file (toggles appear above the server name) or the Extensions icon (right-click on the server)
 3. Use Agent mode in Copilot Chat to access parse-patrol tools
 
-### Claude Desktop
+### Claude Desktop (experimental)
+
+**Option 1: Project-scoped (Recommended)**
+```bash
+# From your parse-patrol project directory
+# First ensure dependencies are installed
+uv sync --extra mcp
+
+# Add the MCP server - use absolute path to ensure correct environment
+claude mcp add parse-patrol --scope project -- sh -c "cd $(pwd) && PYTHONPATH=src uv --project $(pwd) run python -m parse_patrol"
+
+# Alternative: Use the venv python directly
+# claude mcp add parse-patrol --scope project -- sh -c "cd $(pwd) && PYTHONPATH=src $(pwd)/.venv/bin/python -m parse_patrol"
+```
+
+**Environment Issues:**
+- The `claude mcp add` command may run in a different `uv` environment than your project
+- Using `--project $(pwd)` ensures `uv` uses the correct project environment
+- Alternatively, use the venv Python directly: `.venv/bin/python`
+
+**Option 2: Manual configuration**
 1. Copy `claude-desktop-mcp.json` content to your Claude Desktop configuration file:
    - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-2. Restart Claude Desktop
-3. Tools will be available in Claude Desktop conversations
-
-### Neovim (with MCP support)
+   - **Linux/Ubuntu**: `~/.config/Claude/claude_desktop_config.json`
+2. **Important**: Update `/path/to/parse-patrol` with your actual project path
+3. Restart Claude Desktop
+
+**Troubleshooting Claude MCP:**
+- **Environment mismatch**: If "No module named 'mcp'" error, the `uv` environment differs from your project
+  - Use `uv --project $(pwd) run` or direct venv path: `.venv/bin/python`
+  - Test manually: `cd /your/project && PYTHONPATH=src uv run python -m parse_patrol`
+- **Connection closed**: Server starts but immediately closes
+  - Check dependencies: `uv sync --extra mcp`
+  - Verify imports work: `PYTHONPATH=src uv run python -c "import parse_patrol.__main__"`
+- **Server doesn't sync**: Try restarting Claude Desktop after adding the server
+
+### Neovim (with MCP support) (experimental)
 1. Copy `neovim-mcp.json` to your Neovim MCP configuration location
 2. Configure according to your MCP plugin requirements
 
@@ -78,4 +108,4 @@ uv sync --extra mcp
 1. **"No module named 'mcp'" error**: Install MCP dependencies with `uv sync --extra mcp`
 2. **"No module named parse_patrol" error**: Ensure `PYTHONPATH` is set correctly in the configuration
 3. **Server won't start**: Check that `uv` is installed and the path is correct
-4. **Import errors**: Ensure you're using `python -m parse_patrol` (module syntax) not direct file paths
+4. **Import errors**: Ensure you're using `uv run python -m parse_patrol` (module syntax) not direct file paths