DebugMCP - Empowering AI Agents with Multi-Language Debugging Capabilities

A VSCode extension that provides comprehensive multi-language debugging capabilities and automatically exposes itself as an MCP (Model Context Protocol) server for seamless integration with AI assistants.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Supported Languages
• Configuration
• Troubleshooting
• Contributing
• License

Overview

DebugMCP bridges the gap between professional debugging and AI-assisted development by providing a powerful debugging interface that AI assistants can use to help you identify and fix issues in your code. DebugMCP enables AI assistants to perform sophisticated debugging operations on your behalf.

📢 Beta Version Notice: This is a beta version of DebugMCP maintained by ozzafar@microsoft.com. We welcome feedback and contributions to help improve this extension.

Features

🔧 Tools

Tool	Description	Parameters	Example Usage
start_debugging	Start a debug session for a source code file	filePath (required) workingDirectory (optional) configurationName (optional)	Start debugging a Python script
stop_debugging	Stop the current debug session	None	End the current debugging session
step_over	Execute the next line (step over function calls)	None	Move to next line without entering functions
step_into	Step into function calls	None	Enter function calls to debug them
step_out	Step out of the current function	None	Exit current function and return to caller
continue_execution	Continue until next breakpoint	None	Resume execution until hitting a breakpoint
restart_debugging	Restart the current debug session	None	Restart debugging from the beginning
add_breakpoint	Add a breakpoint at a specific line	filePath (required) line (required)	Set breakpoint at line 25 of main.py
remove_breakpoint	Remove a breakpoint from a specific line	filePath (required) line (required)	Remove breakpoint from line 25
list_breakpoints	List all active breakpoints	None	Show all currently set breakpoints
get_debug_status	Get current debug session status	None	Check if debugging session is active
get_variables	Get variables and their values	scope (optional: 'local', 'global', 'all')	Inspect local variables
evaluate_expression	Evaluate an expression in debug context	expression (required)	Evaluate user.name or len(items)

🎯 Debugging Best Practices

DebugMCP follows systematic debugging practices for effective issue resolution:

• Start with Entry Points: Begin debugging at function entry points or main execution paths
• Follow the Execution Flow: Use step-by-step execution to understand code flow
• Root Cause Analysis: Don't stop at symptoms - find the underlying cause

🛡️ Security & Reliability

• Secure Communication: All MCP communications use secure protocols
• Local Operation: The MCP server runs 100% locally with no external communications and requires no credentials
• State Validation: Robust validation of debugging states and operations

Installation

VSCode Marketplace

1. Open VSCode
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "DebugMCP"
4. Click Install
5. The extension automatically activates and registers as an MCP server

Verification

After installation, you should see:

• DebugMCP extension in your installed extensions
• MCP server automatically running on port 3001 (configurable)
• Debug tools available to connected AI assistants

📝 Note: No additional debugging rule instructions are needed - the extension works out of the box.

💡 Tip: Enable auto-approval for all debugmcp tools in your AI assistant to create seamless debugging workflows without constant approval interruptions.

Quick Start

1. Install the extension (see Installation)
2. Open your project in VSCode
3. Ask your AI to debug - it can now set breakpoints, start debugging, and analyze your code!

Supported Languages

DebugMCP supports debugging for the following languages with their respective VSCode extensions:

Language	Extension Required	File Extensions	Status
Python	Python	.py	✅ Fully Supported
JavaScript/TypeScript	Built-in / JS Debugger	.js, .ts, .jsx, .tsx	✅ Fully Supported
Java	Extension Pack for Java	.java	✅ Fully Supported
C/C++	C/C++	.c, .cpp, .h, .hpp	✅ Fully Supported
Go	Go	.go	✅ Fully Supported
Rust	rust-analyzer	.rs	✅ Fully Supported
PHP	PHP Debug	.php	✅ Fully Supported
Ruby	Ruby	.rb	✅ Fully Supported
C#/.NET	C#	.cs	✅ Fully Supported

Configuration

MCP Server Configuration (Recommended)

The extension runs an MCP server automatically. It will pop up a message to auto-register the MCP server in your AI assistant.

Manual MCP Server Registration (Optional)

Cline

Add to your Cline settings or cline_mcp_settings.json:

{
  "mcpServers": {
    "debugmcp": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

Add to your Copilot workspace settings (.vscode/settings.json):

{
  "github.copilot.mcp.servers": {
    "debugmcp": {
      "type": "sse",
      "url": "http://localhost:3001/sse",
      "description": "DebugMCP - Multi-language debugging support"
    }
  }
}

Roo Code

Add to Roo's MCP settings:

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "sse",
        "url": "http://localhost:3001/sse",
        "description": "DebugMCP - Debugging tools for AI assistants"
      }
    }
  }
}

Extension Settings

Configure DebugMCP behavior in VSCode settings:

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180
}

Setting	Default	Description
debugmcp.serverPort	3001	Port number for the MCP server
debugmcp.timeoutInSeconds	180	Timeout for debugging operations

Troubleshooting

Common Issues

MCP Server Not Starting

• Symptom: AI assistant can't connect to DebugMCP
• Solution:
  • Check if port 3001 is available
  • Restart VSCode
  • Verify extension is installed and activated

How It Works

Launch Configuration Integration

The extension handles debug configurations intelligently:

• Existing launch.json: If a .vscode/launch.json file exists, it will:

  • Search for a relevant configuration
  • Use a specific configuration if found

• Default Configuration: If no launch.json exists or no relevant config, it creates an appropriate default configurations for each language based on file extension detection

Requirements

• VSCode with appropriate language extensions installed:
  • Python: Python extension for .py files
  • JavaScript/TypeScript: Built-in Node.js debugger or JavaScript Debugger extension
  • Java: Extension Pack for Java
  • C#/.NET: C# extension
  • C/C++: C/C++ extension
  • Go: Go extension
  • Rust: rust-analyzer extension
  • PHP: PHP Debug extension
  • Ruby: Ruby extension with debug support
• MCP-compatible AI assistant (Copilot, Cline, Roo..)

Demo

Watch to see DebugMCP in action, showing the integration between the VSCode extension and an AI assistant using the MCP protocol.

Development

To build the extension:

npm install
npm run compile

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Security

Security vulnerabilities should be reported following the guidance at https://aka.ms/SECURITY.md. Please do not report security vulnerabilities through public GitHub issues.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

License

MIT License - See LICENSE for details