{"id":29651219,"url":"https://github.com/zackradisic/mcpdbg","last_synced_at":"2025-07-22T05:06:06.291Z","repository":{"id":303886928,"uuid":"1015662730","full_name":"zackradisic/mcpdbg","owner":"zackradisic","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-09T23:25:15.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T09:22:05.265Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zackradisic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T21:09:53.000Z","updated_at":"2025-07-09T23:25:18.000Z","dependencies_parsed_at":"2025-07-10T09:22:08.699Z","dependency_job_id":"e292909f-dcde-45a8-850e-5f19e12d5c50","html_url":"https://github.com/zackradisic/mcpdbg","commit_stats":null,"previous_names":["zackradisic/mcpdbg"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zackradisic/mcpdbg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackradisic%2Fmcpdbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackradisic%2Fmcpdbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackradisic%2Fmcpdbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackradisic%2Fmcpdbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zackradisic","download_url":"https://codeload.github.com/zackradisic/mcpdbg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackradisic%2Fmcpdbg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266430677,"owners_count":23927169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T05:06:05.620Z","updated_at":"2025-07-22T05:06:06.262Z","avatar_url":"https://github.com/zackradisic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Debugger Bridge\n\nA bridge between AI agents using the Model Context Protocol (MCP) and the VS Code debugger, specifically targeting CodeLLDB for C++, Rust, Zig, and other compiled languages.\n\n## Architecture\n\nThis project consists of two main components:\n\n1. **VS Code Extension** (`vscode-extension/`): Acts as a bridge between VS Code's debugger and the MCP server\n2. **MCP Server** (`mcp-server/`): Exposes debugger functionality to AI agents via MCP\n\n```\n┌─────────────┐     MCP Protocol      ┌─────────────┐     WebSocket      ┌──────────────┐     DAP      ┌──────────┐\n│  AI Agent   │◄──────────────────────►│ MCP Server  │◄──────────────────►│ VS Code Ext  │◄────────────►│ CodeLLDB │\n└─────────────┘                        └─────────────┘                     └──────────────┘              └──────────┘\n```\n\n## Setup\n\n### Prerequisites\n\n- VS Code with CodeLLDB extension installed\n- Node.js and npm\n- Bun runtime\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd mcp-debugger\n```\n\n2. Install VS Code Extension dependencies:\n```bash\ncd vscode-extension\nnpm install\n```\n\n3. Install MCP Server dependencies:\n```bash\ncd ../mcp-server\nbun install\n```\n\n### Running the Extension\n\n1. Open the `vscode-extension` folder in VS Code\n2. Press F5 to launch a new VS Code window with the extension loaded\n3. The extension will start a WebSocket server on port 8080\n\n### Running the MCP Server\n\n```bash\ncd mcp-server\nbun run src/index.ts\n```\n\n## WebSocket Protocol Reference\n\nThe VS Code extension and MCP server communicate using JSON messages over WebSocket.\n\n### Request Messages (MCP Server → Extension)\n\n#### Execute LLDB Command\n```json\n{\n  \"type\": \"request\",\n  \"command\": \"executeLldbCommand\",\n  \"lldb_command\": \"register read\",\n  \"id\": \"unique-request-id\"\n}\n```\n\n#### Get Stack Trace\n```json\n{\n  \"type\": \"request\",\n  \"command\": \"getStackTrace\",\n  \"threadId\": 1,\n  \"id\": \"unique-request-id\"\n}\n```\n\n#### Get Variables\n```json\n{\n  \"type\": \"request\",\n  \"command\": \"getVariables\",\n  \"variablesReference\": 1000,\n  \"id\": \"unique-request-id\"\n}\n```\n\n### Response Messages (Extension → MCP Server)\n\n#### Execute LLDB Command Response\n```json\n{\n  \"type\": \"response\",\n  \"command\": \"executeLldbCommand\",\n  \"success\": true,\n  \"result\": \"rax = 0x0000000000000001\",\n  \"id\": \"unique-request-id\"\n}\n```\n\n#### Get Stack Trace Response\n```json\n{\n  \"type\": \"response\",\n  \"command\": \"getStackTrace\",\n  \"success\": true,\n  \"stackFrames\": [\n    {\n      \"id\": 0,\n      \"name\": \"main\",\n      \"source\": {\n        \"path\": \"/path/to/file.cpp\"\n      },\n      \"line\": 42,\n      \"column\": 5\n    }\n  ],\n  \"id\": \"unique-request-id\"\n}\n```\n\n#### Get Variables Response\n```json\n{\n  \"type\": \"response\",\n  \"command\": \"getVariables\",\n  \"success\": true,\n  \"variables\": [\n    {\n      \"name\": \"x\",\n      \"value\": \"42\",\n      \"type\": \"int\",\n      \"variablesReference\": 0\n    }\n  ],\n  \"id\": \"unique-request-id\"\n}\n```\n\n### Event Messages (Extension → MCP Server)\n\n#### Debugger Stopped Event\n```json\n{\n  \"type\": \"event\",\n  \"event\": \"debuggerStopped\",\n  \"reason\": \"breakpoint\",\n  \"threadId\": 1,\n  \"description\": \"Stopped at breakpoint 1.1\",\n  \"allThreadsStopped\": true\n}\n```\n\n#### Debugger Continued Event\n```json\n{\n  \"type\": \"event\",\n  \"event\": \"debuggerContinued\",\n  \"threadId\": 1,\n  \"allThreadsContinued\": true\n}\n```\n\n## MCP Tools Reference\n\nThe MCP server exposes the following tools to AI agents:\n\n### debugger_executeLldbCommand\nExecute a raw LLDB command.\n\n**Parameters:**\n- `command` (string, required): The LLDB command to execute\n\n**Example:**\n```json\n{\n  \"command\": \"thread backtrace\"\n}\n```\n\n### debugger_readRegisters\nRead CPU registers.\n\n**Parameters:** None\n\n### debugger_readMemory\nRead memory at a specific address.\n\n**Parameters:**\n- `address` (string, required): Memory address to read from\n- `count` (number, optional): Number of bytes to read (default: 64)\n\n**Example:**\n```json\n{\n  \"address\": \"0x7fff5fbff8c0\",\n  \"count\": 128\n}\n```\n\n### debugger_listStackFrames\nList the current stack frames.\n\n**Parameters:**\n- `threadId` (number, optional): Thread ID (uses current thread if not specified)\n\n### debugger_listVariables\nList variables in a specific scope.\n\n**Parameters:**\n- `variablesReference` (number, required): Variables reference from a stack frame\n\n### debugger_getState\nGet the current debugger state.\n\n**Parameters:** None\n\n**Returns:**\n```json\n{\n  \"isStopped\": true,\n  \"currentThreadId\": 1,\n  \"stopReason\": \"breakpoint\"\n}\n```\n\n## Usage Example\n\n1. Start a debug session in VS Code with CodeLLDB\n2. Set breakpoints in your code\n3. Run the MCP server\n4. Connect your AI agent to the MCP server\n5. Use the exposed tools to inspect program state, read memory, execute LLDB commands, etc.\n\n## Development\n\n### Building the VS Code Extension\n\n```bash\ncd vscode-extension\nnpm run compile\n```\n\n### Running Tests\n\nTesting requires:\n1. A running VS Code instance with the extension loaded\n2. An active debug session with CodeLLDB\n3. The MCP server running\n\nYou can test individual components using tools like `websocat`:\n\n```bash\n# Test the WebSocket connection\necho '{\"type\":\"request\", \"command\":\"executeLldbCommand\", \"lldb_command\":\"register read\", \"id\":\"test1\"}' | websocat ws://127.0.0.1:8080\n```\n\n## Troubleshooting\n\n### Extension not connecting\n- Ensure the VS Code extension is activated (check the console for \"MCP Debugger Bridge is now active!\")\n- Verify no other process is using port 8080\n\n### MCP server connection issues\n- Check that the WebSocket server is running (extension must be active)\n- Verify firewall settings allow local connections on port 8080\n\n### Debugger commands failing\n- Ensure you have an active debug session with CodeLLDB\n- The debug session must be paused (hit a breakpoint or manually pause)\n- Check that the session type is \"lldb\" in VS Code\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackradisic%2Fmcpdbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzackradisic%2Fmcpdbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackradisic%2Fmcpdbg/lists"}