An MCP (Model Context Protocol) server that bridges MCP tool calls to the Debug Adapter Protocol (DAP) via codelldb. Enables LLM-driven debugging of native code (C, C++, Rust, Zig, etc.) through a debugger.

flowchart LR
    subgraph Client["MCP Client"]
        A["VS Code / OpenCode<br/>Cline / Roo"]
    end
    subgraph Bridge["debugger-mcp (Zig)"]
        B["JSON-RPC 2.0 over stdio<br/>(NDJSON lines)"]
    end
    subgraph Adapter["Debug Adapter"]
        C["codelldb (LLDB)"]
    end
    subgraph Logging["Logging"]
        D["stderr"]
    end

    Client <--->|MCP| Bridge
    Bridge <-->|DAP over TCP<br/>Content-Length| Adapter
    Bridge -.->|log output| Logging

• MCP transport: stdio (newline-delimited JSON per the MCP spec)
• DAP transport: TCP to codelldb (which listens on a random port)
• Language: Zig (zero external dependencies — pure std library)

• Zig 0.15.2+ (to build)
• codelldb — the VS Code LLDB extension adapter
  • Auto-detected at /tmp/codelldb-extract/extension/adapter/codelldb
  • Override via DEBUGGERMCP_ADAPTER environment variable
• ss (from iproute2) — used for port discovery on Linux

Add to your opencode.jsonc:

"mcp": {
  "debugger": {
    "type": "local",
    "command": ["/path/to/debugger-mcp"]
  }
}

No additional env block is needed (codelldb path defaults to /tmp/codelldb-extract/extension/adapter/codelldb).

zig build -Doptimize=ReleaseSafe

The binary is placed at zig-out/bin/debugger-mcp.

sequenceDiagram
    participant Client as OpenCode
    participant Server as debugger-mcp
    participant Adapter as codelldb

    Client->>Server: initialize
    Server-->>Client: {capabilities}
    Client->>Server: initialized
    Client->>Server: tools/list
    Server-->>Client: {tools[...]}

sequenceDiagram
    participant Client as OpenCode
    participant Server as debugger-mcp
    participant Adapter as codelldb

    Client->>Server: start_debugging
    Server->>Adapter: spawn codelldb
    Adapter-->>Server: port
    Server->>Adapter: TCP connect
    Server->>Adapter: DAP initialize
    Adapter-->>Server: {capabilities}
    Server->>Adapter: DAP launch
    Adapter-->>Server: {success}
    Server-->>Client: "session started"

    Client->>Server: step_over
    Server->>Adapter: DAP next
    Adapter-->>Server: {response}
    Server-->>Client: "stepped over"

codelldb is spawned with --port 0 (random port), discovered via ss -tlnp, and communicated with over TCP using standard DAP framing (Content-Length headers). The server follows codelldb's non-standard initialization order: launch must happen before configurationDone — codelldb only sends initialized as a side effect of receiving the launch request.

The server logs to stderr at the configured log level (default: info). Set DEBUGGERMCP_LOG=debug environment variable for verbose output.

src/
├── main.zig         # Entry point, tool registration, wiring
├── handler.zig      # MCP tool handlers — translates MCP → DAP
├── dap.zig          # DAP client — spawn, TCP, protocol operations
├── Logger.zig       # Leveled stderr logger
└── mcp/
    ├── server.zig   # Generic MCP stdio JSON-RPC server
    └── types.zig    # MCP result/error builders

A debug-live Agent Skill is included at skills/debug-live/SKILL.md for use with skills-compatible harnesses. It teaches the LLM a complete debugging workflow: when to invoke debugging, root cause analysis framework, breakpoint strategy, tool-call patterns, and things to avoid. Install it into your agent's skills directory to enable automatic skill discovery.

• Linux-only port discovery (uses ss -tlnp from iproute2)
• Single session: only one debug session at a time
• No DAP event forwarding: stopped, continued, etc. are silently discarded (no MCP notifications to the client)
• Poll-based I/O: synchronous polling with 100ms intervals — not suitable for high-throughput scenarios
• codelldb-specific: initialization order assumes codelldb behavior (launch before configurationDone)