MCP Debugger for VS Code

AI-powered debugging for VS Code with multi-language support. Integrates with GitHub Copilot and AI agents through Model Context Protocol. Debug JavaScript, TypeScript, Python, Java, C/C++, Go, Rust, PHP, Ruby, and more via Debug Adapter Protocol.

Note: The VS Code extension supports all languages via Debug Adapter Protocol. The standalone MCP server (for use with AI agents outside VS Code) supports Node.js/JavaScript only via Chrome DevTools Protocol.

🔗 Repository

This package is now maintained in its own repository: https://github.com/Digital-Defiance/vscode-mcp-debugger

This repository is part of the AI Capabilitites Suite on GitHub.

Features

🐛 Advanced Debugging

VS Code Extension: Multi-language support via Debug Adapter Protocol (JavaScript, TypeScript, Python, C/C++, Java, Go, Rust, PHP, Ruby, and more)
Standalone MCP Server: Node.js/JavaScript debugging via Chrome DevTools Protocol
Smart Breakpoints: AI-suggested breakpoint locations based on code analysis
Conditional Breakpoints: Break only when specific conditions are met
Hang Detection: Automatically detect infinite loops and hanging processes (Node.js only)
Source Map Support: Debug TypeScript and other transpiled languages with full source map integration
Code Lens: Inline breakpoint suggestions at functions, loops, and error handlers

📊 Performance Profiling

CPU Profiling: Identify performance bottlenecks
Memory Profiling: Take heap snapshots and detect memory leaks
Performance Timeline: Track execution events and timing

🤖 AI Integration

GitHub Copilot Ready: Works seamlessly with GitHub Copilot
MCP Protocol: Exposes debugging capabilities to AI agents
Smart Suggestions: AI-powered debugging recommendations

🧪 Test Framework Support

VS Code Extension: Jest, Mocha, Vitest (JS/TS), pytest (Python), JUnit (Java), go test (Go), cargo test (Rust), and more
Standalone MCP Server: Jest, Mocha, Vitest (Node.js only)

🎨 Language Server Protocol (LSP) Features

Code Intelligence

Hover Information: Hover over variables to see debugging instructions and inspection tips
Signature Help: Real-time parameter hints for all debugger functions with documentation
Inlay Hints: Inline type annotations showing return types (session-id, breakpoint-id, variable types)
Document Symbols: Outline view showing debug sessions, breakpoints, inspections, and hang detections
Semantic Tokens: Syntax highlighting for debugger functions and variables

Code Actions (4 features)

Convert console.log to breakpoint: Transform logging statements into proper breakpoints with watch expressions
Remove console.log: Clean up debugging statements
Wrap in try-catch: Add error handling around risky operations (e.g., JSON.parse)
Add hang detection: Insert hang detection comments for infinite loops

Navigation & Hierarchy

Call Hierarchy: Visualize debugger function dependencies and call relationships
Type Hierarchy: Explore debugger type relationships (DebugSession, Breakpoint, StackFrame, Variable)
Document Links: Quick links to debugger documentation
Go to Definition: Navigate to debugger function definitions

Code Editing

Folding Ranges: Collapse/expand debug session blocks
Selection Ranges: Smart selection expansion for debugger code
Linked Editing: Simultaneously edit related debugger identifiers
Color Provider: Visual severity indicators for diagnostics

Diagnostics & Validation

Infinite Loop Detection: Warns about while(true) patterns with hang detection suggestions
Missing Error Handling: Suggests try-catch for operations like JSON.parse
Console.log Hints: Recommends using breakpoints instead of console.log for debugging
Real-time Validation: Instant feedback as you type

Installation

From VS Code Marketplace

Open VS Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Search for "MCP Debugger"
Click Install

Install the MCP Debugger Server

The extension requires the MCP debugger server to function. Install it globally:

npm install -g @ai-capabilities-suite/mcp-debugger-server

Or install it in your project:

npm install --save-dev @ai-capabilities-suite/mcp-debugger-server

From VSIX File

code --install-extension ts-mcp-debugger-1.0.0.vsix

Quick Start

1. Start Debugging

Option A: Use Command Palette

Open any source code file (JavaScript, TypeScript, Python, Java, etc.)
Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
Type "MCP Debugger: Start Debug Session"
Press Enter

Option B: Use Debug Configuration

Open the Debug view (Ctrl+Shift+D / Cmd+Shift+D)
Click "create a launch.json file"
Select "MCP Node.js Debugger"
Press F5 to start debugging

2. Detect Hangs

Open a file that might have infinite loops
Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
Type "MCP Debugger: Detect Hanging Process"
View hang detection results

