debug-recorder-mcp

# debug-recorder-mcp

<p align="center">
  <strong>Local-first debug memory for MCP clients.</strong><br />
  Record incidents, commands, failed attempts, successful fixes, diagnostics, and searchable debugging history in SQLite.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/debug-recorder-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/debug-recorder-mcp.svg" /></a>
  <a href="https://www.npmjs.com/package/debug-recorder-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/debug-recorder-mcp.svg" /></a>
  <a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/ci.yml?branch=main&label=ci" /></a>
  <a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/release.yml"><img alt="Release" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/release.yml?branch=main&label=release" /></a>
  <a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/docs.yml"><img alt="Docs" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/docs.yml?branch=main&label=docs" /></a>
  <a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/codeql.yml?branch=main&label=codeql" /></a>
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg" /></a>
  <a href="https://www.buymeacoffee.com/oaslananka"><img alt="Sponsor" src="https://img.shields.io/badge/sponsor-Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=111827" /></a>
</p>

<p align="center">
  <a href="https://oaslananka.github.io/debug-recorder-mcp/">Published docs</a>
  · <a href="./docs/usage.md">Usage</a>
  · <a href="./docs/client-recipes.md">Client recipes</a>
  · <a href="./docs/security.md">Security</a>
  · <a href="./docs/release-flow.md">Release flow</a>
</p>

<p align="center">
  <a href="https://www.buymeacoffee.com/oaslananka">
    <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Arial&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" />
  </a>
</p>

## Why this exists

Debugging knowledge usually disappears into chat windows, terminals, and commit history. `debug-recorder-mcp` gives MCP-enabled agents and IDEs a durable local memory so they can answer:

> “Have I fixed this before?”

It stores each debugging session, error, command, attempted fix, working fix, tags, and context in a local SQLite database. Search combines SQLite FTS5 with fuzzy reranking, reusable presets, pagination metadata, related-session groups, and optional Markdown exports.

## Highlights

- **Local-first storage:** no external database or hosted service required.
- **MCP-native tools:** stdio server for desktop MCP clients plus optional Streamable HTTP mode.
- **Search that survives messy errors:** FTS5 + Fuse.js reranking for stack traces, typos, Unicode, and punctuation-heavy logs.
- **Reusable search presets:** save common filters and limits for recurring incident patterns.
- **Safe operations:** redaction-before-store option, explicit destructive confirmations, local HTTP host/origin/auth/body-limit hardening.
- **Diagnostics:** `get_diagnostics` returns redacted runtime, schema, package, and health signals for support without leaking raw paths, tokens, stack traces, or command output.
- **Release-grade packaging:** audit, coverage, fuzzing, package-size gates, SBOM/VEX policy, install-script approvals, provenance-ready release workflow, and MCP Registry readiness checks.

## Quick start

Requires Node.js **22 LTS** or **24 LTS** and npm **10+**.

```bash
npx debug-recorder-mcp
```

Default database path:

```text
~/.debug-recorder-mcp/sessions.db
```

Use a custom database path:

```bash
DEBUG_RECORDER_DB=/path/to/custom.db npx debug-recorder-mcp
```

## MCP client setup

### Desktop MCP clients

```json
{
  "mcpServers": {
    "debug-recorder-mcp": {
      "command": "npx",
      "args": ["debug-recorder-mcp"]
    }
  }
}
```

### VS Code / GitHub Copilot

Create or update `.vscode/mcp.json`:

```json
{
  "servers": {
    "debug-recorder-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["debug-recorder-mcp"]
    }
  }
}
```

More setup examples are in [Client setup recipes](./docs/client-recipes.md).

## Available MCP tools

| Tool                   | Purpose                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `start_debug_session`  | Start tracking a new issue or incident.                                                              |
| `add_fix`              | Record a failed or successful fix attempt.                                                           |
| `record_command`       | Save a command, output, exit code, and session link.                                                 |
| `close_session`        | Mark a session as resolved or abandoned.                                                             |
| `update_session`       | Edit title, description, or tags.                                                                    |
| `delete_session`       | Permanently delete a session with explicit confirmation.                                             |
| `search_sessions`      | Search history with FTS5, fuzzy reranking, pagination, related groups, and optional Markdown export. |
| `save_search_preset`   | Store a reusable query, filters, and limit.                                                          |
| `list_search_presets`  | List saved search presets.                                                                           |
| `remove_search_preset` | Remove a saved search preset by name.                                                                |
| `find_similar_errors`  | Ask whether a similar error has appeared before.                                                     |
| `get_session`          | Fetch full details, fixes, and commands.                                                             |
| `get_session_context`  | Get an AI-friendly session summary.                                                                  |
| `list_sessions`        | Browse sessions with filters.                                                                        |
| `get_stats`            | Summarize debug history.                                                                             |
| `get_diagnostics`      | Return a redacted operational diagnostics snapshot.                                                  |
| `export_sessions`      | Export a full JSON backup or a lightweight summary inventory.                                        |
| `import_sessions`      | Import a validated export payload.                                                                   |

## Real usage examples

### Have I seen this before?

Ask your MCP client:

> I am getting `TypeError: Cannot read properties of undefined`. Have I seen this before?

The client can call `find_similar_errors`, then inspect the best match with `get_session_context`.

### Record an active incident

1. Call `start_debug_session` with the problem title and error details.
2. Add terminal commands with `record_command`.
3. Add each attempted fix with `add_fix`.
4. Improve title, notes, or tags with `update_session`.
5. Close the incident with `close_session`.

### Back up or migrate history

1. Call `export_sessions` with `format: "json"`. The response is marked with
   `format: "json"` and contains the full `sessions`, `fixes`, and `commands`
   arrays.
2. Store the returned object in your backup system.
3. Restore later by passing that object as `import_sessions.payload`.

For a lightweight inventory, call `export_sessions` with `format: "summary"`.
Summary responses are marked with `format: "summary"`, include aggregate
`stats` and abbreviated session rows, and are not restore payloads.

## HTTP transport

The package also supports local Streamable HTTP:

```bash
npm run start:http
```

Useful routes:

- `GET /health`
- `GET /version`
- MCP endpoint: `POST /mcp`

HTTP mode is local-first by default. It binds to `127.0.0.1`, creates an isolated stateless MCP server/transport per request, validates `Host`, validates browser `Origin` when present, and enforces a JSON body-size limit before the MCP transport receives the request.

For deliberate non-loopback exposure, set all of these:

```bash
HOST=0.0.0.0
DEBUG_RECORDER_REMOTE_HTTP=true
DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token
DEBUG_RECORDER_ALLOWED_HOSTS=debug-recorder.example.com
DEBUG_RECORDER_ALLOWED_ORIGINS=https://debug-recorder.example.com
npm run start:http
```

Wildcard origins are rejected for remote mode. The static bearer token is
**private/shared-secret mode**: every caller shares one identity, one authority
level, and one SQLite dataset. It is suitable for loopback, an encrypted trusted
network, or a private authenticating proxy, but it is not OAuth and does not
provide per-user scopes or revocation.

**Public multi-user HTTP is not supported** by the current release. The accepted
target architecture uses an external authorization server and MCP-aware gateway
with protected-resource discovery, audience-bound tokens, scopes, rate limits,
audit events, and subject-aware storage. See
[Public HTTP authorization](./docs/public-http-authorization.md) and
[ADR-0006](./docs/adr/0006-public-http-oauth-resource-server-profile.md).

## Configuration

| Variable                             | Description