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:
- add_breakpoint - Add a breakpoint to a specific file and line number
- remove_breakpoint - Remove a breakpoint from a specific file and line number
- start_debugging - Start debugging with a specific configuration
- stop_debugging - Stop the current debugging session
Installation & Setup
-
Clone and build the extension:
git clone <repository-url> cd vscode-mcp-debugger npm install npm run compile -
Install the extension in VSCode:
- Press
F5to run in Extension Development Host, or - Package as VSIX:
vsce packageand install manually
- Press
-
Verify the MCP server is available:
- Open VSCode Command Palette (
Cmd+Shift+P) - Run "MCP: List Servers"
- You should see "MCP Debugger Tools" listed
- Open VSCode Command Palette (
-
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:
- AI Agent calls MCP tools (add_breakpoint, start_debugging, etc.)
- MCP Server (standalone Node.js process) receives the tool calls
- File-based IPC - Server writes command requests to temporary files
- VSCode Extension monitors temp directory and processes commands
- VSCode Debug API - Extension uses native VSCode debugging capabilities
- 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 filelineNumber(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 filelineNumber(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 useworkspaceFolderPath(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 watchfor 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
- Fork the repository
- Create a feature branch
- Make your changes
- Test with Extension Development Host
- Submit a pull request
Please ensure all tools work correctly and add appropriate error handling.
Troubleshooting
Common Issues
-
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
-
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)
-
Debug config errors:
- Verify
.vscode/launch.jsonexists and is valid - Ensure the specified configuration name exists
- Check that the workspace folder is correctly detected
- Verify
-
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:
- Open Command Palette (
Cmd+Shift+P) - Run "MCP: List Servers"
- Select "MCP Debugger Tools"
- 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