3. Set Smart Breakpoints

Place cursor on a line
Right-click and select "MCP Debugger: Set Smart Breakpoint"
Choose from AI-suggested breakpoint locations

Configuration

Settings

Configure the extension in VS Code settings (Ctrl+, / Cmd+,):

{
  "mcp-debugger.serverPath": "",
  "mcp-debugger.autoStart": true,
  "mcp-debugger.defaultTimeout": 30000,
  "mcp-debugger.enableHangDetection": true,
  "mcp-debugger.hangDetectionTimeout": 5000,
  "mcp-debugger.enableProfiling": false,
  "mcp-debugger.logLevel": "info"
}

Launch Configurations

Add to .vscode/launch.json:

Debug Current File

{
  "type": "mcp-node",
  "request": "launch",
  "name": "MCP Debug Current File",
  "program": "${file}",
  "cwd": "${workspaceFolder}",
  "enableHangDetection": true
}

Debug with Profiling

{
  "type": "mcp-node",
  "request": "launch",
  "name": "MCP Debug with Profiling",
  "program": "${workspaceFolder}/index.js",
  "cwd": "${workspaceFolder}",
  "enableProfiling": true,
  "enableHangDetection": true
}

Debug Jest Tests

{
  "type": "mcp-node",
  "request": "launch",
  "name": "MCP Debug Jest",
  "program": "${workspaceFolder}/node_modules/.bin/jest",
  "args": ["--runInBand"],
  "cwd": "${workspaceFolder}",
  "enableHangDetection": true
}

Commands

Command	Description	Shortcut
`MCP Debugger: Start Debug Session`	Start debugging current file	-
`MCP Debugger: Detect Hanging Process`	Detect infinite loops	-
`MCP Debugger: Set Smart Breakpoint`	Set AI-suggested breakpoint	-
`MCP Debugger: Start CPU Profiling`	Start CPU profiler	-
`MCP Debugger: Take Heap Snapshot`	Take memory snapshot	-

LSP Commands (Available via MCP Protocol)

Command	Description
`mcp.debugger.start`	Start debug session via MCP
`mcp.debugger.setBreakpoint`	Set breakpoint via MCP
`mcp.debugger.continue`	Resume execution
`mcp.debugger.stepOver`	Step over current line
`mcp.debugger.stepInto`	Step into function
`mcp.debugger.stepOut`	Step out of function
`mcp.debugger.pause`	Pause execution
`mcp.debugger.inspect`	Inspect variable
`mcp.debugger.getStack`	Get call stack
`mcp.debugger.detectHang`	Detect hanging process
`mcp.debugger.profileCPU`	Start CPU profiling
`mcp.debugger.profileMemory`	Take memory snapshot

LSP Features in Action

Code Lens Breakpoint Suggestions

The extension automatically suggests breakpoints at strategic locations:

function processData(items) {  // 🔴 Set Breakpoint
  for (let i = 0; i < items.length; i++) {  // 🔍 Debug Loop
    try {
      const result = transform(items[i]);
      results.push(result);
    } catch (error) {  // ⚠️ Debug Error Handler
      console.error(error);
    }
  }
}

Signature Help

Get real-time parameter hints as you type:

debugger_start(
  // ↓ Shows: command: string, args?: string[], cwd?: string, timeout?: number
  'node',
  ['app.js'],
  '/path/to/project',
  30000
);

Inlay Hints

See return types inline:

const session = debugger_start('node', ['test.js']);  // → session-id
const bp = debugger_set_breakpoint(session, 'test.js', 10);  // → breakpoint-id
const value = debugger_inspect(session, 'user.age');  // → number

Code Actions

Quick fixes appear automatically:

// Before: console.log statement with hint
console.log(user.name);  // 💡 Consider using breakpoints instead

// Quick Fix 1: Convert to breakpoint
// Watch: user.name
debugger; // Breakpoint - inspect user.name

// Quick Fix 2: Remove console.log
// (statement removed)

Diagnostics

Real-time warnings and suggestions:

// ⚠️ Warning: Potential infinite loop detected
while (true) {
  // Consider using hang detection
}

// ℹ️ Info: Consider wrapping in try-catch
const data = JSON.parse(input);

Call Hierarchy

Visualize function dependencies:

debugger_continue
  ↓ depends on
  debugger_set_breakpoint
    ↓ depends on
    debugger_start

Type Hierarchy

Explore type relationships:

Object
  ├── Breakpoint
  ├── StackFrame
  └── Variable

EventEmitter
  └── DebugSession

Usage Examples

