🔔 Important Notices
1. Timeout Error Fix (v0.2.0+)
Fixed the timeout issue that occurred when starting the debug session. The connection to VSCode instances is now more stable with improved heartbeat and retry mechanisms.
2. Use @latest Tag for Installation
When configuring MCP, always include the @latest tag to ensure you're using the most recent version:
"args": [
"-y",
"@uhd_kr/mcp-debug-tools@latest"
],
A bridge solution that enables AI tools (Cursor, Windsurf, etc.) to access VSCode's debugging capabilities. Connects Model Context Protocol (MCP) with Debug Adapter Protocol (DAP) to allow AI to perform debugging tasks.
📺 Demo Video: AI-Powered Debugging in Action
Watch how MCP Debug Tools enables AI assistants to perform complex debugging tasks across multiple Node.js projects simultaneously. This demonstration showcases real-time variable inspection, multi-threaded debugging, and automated breakpoint management through natural language commands.
[Loading...GIF]
(click go to Youtube)
⚠️ Beta Testing
Currently in beta testing. Please report any issues or feedback.
Contact: yoo.hwanyong@gmail.com
🎯 Key Features
Debug Control
- Breakpoint Management: Add/remove conditional breakpoints, bulk operations
- Execution Control: Start/stop debug, continue/pause, Step Into/Over/Out
- Variable Inspection: Check values, evaluate expressions, scope analysis
- Stack Tracing: Call stack, thread management, exception information
Auto-Connection System
- Automatic VSCode instance discovery and connection
- Multiple VSCode windows support
- Workspace-based configuration management
- Real-time heartbeat monitoring
📦 Installation
1. VSCode Extension (Required)
Provides debugging capabilities as a server in VSCode.
Method 1: VSCode Marketplace
1. Open VSCode Extensions tab (Ctrl+Shift+X)
2. Search for "MCP Debug Tools"
3. Click Install
Method 2: Direct Link
Method 3: Download Link
Client that connects AI tools with VSCode.
# Run directly with npx (no installation needed)
npx @uhd_kr/mcp-debug-tools
🔧 Configuration
MCP Setup (Cursor/Windsurf)
Add to mcp.json or configuration file:
{
"mcpServers": {
"dap-proxy": {
"command": "npx",
"args": ["-y", "@uhd_kr/mcp-debug-tools@latest"],
"env": {}
}
}
}
CLI Options
# Auto-connect (recommended)
npx @uhd_kr/mcp-debug-tools
# Specify port
npx @uhd_kr/mcp-debug-tools --port=8891
# Disable auto-discovery
npx @uhd_kr/mcp-debug-tools --no-auto
🛠️ Supported Features
Breakpoint Management
add-breakpoint - Add breakpoint with conditional supportadd-breakpoints - Add multiple breakpoints at onceremove-breakpoint - Remove specific breakpointclear-breakpoints - Clear all/specific file breakpointslist-breakpoints - List all breakpoints
Debug Control
start-debug - Start debug sessionstop-debug - Stop debug sessioncontinue - Continue executionstep-over - Step over linestep-into - Step into functionstep-out - Step out of functionpause - Pause execution
State Inspection
get-debug-state - Debug session stateevaluate-expression - Evaluate expressioninspect-variable - Variable detailsget-variables-scope - All variables in scopeget-call-stack - Call stack informationget-thread-list - Thread listget-exception-info - Exception information
Configuration Management
list-debug-configs - List launch.json configurationsselect-debug-config - Select debug configuration
Workspace Management
select-vscode-instance - Select VSCode instancelist-vscode-instances - List active instancesget-workspace-info - Workspace information
dap-log://current - DAP protocol message logdebug://breakpoints - Current breakpoint informationdebug://active-session - Active debug session infodebug://console - Debug console outputdebug://call-stack - Call stack informationdebug://variables-scope - Variable scope information
🏗️ Architecture
┌─────────────┐ HTTP ┌─────────────┐ stdio ┌─────────────┐
│ VSCode │ ◄────────► │ CLI Tool │ ◄────────► │ AI Tool │
│ Extension │ (8890) │ │ │ (Cursor) │
└─────────────┘ └─────────────┘ └─────────────┘
Auto-Connection Mechanism
- Workspace Config:
.mcp-debug-tools/config.json - Stores VSCode connection info
- Global Registry:
~/.mcp-debug-tools/active-configs.json - Tracks all active instances
- Heartbeat: 5-second interval liveness updates
- PID Verification: Process status checking
🚀 Getting Started
- Install VSCode Extension
- Open project in VSCode
- Add to AI tool's MCP configuration
- Use debugging commands in AI tool
💡 Common Use Cases
1. Finding and Fixing Bugs
Ask your AI assistant to help debug your code:
"There's an error in my calculateTotal function. Can you set breakpoints
at the start of the function and step through to find the issue?"
The AI will:
- Set breakpoints in the problematic function
- Start debug session
- Step through code line by line
- Inspect variables to identify the bug
- Suggest fixes based on the debugging data
2. Understanding Complex Code Flow
When exploring unfamiliar codebases:
"I need to understand how the authentication flow works. Can you trace
through the login process step by step?"
The AI will:
- Identify key authentication functions
- Set strategic breakpoints
- Run through the authentication flow
- Explain each step with actual runtime data
- Show how data transforms through the process
3. Validating Data Processing
For data transformation pipelines:
"Please verify that my data transformation pipeline correctly processes
the input array and produces the expected output format"
The AI will:
- Set breakpoints at transformation stages
- Inspect input data structure
- Monitor data changes at each step
- Validate output against requirements
- Identify any data integrity issues
Finding performance issues:
"My application is running slowly. Can you help identify which functions
are taking the most time during execution?"
The AI will:
- Set breakpoints at function entry/exit points
- Monitor execution flow
- Identify functions called frequently
- Suggest optimization opportunities
- Highlight potential bottlenecks
5. Exception Handling Analysis
Debugging runtime errors:
"My app crashes with an unhandled exception. Can you catch it and show
me the exact state when it occurs?"
The AI will:
- Monitor for exceptions
- Capture exception details and stack trace
- Show variable states at crash point
- Analyze the root cause
- Suggest error handling improvements
6. Test-Driven Debugging
Debugging failing tests:
"My unit test is failing. Can you debug the test execution and show me
why the assertion fails?"
The AI will:
- Run tests in debug mode
- Break at test assertions
- Compare expected vs actual values
- Trace back to the source of discrepancy
- Suggest test or code fixes
🤖 AI Agent Integration Guide
For AI developers and users who want to leverage MCP Debug Tools in their AI-powered development workflows, we provide a comprehensive rules document that helps AI agents use these debugging tools effectively.
This document contains essential guidelines and patterns for AI agents to:
- Understand the proper sequence of debugging operations
- Handle common debugging scenarios efficiently
- Recover from errors gracefully
- Follow best practices for performance and safety
How to Use
For AI Tool Users (Cursor, Windsurf, etc.)
For Custom AI Agent Development
- Use the rules document as a reference for implementing debugging workflows
- Incorporate the sequential operation patterns into your agent's logic
- Follow the error recovery strategies for robust debugging automation
Key Sections to Reference
- Prerequisites Check: Ensure environment is ready before debugging
- Tool Categories: Understand the 5 main tool categories and their purposes
- Sequential Operations: Follow the proper order of debugging operations
- Common Workflows: Pre-built patterns for typical debugging scenarios
- Error Recovery: Handle failures and recover gracefully
Benefits of Following the Rules
- ✅ Reduced Errors: Proper tool sequencing prevents common mistakes
- ✅ Efficient Debugging: Optimized workflows save time and resources
- ✅ Better AI Assistance: AI can provide more accurate debugging help
- ✅ Consistent Results: Standardized patterns ensure reliable outcomes
Example AI-Assisted Debugging Session
User: "Help me find why my function returns undefined"
AI (using rules):
1. First, I'll check available VSCode instances (list-vscode-instances)
2. Set a breakpoint at the function start (add-breakpoint)
3. Start debug session (start-debug)
4. When paused, inspect all variables (get-variables-scope)
5. Step through to find where undefined is introduced (step-over)
6. Suggest the fix based on findings
For the complete rules and patterns, see MCP_DEBUG_TOOLS_RULES.md
📊 Current Limitations
- Real-time sync limited by MCP protocol constraints
🔮 Future Plans
- Remote debugging
- Performance profiling tools
🐛 Troubleshooting
CLI Can't Find VSCode
- Verify VSCode Extension is active
- Check
.mcp-debug-tools/config.json exists
- Try manual connection with
--port option
Multiple VSCode Windows
- CLI auto-selects based on current directory
- Use
list-vscode-instances to check active instances
- Use
select-vscode-instance to choose specific instance
📄 License
GNU General Public License v3.0 - LICENSE
🤝 Contributing
Issues and Pull Requests welcome!
📚 References
Enjoy debugging with AI! 🚀
