MCP Debugger Tools

# MCP Debugger Tools VSCode extension that exposes debugging capabilities via Model Context Protocol (MCP), enabling AI agents to programmatically control VSCode's debugger. ## Features The extension provides the following 4 MCP tools: 1. **add_breakpoint** - Add a breakpoint to a specific file and line number 2. **remove_breakpoint** - Remove a breakpoint from a specific file and line number 3. **start_debugging** - Start debugging with a specific configuration 4. **stop_debugging** - Stop the current debugging session ## Installation & Setup 1. **Clone and build the extension:** ```bash git clone <repository-url> cd vscode-mcp-debugger npm install npm run compile ``` 2. **Install the extension in VSCode:** - Press `F5` to run in Extension Development Host, or - Package as VSIX: `vsce package` and install manually 3. **Verify the MCP server is available:** - Open VSCode Command Palette (`Cmd+Shift+P`) - Run "MCP: List Servers" - You should see "MCP Debugger Tools" listed 4. **Enable in AI Chat:** - Open AI Chat in VSCode - Click the tools icon or type `/` to see available tools - You should see the 4 debugging tools available ## Usage with AI Agents Once installed, AI agents can use these tools to: - **Set breakpoints** in your code at specific lines - **Start debugging sessions** using your launch configurations - **Remove breakpoints** when no longer needed - **Stop debugging** to clean up resources ### Communication Architecture The extension uses a unique architecture to bridge the MCP protocol with VSCode's debugging APIs: ``` AI Agent → MCP Server → Temp File IPC → VSCode Extension → VSCode Debug API ↑ ↓ JSON Response ← Response File ← Debug API Result ``` **How it works:** 1. **AI Agent** calls MCP tools (add_breakpoint, start_debugging, etc.) 2. **MCP Server** (standalone Node.js process) receives the tool calls 3. **File-based IPC** - Server writes command requests to temporary files 4. **VSCode Extension** monitors temp directory and processes commands 5. **VSCode Debug API** - Extension uses native VSCode debugging capabilities 6. **Response cycle** - Results flow back through the same IPC mechanism This architecture ensures the MCP server runs independently while having full access to VSCode's debugging features. ### Example AI Agent Workflow ``` AI: I'll help you debug the issue in your calculator function. 1. First, let me add a breakpoint at the start of the function: [Uses add_breakpoint tool with filePath and lineNumber] 2. Now I'll start debugging with your launch configuration: [Uses start_debugging tool] 3. After analyzing the execution, I'll clean up: [Uses remove_breakpoint and stop_debugging tools] ``` ## MCP Tools Reference ### add_breakpoint **Description:** Add a breakpoint to a specific file and line number **Parameters:** - `filePath` (string, required): Absolute path to the file - `lineNumber` (number, required): Line number (1-based) - `condition` (string, optional): Conditional expression for the breakpoint **Example:** ```json { "filePath": "/path/to/your/file.js", "lineNumber": 25, "condition": "x > 10" } ``` ### remove_breakpoint **Description:** Remove a breakpoint from a specific file and line number **Parameters:** - `filePath` (string, required): Absolute path to the file - `lineNumber` (number, required): Line number (1-based) **Example:** ```json { "filePath": "/path/to/your/file.js", "lineNumber": 25 } ``` ### start_debugging **Description:** Start debugging with a specific configuration **Parameters:** - `configurationName` (string, optional): Name of the debug configuration to use - `workspaceFolderPath` (string, optional): Path to the workspace folder **Example:** ```json { "configurationName": "Launch Node.js Program", "workspaceFolderPath": "/path/to/workspace" } ``` ### stop_debugging **Description:** Stop the current debugging session **Parameters:** - `sessionId` (string, optional): Optional session ID to stop a specific session **Example:** ```json { "sessionId": "debug-session-123" } ``` ## Requirements - **VSCode** with MCP support (latest version recommended) - **Node.js** (v18+ for running the MCP server) - **Project workspace** with debug configurations in `.vscode/launch.json` - **Extension Development Host** (for development/testing) ## Supported Platforms - ✅ **macOS** - Fully tested and supported - ✅ **Linux** - Compatible with file-based IPC - ✅ **Windows** - Should work with standard temp directory - ⚠️ **WSL** - May require additional configuration for file permissions ## Debug Configuration Setup Create a `.vscode/launch.json` file in your project: ```json { "version": "0.2.0", "configurations": [ { "name": "Launch Node.js Program", "type": "node", "request": "launch", "program": "${workspaceFolder}/src/index.js", "console": "integratedTerminal" } ] } ``` ## Development ### Building from Source - **Install dependencies:** `npm install` - **Compile TypeScript:** `npm run compile` - **Watch for changes:** `npm run watch` for automatic compilation - **Testing:** Use the Extension Development Host (F5) - **Debugging:** Set breakpoints in the extension code itself ### Project Structure ``` src/ ├── extension.ts # Main extension entry point & MCP registration ├── debugBridge.ts # VSCode Debug API wrapper ├── mcpServer.ts # Standalone MCP server (stdio transport) ├── integratedMcpServer.ts # Alternative integrated server implementation └── vscodeDebuggerMcp.ts # Legacy server implementation ``` ### Key Components - **Extension.ts**: Registers MCP server definition, monitors IPC files - **DebugBridge.ts**: Provides clean interface to VSCode debugging APIs - **mcpServer.ts**: Standalone MCP server that communicates via file IPC - **IPC System**: File-based communication between processes ### Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test with Extension Development Host 5. Submit a pull request Please ensure all tools work correctly and add appropriate error handling. ## Troubleshooting ### Common Issues 1. **Tools not visible:** - Check that MCP server is running via "MCP: List Servers" - Verify the extension is active in Extension Development Host - Look for "MCP Debugger Tools" in the MCP servers list 2. **Breakpoints not working:** - Ensure file paths are absolute and files exist - Check that the file is currently open or can be opened in VSCode - Verify the line number is valid (1-based indexing) 3. **Debug config errors:** - Verify `.vscode/launch.json` exists and is valid - Ensure the specified configuration name exists - Check that the workspace folder is correctly detected 4. **IPC communication issues:** - Check VSCode Developer Console for error messages - Verify temp directory permissions (the extension uses OS temp directory) - Look for MCP server stderr output in "MCP: List Servers" → Show Output ### Debug Mode Enable detailed logging by checking the MCP server output: 1. Open Command Palette (`Cmd+Shift+P`) 2. Run "MCP: List Servers" 3. Select "MCP Debugger Tools" 4. Click "Show Output" to see server logs ### Technical Details - **MCP Server Process**: Runs as standalone Node.js process via stdio transport - **Extension Process**: Runs within VSCode extension host - **IPC Mechanism**: Temporary JSON files in OS temp directory - **Response Timeout**: 10 seconds (configurable in source code) - **File Cleanup**: Automatic cleanup of temporary IPC files ## License MIT