Compatible platform for the VSCode debugging extension with file-based IPC
Fully tested and supported platform for the VSCode debugging extension with file-based IPC
Enables running debugging sessions with Node.js applications through VSCode's debugging API
Provides debugging capabilities for TypeScript code, allowing for setting breakpoints and controlling debug sessions
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:
- Install the extension in VSCode:
- Press
F5
to run in Extension Development Host, or - Package as VSIX:
vsce package
and 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:
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
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:
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:
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:
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
- 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.json
exists 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
This server cannot be installed
A VSCode extension that enables AI agents to programmatically control VSCode's debugging features through the Model Context Protocol (MCP).
Related MCP Servers
- -securityAlicense-qualityEnables AI agents and assistants like Goose or Claude to interact with VS Code through the Model Context Protocol.Last updated -14TypeScriptApache 2.0
- -securityAlicense-qualityAn implementation of the Model Context Protocol (MCP) that enables interaction with debug adapters, allowing language models to control debuggers, set breakpoints, evaluate expressions, and navigate source code during debugging sessions.Last updated -2PythonAGPL 3.0
- AsecurityAlicenseAqualityMCP Server for the Peacock extension for VS Code (https://peacockcode.dev), coloring your world, one Code editor at a time. The main goal of the project is to show how an MCP server can be used to interact with APIs.Last updated -1391TypeScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server that helps AI coding assistants identify critical design issues in code, rather than just focusing on cosmetic problems when asked to improve code.Last updated -1874TypeScriptMIT License