agentic-debugger

An MCP (Model Context Protocol) server that enables interactive debugging with code instrumentation for AI coding assistants. Inspired by Cursor's debug mode.

Works with any MCP-compatible AI coding tool:

• Claude Code
• Cursor
• Windsurf
• Cline
• GitHub Copilot
• Kiro
• Zed
• And more...

Features

• Live code instrumentation - Inject debug logging at specific lines
• Variable capture - Log variable values at runtime
• Multi-language support - JavaScript, TypeScript, and Python
• Browser support - CORS-enabled for browser JS debugging
• Clean removal - Region markers ensure instruments are fully removed

Installation

Using npx (recommended)

Add to your MCP configuration:

{
  "mcpServers": {
    "debug": {
      "command": "npx",
      "args": ["-y", "agentic-debugger"]
    }
  }
}

Configuration file locations:

• Claude Code: ~/.mcp.json
• Cursor: .cursor/mcp.json in your project or ~/.cursor/mcp.json
• Other tools: Check your tool's MCP documentation

Global install

npm install -g agentic-debugger

Then configure:

{
  "mcpServers": {
    "debug": {
      "command": "agentic-debugger"
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | start_debug_session | Start HTTP server for log collection | | stop_debug_session | Stop server and cleanup | | add_instrument | Insert logging code at file:line | | remove_instruments | Remove debug code from file(s) | | list_instruments | Show all active instruments | | read_debug_logs | Read captured log data | | clear_debug_logs | Clear the log file |

How It Works

1. Start session - Spawns a local HTTP server (default port 9876)
2. Add instruments - Injects fetch() calls that POST to the server
3. Reproduce bug - Run your code, instruments capture variable values
4. Analyze logs - Read the captured data to identify issues
5. Cleanup - Remove all instruments and stop the server

Debug Workflow Example

You: "Help me debug why the total is NaN"

AI Assistant:
1. Starts debug session
2. Reads your code to understand the logic
3. Adds instruments at suspicious locations
4. "Please run your code to reproduce the issue"

You: *runs code* "Done"

AI Assistant:
5. Reads debug logs
6. "I see `discount` is undefined at line 15..."
7. Removes instruments
8. Fixes the bug
9. Stops debug session

Instrument Examples

JavaScript/TypeScript

// #region agentic-debug-abc123
fetch('http://localhost:9876/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'abc123',
    location: 'cart.js:15',
    timestamp: Date.now(),
    data: { total, discount, items }
  })
}).catch(() => {});
// #endregion agentic-debug-abc123

Python

# region agentic-debug-abc123
try:
    import urllib.request as __req, json as __json
    __req.urlopen(__req.Request(
        'http://localhost:9876/log',
        data=__json.dumps({
            'id': 'abc123',
            'location': 'cart.py:15',
            'timestamp': __import__('time').time(),
            'data': {'total': total, 'discount': discount}
        }).encode(),
        headers={'Content-Type': 'application/json'}
    ))
except: pass
# endregion agentic-debug-abc123

Supported Languages

| Language | Extensions | |----------|------------| | JavaScript | .js, .mjs, .cjs | | TypeScript | .ts, .tsx | | Python | .py |

Requirements

• Node.js >= 18.0.0
• An MCP-compatible AI coding assistant

License

MIT