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:

   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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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