Example 1: Debug a Node.js Application

// app.js
function calculateSum(numbers) {
  let sum = 0;
  for (let i = 0; i < numbers.length; i++) {
    sum += numbers[i];
  }
  return sum;
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result);

Open app.js
Set a breakpoint on line 3 (inside the loop)
Press F5 to start debugging
Step through the code with F10 (Step Over)
Inspect variables in the Debug sidebar

Example 2: Detect an Infinite Loop

// hang.js
function infiniteLoop() {
  let i = 0;
  while (true) {
    i++;
    // This will hang forever
  }
}

infiniteLoop();

Open hang.js
Run "MCP Debugger: Detect Hanging Process"
View hang detection results showing the infinite loop location

Example 3: Profile Performance

// slow.js
function slowFunction() {
  let result = 0;
  for (let i = 0; i < 1000000; i++) {
    result += Math.sqrt(i);
  }
  return result;
}

slowFunction();

Open slow.js
Start debugging with profiling enabled
Run "MCP Debugger: Start CPU Profiling"
Let the code execute
View CPU profile to identify bottlenecks

GitHub Copilot Integration

The MCP Debugger works seamlessly with GitHub Copilot for AI-assisted debugging:

Debugging Context: Copilot can access debugging information
Smart Suggestions: Get AI-powered debugging recommendations
Breakpoint Suggestions: Copilot suggests optimal breakpoint locations
Error Analysis: Copilot helps analyze errors and exceptions
Autonomous Debugging: Copilot can debug code automatically

Quick Start with Copilot

Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
Ask: "Debug this file and find the bug"
Copilot will automatically use the MCP Debugger tools

Example Conversations

You: "Debug this function and tell me why it returns undefined"
Copilot: [Starts debug session, sets breakpoints, inspects variables, explains issue]

You: "Check if this script has an infinite loop"
Copilot: [Uses hang detection, identifies loop location, suggests fix]

You: "Why is this function so slow?"
Copilot: [Profiles code, identifies bottlenecks, suggests optimizations]

Learn More

See the Copilot Integration Guide for:

Detailed setup instructions
Complete debugging workflows
Example conversations
Tips and best practices
Troubleshooting guide

LSP Features for AI Agents

The Language Server Protocol integration enables AI agents to:

1. Understand Code Context

Access document symbols to identify debug sessions and breakpoints
Use semantic tokens to understand debugger-specific syntax
Navigate type hierarchies to understand debugger data structures

2. Provide Intelligent Suggestions

Suggest breakpoints at optimal locations using code lens
Recommend quick fixes for common debugging patterns
Offer signature help for correct debugger function usage

3. Validate Code

Detect infinite loops and suggest hang detection
Identify missing error handling
Warn about inefficient debugging practices (console.log)

4. Navigate Code

Use call hierarchy to understand debugger function dependencies
Follow document links to relevant documentation
Navigate type hierarchies for debugger types

Example: AI Agent Using LSP Features

// AI agent analyzes code using LSP
// 1. Gets document symbols → finds existing breakpoints
// 2. Uses call hierarchy → understands function dependencies
// 3. Checks diagnostics → identifies infinite loop warning
// 4. Suggests code action → adds hang detection
// 5. Provides signature help → shows correct parameters

// AI's suggestion:
const session = debugger_start('node', ['app.js'], process.cwd(), 30000);
const result = debugger_detect_hang('node', ['app.js'], 5000, 100);
if (result.hung) {
  console.log(`Hang detected at ${result.location}`);
}

Troubleshooting

MCP Server Not Starting

Problem: Extension shows "MCP Debugger server not running"

Solution:

Check if Node.js is installed: node --version
Install MCP server: npm install -g @ai-capabilities-suite/mcp-debugger-server
Set custom server path in settings if needed
Restart VS Code

Breakpoints Not Working

Problem: Breakpoints are not being hit

Solution:

Ensure source maps are enabled for TypeScript
Check that file paths are absolute
Verify the program is actually executing the code
Try setting a breakpoint on the first line

Hang Detection False Positives

Problem: Hang detection reports hangs for legitimate long-running operations

Solution:

Increase mcp-debugger.hangDetectionTimeout in settings
Disable hang detection for specific debug sessions
Use conditional breakpoints instead

Performance Issues

Problem: Debugging is slow

Solution:

Disable profiling if not needed
Reduce number of breakpoints
Increase timeout values
Close other VS Code extensions

Requirements

