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:

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

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:

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:

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:

stop_debugging

Description: Stop the current debugging session

Parameters:

• sessionId (string, optional): Optional session ID to stop a specific session

Example:

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:

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

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