agentic-debugger

# 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: ```json { "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 ```bash npm install -g agentic-debugger ``` Then configure: ```json { "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 ```javascript // #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 ```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