MCP Debug Tools

The bridge between AI Agents and VS Code Debugger — Let your AI assistant set breakpoints, step through code, and inspect variables in real-time.

Why MCP Debug Tools?

Traditional AI coding assistants can read and write code, but they can't debug it. MCP Debug Tools removes this limitation by giving AI agents direct access to VS Code's debugger through simple CLI commands.

Without MCP Debug Tools	With MCP Debug Tools
AI guesses at bugs from code reading	AI sets breakpoints and inspects live runtime state
"Try adding a console.log here"	AI steps through code line-by-line automatically
Manual copy-paste of error messages	AI reads call stacks and variable values as JSON

💡 Direct CLI Control — Works Without MCP Connection

Beyond the standard MCP proxy, you can execute debugging actions via one-off terminal commands — no persistent connection required.

• Terminal AI Friendly: Shell-based AI agents interact with the debugger directly
• Zero Connection Overhead: No need to configure or maintain an MCP server connection
• Easy Parsing: Results in pure JSON (stdout), logs separated to stderr — AI parses instantly
• Scriptable: Integrate VS Code debugging into automated bash scripts seamlessly

# Discover all available tools
npx @uhd_kr/mcp-debug-tools list

# Execute tools directly
npx @uhd_kr/mcp-debug-tools call add-breakpoint '{"file": "src/app.ts", "line": 15}'
npx @uhd_kr/mcp-debug-tools call step-over

🚀 What's New in v1.0.0

🤖 AI Agent Skill Auto-Injection

The extension now automatically injects skill documents into your workspace when activated, so AI agents can discover and use debugging tools without any manual configuration.

AI Platform	Auto-detected Path	Status
Gemini (Google)	.gemini/skills/dap-cli-debugging/SKILL.md	✅ Supported
Claude Code (Anthropic)	.claude/skills/dap-cli-debugging/SKILL.md	✅ Supported

🔌 Offline CLI Support

Run the CLI directly from the VS Code extension's install path — no internet or npx required.

# macOS / Linux
node ~/.vscode/extensions/uhd.mcp-debug-tools-*/out/cli.js call get-active-session

# Windows (PowerShell)
node "$env:USERPROFILE\.vscode\extensions\uhd.mcp-debug-tools-*\out\cli.js" call get-active-session

📖 Comprehensive Tool Documentation

All 29 debugging tools are now fully documented in the auto-injected skill file, organized by category with parameters and usage examples.

⚠️ 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

• MCP Debug Tools on VSCode Marketplace

Method 3: Download Link

• Releases

2. CLI Tool

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

Local Path Fallback (When npx is unavailable)

If npx is unavailable (e.g., offline environment, network restrictions), you can run the CLI directly from the VS Code extension's install directory.

macOS / Linux:

node ~/.vscode/extensions/uhd.mcp-debug-tools-*/out/cli.js <command> [args]

Windows (PowerShell):

node "$env:USERPROFILE\.vscode\extensions\uhd.mcp-debug-tools-*\out\cli.js" <command> [args]

Windows (CMD):

node "%USERPROFILE%\.vscode\extensions\uhd.mcp-debug-tools-*\out\cli.js" <command> [args]

Tip: If you installed mcp-debug-tools globally via npm install -g @uhd_kr/mcp-debug-tools, you can simply run mcp-debug-tools <command> directly without npx.

🛠️ Supported Features

MCP Tools (Executable Commands)

Breakpoint Management

• add-breakpoint - Add breakpoint with conditional support
• add-breakpoints - Add multiple breakpoints at once
• remove-breakpoint - Remove specific breakpoint
• clear-breakpoints - Clear all/specific file breakpoints
• list-breakpoints - List all breakpoints

Debug Control

• start-debug - Start debug session
• stop-debug - Stop debug session
• continue - Continue execution
• step-over - Step over line
• step-into - Step into function
• step-out - Step out of function
• pause - Pause execution

State Inspection

• get-debug-state - Debug session state
• evaluate-expression - Evaluate expression
• inspect-variable - Variable details
• get-variables-scope - All variables in scope
• get-call-stack - Call stack information
• get-thread-list - Thread list
• get-exception-info - Exception information

Configuration Management

• list-debug-configs - List launch.json configurations
• select-debug-config - Select debug configuration

Workspace Management

• select-vscode-instance - Select VSCode instance
• list-vscode-instances - List active instances
• get-workspace-info - Workspace information

MCP Resources (Read-only Information)

• dap-log://current - DAP protocol message log
• debug://breakpoints - Current breakpoint information
• debug://active-session - Active debug session info
• debug://console - Debug console output
• debug://call-stack - Call stack information
• debug://variables-scope - Variable scope information

🏗️ Architecture

┌─────────────┐    HTTP    ┌─────────────┐    stdio   ┌─────────────┐
│   VSCode    │ ◄────────► │  CLI Tool   │ ◄────────► │ AI Tool     │
│  Extension  │   (8890)   │             │            │ (Cursor)    │
└─────────────┘            └─────────────┘            └─────────────┘

Auto-Connection Mechanism

1. Workspace Config: .mcp-debug-tools/config.json - Stores VSCode connection info
2. Global Registry: ~/.mcp-debug-tools/active-configs.json - Tracks all active instances
3. Heartbeat: 5-second interval liveness updates
4. PID Verification: Process status checking

🚀 Getting Started

1. Install VSCode Extension
2. Open project in VSCode
3. Add to AI tool's MCP configuration
4. 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

4. Performance Bottleneck Detection

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

Using MCP Debug Tools with AI Assistants

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.

MCP_DEBUG_TOOLS_RULES.md

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

1. For AI Tool Users (Cursor, Windsurf, etc.)

   • Include the rules document in your AI assistant's context when debugging
   • Copy relevant sections from MCP_DEBUG_TOOLS_RULES.md into your prompts
   • Example prompt:

     I need to debug my Node.js application. Please follow the MCP Debug Tools
     rules for proper tool sequencing and error handling.
     [Paste relevant sections from MCP_DEBUG_TOOLS_RULES.md]
     

2. 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

3. 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

1. Verify VSCode Extension is active
2. Check .mcp-debug-tools/config.json exists
3. 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

• Debug Adapter Protocol
• Model Context Protocol
• VSCode Extension API

---

Enjoy debugging with AI! 🚀