firedbg-mcp

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 installation with firedbg_status; it never installs or updates FireDBG.

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_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.