# mcp-debug-recorder

[![npm version](https://img.shields.io/npm/v/mcp-debug-recorder.svg)](https://www.npmjs.com/package/mcp-debug-recorder)
[![License](https://img.shields.io/npm/l/mcp-debug-recorder.svg)](./LICENSE)
[![npm downloads](https://img.shields.io/npm/dm/mcp-debug-recorder.svg)](https://www.npmjs.com/package/mcp-debug-recorder)
[![LobeHub](https://lobehub.com/badge/mcp/mcp-debug-recorder)](https://lobehub.com/mcp/mcp-debug-recorder)
[![Glama](https://glama.ai/mcp/servers/@oaslananka/mcp-debug-recorder/badge)](https://glama.ai/mcp/servers/@oaslananka/mcp-debug-recorder)

`mcp-debug-recorder` answers a simple question fast: have I fixed this before?

It records debug sessions, terminal commands, failed attempts, and successful fixes in a local SQLite database so your MCP client can query your own debugging history in natural language.

## Quick Start

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

By default, data is stored at `~/.mcp-debug-recorder/sessions.db`.

## Architecture

```text
src/
├── db.ts           - openDb(), createTestDb(), versioned MIGRATIONS[]
├── store.ts        - Store class with dependency-injected SQLite access
├── search.ts       - FTS5 + Fuse.js hybrid search
├── tools/          - MCP tool handlers grouped by session/search/admin concerns
├── types.ts        - Zod schemas and TypeScript types
├── mcp.ts          - MCP server wiring + tool registration
├── server-http.ts  - Streamable HTTP transport
├── logging.ts      - Structured logging with secret redaction
└── version.ts      - Package version helper
```

### Schema versioning

The database schema is versioned via `PRAGMA user_version`. Migrations run automatically on startup, so upgrading does not require manual SQL.

### Adding a custom database path

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

## Configuration

### Environment variables

- `DEBUG_RECORDER_DB`: override the SQLite database path
- `PORT`: override the HTTP server port for Streamable HTTP mode
- `LOG_LEVEL`: minimum structured log level (`debug`, `info`, `warn`, `error`)
- `FUZZY_THRESHOLD`: override the Fuse.js threshold used during reranking

## Available Tools

- `start_debug_session`: start tracking a new issue
- `add_fix`: record a failed or successful fix attempt
- `record_command`: save a terminal command and its output
- `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 historical sessions with FTS5 + fuzzy reranking
- `find_similar_errors`: ask whether you have seen a similar error before
- `get_session`: fetch full session details
- `get_session_context`: fetch an AI-friendly summary of a session
- `list_sessions`: browse sessions with filters
- `get_stats`: summarize your debug history
- `export_sessions`: export your local history for backup or migration
- `import_sessions`: import a previously exported JSON payload

## Client Setup

### Claude Desktop

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

### VS Code / GitHub Copilot

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

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

### Codex CLI

```bash
codex mcp add mcp-debug-recorder -- npx mcp-debug-recorder
codex mcp list
```

### Gemini CLI

```bash
gemini mcp add mcp-debug-recorder npx mcp-debug-recorder
gemini mcp list
```

### Antigravity

```powershell
antigravity --add-mcp "{\"name\":\"mcp-debug-recorder\",\"command\":\"npx\",\"args\":[\"mcp-debug-recorder\"]}"
```

## Real Usage Examples

### Have I seen this before?

> "I'm getting `TypeError: Cannot read properties of undefined`, have I seen this before?"

Call `find_similar_errors` with the current error text, then inspect the best match with `get_session_context`.

### Record an active incident

1. Call `start_debug_session`
2. Add terminal commands with `record_command`
3. Add each attempted fix with `add_fix`
4. Use `update_session` when the title or notes become clearer
5. Close the session with `close_session`

### Back up your local debug history

1. Call `export_sessions` with `format: "json"`
2. Save the returned JSON in your preferred backup system
3. Restore later with `import_sessions`

## Data Storage

- Default path: `~/.mcp-debug-recorder/sessions.db`
- Portable SQLite storage with `better-sqlite3`
- FTS5-backed search index for large histories
- No external database server required

> Note: `better-sqlite3` uses a native addon. If you see binding errors, run `npm rebuild better-sqlite3` for your Node version.

## HTTP Transport

The package also supports Streamable HTTP:

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

Useful routes:

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

## Development

```bash
npm ci
npm run lint
npm test
npm run build
npm run test:e2e
npm run docs:api
```

For release verification:

```bash
npm run format:check
npm run test:coverage
npm run prepublishOnly
```

Additional project docs:

- [Usage](./docs/usage.md)
- [Configuration](./docs/configuration.md)
- [Architecture](./docs/architecture.md)
- [Search Algorithm](./docs/search-algorithm.md)
- [Release Flow](./docs/release-flow.md)
- [Versioning Policy](./VERSIONING.md)
- [Roadmap](./ROADMAP.md)