VS Code: Version 1.85.0 or higher
Operating System: Windows, macOS, or Linux
For VS Code Extension (Multi-Language):
- JavaScript/TypeScript: Node.js 16.x or higher
- Python: Python 3.x with debugpy extension
- Java: JDK with Java Debug Server extension
- C/C++: GDB or LLDB with C/C++ extension
- Go: Go toolchain with delve extension
- Rust: Rust toolchain with CodeLLDB extension
- Other languages: Install appropriate VS Code debug extension
For Standalone MCP Server (Node.js Only):
- Node.js: 16.x or higher
- JavaScript/TypeScript: Full support with source maps

Extension Settings

This extension contributes the following settings:

mcp-debugger.serverPath: Path to MCP debugger server executable
mcp-debugger.autoStart: Automatically start MCP server when VS Code opens
mcp-debugger.defaultTimeout: Default timeout for debug operations (ms)
mcp-debugger.enableHangDetection: Enable automatic hang detection
mcp-debugger.hangDetectionTimeout: Timeout for hang detection (ms)
mcp-debugger.enableProfiling: Enable performance profiling features
mcp-debugger.logLevel: Log level (debug, info, warn, error)

Known Issues

WebSocket connections may timeout on slow networks
Source maps must be inline or in the same directory for TypeScript/transpiled languages
Some Node.js native modules may not be debuggable
VS Code Extension: Language-specific features depend on installed debug adapters
Standalone MCP Server: Only supports Node.js/JavaScript debugging (Python, Java, etc. not supported)
Hang detection and profiling: Node.js only (not available for other languages)

Release Notes

1.5.0

Major LSP update:

13 new LSP features for enhanced code intelligence
Code Actions: Convert console.log to breakpoints, add try-catch, remove logging
Signature Help: Real-time parameter hints for all debugger functions
Inlay Hints: Inline type annotations for return values
Document Symbols: Outline view for debug sessions and breakpoints
Semantic Tokens: Syntax highlighting for debugger code
Call Hierarchy: Visualize function dependencies
Type Hierarchy: Explore debugger type relationships
Diagnostics: Real-time validation with infinite loop detection
Code Lens: Inline breakpoint suggestions
Document Links: Quick access to documentation
Folding Ranges: Collapse/expand debug blocks
Selection Ranges: Smart selection expansion
Linked Editing: Simultaneous identifier editing
Color Provider: Visual severity indicators
80+ comprehensive tests for LSP features
E2E testing for all LSP capabilities

1.0.0

Initial release:

Advanced debugging with MCP integration
Hang detection
CPU and memory profiling
Smart breakpoint suggestions
GitHub Copilot integration
Test framework support (Jest, Mocha, Vitest)

Contributing

Found a bug or have a feature request? Please open an issue on GitHub.

License

MIT License - see LICENSE file for details.

More Information

Enjoy debugging with AI! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
.yarn		.yarn
images		images
src		src
.gitignore		.gitignore
.vscodeignore		.vscodeignore
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
COPILOT-GUIDE.md		COPILOT-GUIDE.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
package.json		package.json
project.json		project.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

Digital-Defiance/vscode-mcp-debugger

Folders and files

Latest commit

History

Repository files navigation

MCP Debugger for VS Code

🔗 Repository

Features

🐛 Advanced Debugging

📊 Performance Profiling

🤖 AI Integration

🧪 Test Framework Support

🎨 Language Server Protocol (LSP) Features

Code Intelligence

Code Actions (4 features)

Navigation & Hierarchy

Code Editing

Diagnostics & Validation

Installation

From VS Code Marketplace

Install the MCP Debugger Server

From VSIX File

Quick Start

1. Start Debugging

2. Detect Hangs

3. Set Smart Breakpoints

Configuration

Settings

Launch Configurations

Debug Current File

Debug with Profiling

Debug Jest Tests

Commands

LSP Commands (Available via MCP Protocol)

LSP Features in Action

Code Lens Breakpoint Suggestions

Signature Help

Inlay Hints

Code Actions

Diagnostics

Call Hierarchy

Type Hierarchy

Usage Examples

Example 1: Debug a Node.js Application

Example 2: Detect an Infinite Loop

Example 3: Profile Performance

GitHub Copilot Integration

Quick Start with Copilot

Example Conversations

Learn More

LSP Features for AI Agents

1. Understand Code Context

2. Provide Intelligent Suggestions

3. Validate Code

4. Navigate Code

Example: AI Agent Using LSP Features

Troubleshooting

MCP Server Not Starting

Breakpoints Not Working

Hang Detection False Positives

Performance Issues

Requirements

Extension Settings

Known Issues

Release Notes

1.5.0

1.0.0

Contributing

License

More Information

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages