Debug-MCP

# Using MCP Tool with VS Code Copilot This guide explains how to use this Python debugging MCP tool with GitHub Copilot in VS Code. ## Prerequisites - VS Code installed - GitHub Copilot extension installed - Python 3.11+ installed - This project set up ## Setup Instructions ### 1. Install the Project ```bash cd /path/to/Debug-MCP # Create virtual environment uv venv # Install dependencies uv pip install -e ".[dev,cli]" ``` ### 2. Configure MCP Server (Choose One Method) #### Method A: Workspace Configuration (Recommended for Project-Specific Setup) Create a `.vscode/mcp.json` file in your workspace: ```bash mkdir -p .vscode ``` Add the following configuration to `.vscode/mcp.json`: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` **After saving the file:** 1. VS Code will show commands in the editor to manage the server (Start/Stop/Restart) 2. Click the **"Add Server"** button that appears 3. VS Code will ask you to select the server type. Choose **"stdio"** (standard input/output) - **stdio**: Local process using stdin/stdout (our server uses this) - **http**: HTTP-based server (for remote services) - **sse**: Server-sent events (legacy support) 4. Enter the **Server ID**: ``` python-debug ``` (This can be any unique identifier you choose, but "python-debug" matches our configuration) 5. VS Code will prompt for the **command**. Enter: ``` uv ``` 6. VS Code will ask for **arguments**. Enter each argument separately: - First argument: `run` - Second argument: `python` - Third argument: `-m` - Fourth argument: `mcp_debug_tool.server` - Fifth argument: `--workspace` - Sixth argument: `${workspaceFolder}` Or you can enter all at once (space-separated): ``` run python -m mcp_debug_tool.server --workspace ${workspaceFolder} ``` 7. The server will be registered and ready to use **Note:** If you already have `.vscode/mcp.json` configured, VS Code should read the configuration automatically. You may not need to enter commands manually. Alternatively, you can also add the server via: - Command Palette → **"MCP: List Servers"** → **"+ Add Server"** → **"From Workspace Configuration"** #### Method B: Global Configuration (For All Workspaces) **For macOS/Linux:** ```bash mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat ``` **For Windows:** ```cmd mkdir %APPDATA%\Code\User\globalStorage\github.copilot-chat ``` Create or edit `mcp.json` in that directory: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "--directory", "/absolute/path/to/Debug-MCP", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` **Note:** - Use `--directory` to specify where the Debug-MCP project is installed - Use `${workspaceFolder}` for the workspace being debugged (the current project) - Change `/absolute/path/to/Debug-MCP` to your actual Debug-MCP installation path **Alternative using installed package:** If you installed Debug-MCP globally: ```bash # Install globally cd /absolute/path/to/Debug-MCP uv pip install -e . ``` Then use this simpler configuration: ```json { "mcpServers": { "python-debug": { "command": "python", "args": [ "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` #### Method C: Install from URL Use the MCP installation URL: ``` vscode:mcp/install?%7B%22name%22%3A%22python-debug%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22run%22%2C%22python%22%2C%22-m%22%2C%22mcp_debug_tool.server%22%2C%22--workspace%22%2C%22%24%7BworkspaceFolder%7D%22%5D%2C%22env%22%3A%7B%22PYTHONUNBUFFERED%22%3A%221%22%7D%7D ``` ### 3. Verify Installation 1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) 2. Run **"MCP: List Servers"** 3. You should see "python-debug" in the list 4. Right-click on it to **Start** the server if it's not running 5. Check the status - it should show "Running" 6. If there are errors, select **"Show Output"** to view logs ### 4. Restart VS Code Restart VS Code to ensure all changes are applied. ### 5. Enable the Server in Agent Mode 1. Open Copilot Chat in VS Code 2. Start a chat in **Agent Mode** (the mode where Copilot can use tools) 3. Click on the **Tools** icon or type `/tools` 4. Enable the **python-debug** server tools 5. You should see tools like: - `sessions.create` - `sessions.breakpoint` - `sessions.continue` - `sessions.state` - `sessions.end` ### 6. Use in Copilot Chat Open VS Code Copilot Chat and use the MCP tool as follows: #### Example 1: Start Debug Session ``` @workspace I want to debug src/main.py in this project. Use the sessions.create method to start a session with entry "src/main.py". ``` #### Example 2: Run to Breakpoint ``` @workspace In session [session-id], run to line 42 of src/main.py and show me the local variables at that point. ``` #### Example 3: Continue to Next Breakpoint ``` @workspace Continue session [session-id] and run to line 100 of src/main.py. ``` ## Available MCP Methods This tool provides the following MCP methods: ### `sessions.create` Create a new debug session. **Parameters:** ```json { "entry": "src/main.py", "args": ["--verbose"], "env": {"DEBUG": "true"} } ``` **Response:** ```json { "sessionId": "session-abc123", "entry": "src/main.py", "status": "created" } ``` ### `sessions.breakpoint` Run to the specified breakpoint. **Parameters:** ```json { "sessionId": "session-abc123", "file": "src/main.py", "line": 42 } ``` **Response:** ```json { "hit": true, "locals": { "x": "10", "name": "'Alice'", "items": "[1, 2, 3]" }, "frameInfo": { "file": "src/main.py", "line": 42, "function": "process_data" } } ``` ### `sessions.continue` Continue execution to the next breakpoint. **Parameters:** ```json { "sessionId": "session-abc123", "file": "src/main.py", "line": 100 } ``` ### `sessions.state` Get the current session state. **Parameters:** ```json { "sessionId": "session-abc123" } ``` **Response:** ```json { "sessionId": "session-abc123", "status": "paused", "entry": "src/main.py", "frameInfo": { "file": "src/main.py", "line": 42, "function": "process_data" } } ``` ### `sessions.end` End the debug session. **Parameters:** ```json { "sessionId": "session-abc123" } ``` ## Troubleshooting ### Server Won't Start / Shows Errors If the MCP server is registered but won't start: #### Step 1: Check Server Status 1. Command Palette → **"MCP: List Servers"** 2. Find "python-debug" in the list 3. Check the status indicator (should show "Running" when active) #### Step 2: View Error Logs 1. In the server list, select "python-debug" 2. Click **"Show Output"** or right-click → **"Show Output"** 3. Look for error messages in the output panel #### Step 3: Common Issues and Solutions **Problem: "Command not found: uv"** - Solution: Make sure `uv` is installed and in PATH ```bash which uv # If not found, install it: curl -LsSf https://astral.sh/uv/install.sh | sh ``` - Or change the command to use Python directly: ```json { "mcpServers": { "python-debug": { "command": "python", "args": ["-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}"] } } } ``` **Problem: "No module named 'mcp_debug_tool'"** - Solution: The project is not installed. Install it: ```bash cd /path/to/Debug-MCP uv pip install -e ".[dev,cli]" ``` **Problem: "Process exited with code 2"** - This usually means argument parsing error - Solution: Check that arguments are in an array format in the JSON: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` - **Important:** Each argument must be a separate string in the array - **Wrong:** `"args": "run python -m mcp_debug_tool.server"` - **Correct:** `"args": ["run", "python", "-m", "mcp_debug_tool.server", ...]` **Problem: "Permission denied"** - Solution: Make sure the command is executable: ```bash chmod +x $(which uv) ``` **Problem: "Workspace path not found"** - Solution: Make sure you opened VS Code in the Debug-MCP project directory - Or use an absolute path instead of `${workspaceFolder}`: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "python", "-m", "mcp_debug_tool.server", "--workspace", "/absolute/path/to/Debug-MCP" ] } } } ``` #### Step 4: Manual Start Test Test if the server works outside of VS Code: ```bash cd /path/to/Debug-MCP uv run python -m mcp_debug_tool.server --workspace . ``` The server should start and wait for input. Press `Ctrl+C` to stop. If this works, the issue is with the VS Code configuration. #### Step 5: Restart Server 1. Command Palette → **"MCP: List Servers"** 2. Right-click on "python-debug" 3. Select **"Restart"** Or use the code lens in `.vscode/mcp.json`: - Open `.vscode/mcp.json` - Click **"Restart"** above the server configuration #### Step 6: Remove and Re-add Server If restart doesn't work: 1. Command Palette → **"MCP: List Servers"** 2. Right-click on "python-debug" → **"Remove"** 3. Restart VS Code 4. Open `.vscode/mcp.json` (should be created with correct configuration) 5. Look for the **"Add Server"** button in the editor 6. Click it and follow the prompts 7. Or: Command Palette → **"MCP: List Servers"** → **"+ Add Server"** → **"From Workspace Configuration"** #### Step 7: Verify Configuration Format Make sure `.vscode/mcp.json` has this exact format: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` **Key points:** - `args` must be an array of strings - Each argument must be a separate string - Use `${workspaceFolder}` for the workspace path ### Can't See the "Add Server" Button If you don't see the "Add Server" button after creating `.vscode/mcp.json`: 1. Make sure the JSON is valid (check for syntax errors) 2. Close and reopen the file 3. Restart VS Code 4. Manually add the server: - Command Palette → **"MCP: List Servers"** - Click **"+ Add Server"** - Select **"From Workspace Configuration"** - Choose the **"stdio"** transport type ### Wrong Server Type Selected If you selected the wrong transport type: 1. Command Palette → **"MCP: List Servers"** 2. Right-click on "python-debug" 3. Select **"Remove"** 4. Add again and choose **"stdio"** ### Command Entry Issues If VS Code asks for the server information when adding manually: **1. Server ID:** ``` python-debug ``` (This must be unique. If you already have a server with this name, use something like `python-debug-v2`) **2. Command to enter:** ``` uv ``` **3. Arguments to enter (one per line or space-separated):** ``` run python -m mcp_debug_tool.server --workspace ${workspaceFolder} ``` Or as a single line: ``` run python -m mcp_debug_tool.server --workspace ${workspaceFolder} ``` **Important:** Make sure `uv` is in your PATH: ```bash which uv ``` If `uv` is not found, use the full path: ``` /path/to/uv ``` Or use the system Python directly: - **Command:** `python` - **Arguments:** `-m mcp_debug_tool.server --workspace ${workspaceFolder}` ### MCP Server Won't Start 1. Verify paths are correct: ```bash which uv which python ``` 2. Test by starting the server manually: ```bash cd /absolute/path/to/Debug-MCP uv run python -m mcp_debug_tool.server --workspace . ``` 3. Check logs: - Command Palette → **"MCP: List Servers"** - Select "python-debug" - Choose **"Show Output"** - Or: Select the error notification in Chat view → **"Show Output"** ### Tools Not Appearing in Agent Mode 1. Make sure the server is **started**: - Command Palette → **"MCP: List Servers"** - Verify status is "Running" 2. Enable tools in Agent Mode: - Open Copilot Chat - Click the **Tools** icon - Enable "python-debug" tools 3. Check tool permissions: - VS Code may ask for confirmation before running tools - Make sure to allow the tools when prompted ### Session Timeout The default timeout is 20 seconds. For long-running code, you can adjust it with environment variables: ```json { "mcpServers": { "python-debug": { "env": { "PYTHONUNBUFFERED": "1", "DEBUG_TIMEOUT": "60" } } } } ``` ### Path Not Found Use absolute paths instead of relative paths: ```json { "sessionId": "session-123", "file": "/absolute/path/to/Debug-MCP/src/main.py", "line": 42 } ``` ## Usage Examples ## Usage Examples ### Using in a Different Project If you want to use this MCP tool to debug a **different Python project**, you have two options: #### Option 1: Global Configuration (Recommended) Set up the MCP server globally so it's available in all workspaces: 1. **Create global configuration:** ```bash mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat ``` 2. **Edit the global `mcp.json`:** ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "--directory", "/absolute/path/to/Debug-MCP", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` 3. **Open your other project in VS Code** 4. **The MCP tool will now debug files in that project** **How it works:** - `--directory /path/to/Debug-MCP`: Tells `uv` where the Debug-MCP tool is installed - `--workspace ${workspaceFolder}`: Tells the debugger to work with the currently open project #### Option 2: Per-Project Configuration Create a `.vscode/mcp.json` in each project where you want to use the debugger: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": [ "run", "--directory", "/absolute/path/to/Debug-MCP", "python", "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` #### Option 3: Install as System Package For the cleanest setup, install Debug-MCP as a system-wide Python package: ```bash # In the Debug-MCP directory cd /absolute/path/to/Debug-MCP pip install -e . # or uv pip install -e . ``` Then use this simpler global configuration: ```json { "mcpServers": { "python-debug": { "command": "python", "args": [ "-m", "mcp_debug_tool.server", "--workspace", "${workspaceFolder}" ], "env": { "PYTHONUNBUFFERED": "1" } } } } ``` Now you can debug any Python project from any directory! ### Complete Debug Workflow ``` User: @workspace There's a bug in src/buggy_script.py. Set a breakpoint at line 15 and check the variable values. Copilot: First, I'll create a debug session... [calls sessions.create] Session session-xyz created. Running code to line 15... [calls sessions.breakpoint] Paused at line 15. Found the following variables: - counter: 0 - result: [] - data: [1, 2, 3, 4, 5] The counter is still 0. This might be the source of the bug. User: I see. Can you also check line 30? Copilot: Continuing execution to line 30... [calls sessions.continue] Paused at line 30: - counter: 5 - result: [2, 4, 6, 8, 10] It appears to be working correctly here. ``` ## References - [MCP Specification](https://spec.modelcontextprotocol.io/) - [VS Code Copilot Documentation](https://docs.github.com/en/copilot) - [Project README](../README.md) - [API Specification](../specs/001-python-debug-tool/spec.md)