# MCP Debug Recorder [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/oaslananka/debug-recorder-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-debug-recorder

## Description
Record debug sessions, commands, failed attempts, and successful fixes in local SQLite storage.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation & README

# 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="https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/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="https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/usage.md">Usage</a>
  · <a href="https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/client-recipes.md">Client recipes</a>
  · <a href="https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/security.md">Security</a>
  · <a href="https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/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](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/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](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/public-http-authorization.md) and
[ADR-0006](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/adr/0006-public-http-oauth-resource-server-profile.md).

## Configuration

| Variable                             | Description                                                           |
| ------------------------------------ | --------------------------------------------------------------------- |
| `DEBUG_RECORDER_DB`                  | Override the SQLite database path.                                    |
| `HOST`                               | HTTP bind host. Defaults to `127.0.0.1`.                              |
| `PORT`                               | HTTP port. Defaults to `3000`.                                        |
| `DEBUG_RECORDER_HTTP_TOKEN`          | Private/shared-secret token; required for non-loopback HTTP, not OAuth. |
| `DEBUG_RECORDER_ALLOWED_HOSTS`       | Comma-separated HTTP `Host` allowlist.                                |
| `DEBUG_RECORDER_ALLOWED_ORIGINS`     | Comma-separated browser `Origin` allowlist.                           |
| `DEBUG_RECORDER_MAX_BODY_BYTES`      | HTTP JSON body limit. Defaults to `1048576`.                          |
| `DEBUG_RECORDER_REMOTE_HTTP`         | Enable non-loopback HTTP with `true`, `1`, or `yes`.                  |
| `DEBUG_RECORDER_REDACT_BEFORE_STORE` | Enable pre-store redaction with `true`, `1`, or `yes`.                |
| `LOG_LEVEL`                          | Minimum structured log level: `debug`, `info`, `warn`, or `error`.    |
| `FUZZY_THRESHOLD`                    | Override the Fuse.js reranking threshold.                             |

Boolean configuration also accepts `false`, `0`, and `no`; values are
case-insensitive, whitespace is ignored, and unsupported values fail fast.
Diagnostics reports the resolved effective values rather than re-reading changed
environment strings.

## Data and privacy

- Database: local SQLite via `better-sqlite3`.
- Search index: SQLite FTS5 virtual table.
- Default path: `~/.debug-recorder-mcp/sessions.db`.
- Redaction: optional before-store redaction plus diagnostics redaction.
- Deletion: destructive operations require explicit confirmation.
- Maintenance: see [Storage retention and maintenance](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/storage-retention.md).

> `better-sqlite3` uses a native addon. If Node versions change and bindings fail, run `npm rebuild better-sqlite3`.

## Docker

```bash
docker build -t debug-recorder-mcp:local .
docker run --rm -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e DEBUG_RECORDER_REMOTE_HTTP=true \
  -e DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token \
  -e DEBUG_RECORDER_ALLOWED_HOSTS=127.0.0.1:3000,localhost:3000 \
  -e DEBUG_RECORDER_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000 \
  debug-recorder-mcp:local
```

The image installs with `npm ci`, preserves reviewed native install scripts, prunes development dependencies, and runs as the non-root `node` user.

## Documentation

Published documentation is generated by `npm run docs:site` and published to GitHub Pages:

```text
https://oaslananka.github.io/debug-recorder-mcp/
```

Important docs:

- [Usage](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/usage.md)
- [Client setup recipes](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/client-recipes.md)
- [Configuration](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/configuration.md)
- [Architecture](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/architecture.md)
- [Security](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/security.md)
- [Public HTTP authorization](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/public-http-authorization.md)
- [Operations](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/operations.md)
- [Troubleshooting](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/troubleshooting.md)
- [Storage retention](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/storage-retention.md)
- [Testing](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/testing.md)
- [Release flow](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/release-flow.md)
- [Install-script policy](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/install-script-policy.md)
- [SBOM/VEX policy](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/security-sbom-vex.md)
- [Architecture decision records](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/adr/README.md)

## Development

```bash
npm ci
npm run format:check
npm run lint
npm run check:dead-code
npm run test:coverage
npm run test:fuzz
npm run build
npm run test:e2e
npm run audit
npm run check:install-scripts
npm pack --dry-run
npm run check:package-size
npm run check:version
npm run check:mcp
npm run check:security-policy
npm run check:sbom
npm run docs:site
```

Full local gate:

```bash
npm run ci:local
```

Release readiness:

```bash
npm run prepublishOnly
npm run check:mcp-registry
```

## Release and npm publishing

The normal release workflow uses Release Please, builds release assets, generates SBOM/checksums, attests the tarball, uploads GitHub Release assets, and publishes to npm with provenance.

For the first npm package creation, use the manual **Initial npm Token Publish** workflow with repository secret `NPM_TOKEN`. After the package exists and npm trusted publishing is configured, the regular **Release** workflow can publish through GitHub OIDC. Details are in [Release flow](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/release-flow.md).

## License

Released under the [MIT License](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/LICENSE). `package.json` also declares `"license": "MIT"`, and the npm package includes `LICENSE`.

## Funding

If this project saves you debugging time, support development here:

- Buy Me a Coffee: <https://www.buymeacoffee.com/oaslananka>
- GitHub Sponsors: <https://github.com/sponsors/oaslananka>

Funding metadata is available in both `.github/FUNDING.yml` and `package.json`.

## Agent plugin and runtime configuration

This repository owns the product-level agent plugin, MCP runtime configuration, and product-specific skills for `debug-recorder-mcp`. The central [`agent-tools`](https://github.com/oaslananka/agent-tools) repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server package.

| File | Purpose |
| --- | --- |
| [`.claude-plugin/plugin.json`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/.claude-plugin/plugin.json) | Claude Code-valid product plugin manifest. |
| [`.mcp.json`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/.mcp.json) | Claude Code project-local MCP server configuration. |
| [`.codex/config.example.toml`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/.codex/config.example.toml) | Codex CLI MCP configuration example. |
| [`.vscode/mcp.example.json`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/.vscode/mcp.example.json) | VS Code / GitHub Copilot workspace MCP configuration example. |
| [`opencode.example.jsonc`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/opencode.example.jsonc) | OpenCode project MCP configuration example. |
| `.opencode/skills/` | OpenCode-native mirrored skill definitions. |
| [`docs/agent-runtime-config.md`](https://github.com/oaslananka/debug-recorder-mcp/blob/HEAD/docs/agent-runtime-config.md) | Agent runtime setup and validation notes. |

Validate plugin packaging locally:

```bash
claude plugin validate .
```