firedbg-mcp

A small, repository-scoped MCP server for FireDBG. It lets an agent discover Rust targets, run them under FireDBG, index traces, and inspect the complete SQLite trace without granting access to other workspaces.

Prerequisites

• Node.js 22 or newer
• A Rust Cargo workspace
• firedbg and firedbg-indexer installed and available on PATH

FireDBG provides installation instructions in its upstream repository. This server checks the base installation with firedbg_status; it does not replace the global FireDBG CLI, indexer, or bundled LLDB runtime.

If upstream does not publish a precompiled debugger for the active compiler, call firedbg_prepare_compatible. The tool installs the exact matching Rustup toolchain, builds only firedbg-debugger from a pinned upstream revision, smoke-tests it, and activates it under <workspace>/.firedbg-mcp/firedbg/<rust-major.minor>/. It reuses the installed FireDBG LLDB runtime and does not replace global FireDBG binaries.

Setup

npm install
npm run build

Configure an MCP client to launch the compiled server with its repository root:

{
  "mcpServers": {
    "firedbg": {
      "command": "node",
      "args": ["/absolute/path/to/firedbg-mcp/dist/index.js", "--workspace-root", "/absolute/path/to/rust-workspace"]
    }
  }
}

--workspace-root defaults to the server process's initial working directory. FIREDBG_BIN and FIREDBG_INDEXER_BIN may select non-default executable paths.

Every attempted tool call is appended to <workspace>/.firedbg-mcp/actions.jsonl. Raw target arguments, program output, SQL, and query parameters are excluded from the audit record; hashes are retained for correlation. In Git worktrees the directory is added to .git/info/exclude automatically.

Tools

• firedbg_status
• firedbg_prepare_compatible
• firedbg_list_targets
• firedbg_run
• firedbg_list_runs
• firedbg_index_run
• firedbg_trace_schema
• firedbg_query_trace

Trace queries accept one parameterized SELECT or WITH statement. The database is opened read-only and responses are capped at 1,000 rows and 1 MiB. Use offset and limit for pagination.

Development

npm test
npm run typecheck
npm run build
npm run inspect -- --workspace-root /path/to/cargo/workspace

Debug runs are synchronous in v1. Background execution would require persisted job state, status and cancellation tools, process-tree cleanup, and restart recovery; that is intentionally outside this server's KISS-oriented scope.

Compatible-debugger builds use <workspace>/.firedbg-mcp/build only while compiling and remove that directory after success or failure. The resulting debugger is repository-local; future runs automatically pass its home to the FireDBG CLI when its embedded Rust minor version matches the workspace's active compiler.