Content
# 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.
[](https://marketplace.visualstudio.com/items?itemName=uhd.mcp-debug-tools)
[](https://www.npmjs.com/package/@uhd_kr/mcp-debug-tools)
## 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
```bash
# 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**.
```bash
# 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](mailto: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](https://marketplace.visualstudio.com/items?itemName=uhd.mcp-debug-tools)
**Method 3: Download Link**
- [Releases](https://github.com/hwanyong/mcp-debug-tools/releases)
### 2. CLI Tool
Client that connects AI tools with VSCode.
```bash
# 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:
```json
{
"mcpServers": {
"dap-proxy": {
"command": "npx",
"args": ["-y", "@uhd_kr/mcp-debug-tools@latest"],
"env": {}
}
}
}
```
### CLI Options
```bash
# 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:**
```bash
node ~/.vscode/extensions/uhd.mcp-debug-tools-*/out/cli.js <command> [args]
```
**Windows (PowerShell):**
```powershell
node "$env:USERPROFILE\.vscode\extensions\uhd.mcp-debug-tools-*\out\cli.js" <command> [args]
```
**Windows (CMD):**
```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`](./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`](./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](https://github.com/hwanyong/mcp-debug-tools/blob/main/LICENSE)
## 🤝 Contributing
Issues and Pull Requests welcome!
## 📚 References
- [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [VSCode Extension API](https://code.visualstudio.com/api)
---
**Enjoy debugging with AI! 🚀**
Connection Info
You Might Also Like
No recommendations available