# firedbg-mcp

A small, repository-scoped MCP server for [FireDBG](https://firedbg.sea-ql.org/). 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

```sh
npm install
npm run build
```

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

```json
{
  "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

```sh
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.