{"id":51526596,"url":"https://github.com/oaslananka/debug-recorder-mcp","last_synced_at":"2026-07-08T22:01:00.588Z","repository":{"id":360487728,"uuid":"1246600291","full_name":"oaslananka/debug-recorder-mcp","owner":"oaslananka","description":"TypeScript MCP server for structured debug session capture, reproducible diagnostics, event recording, and developer workflow observability.","archived":false,"fork":false,"pushed_at":"2026-07-06T00:30:12.000Z","size":32916,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T02:09:53.432Z","etag":null,"topics":["automation","debugging","developer-tools","diagnostics","mcp","model-context-protocol","nodejs","observability","recording","testing","troubleshooting","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/oaslananka/debug-recorder-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oaslananka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["oaslananka"],"buy_me_a_coffee":"oaslananka"}},"created_at":"2026-05-22T11:03:15.000Z","updated_at":"2026-07-06T00:29:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oaslananka/debug-recorder-mcp","commit_stats":null,"previous_names":["oaslananka/debug-recorder-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/oaslananka/debug-recorder-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oaslananka%2Fdebug-recorder-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oaslananka%2Fdebug-recorder-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oaslananka%2Fdebug-recorder-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oaslananka%2Fdebug-recorder-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oaslananka","download_url":"https://codeload.github.com/oaslananka/debug-recorder-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oaslananka%2Fdebug-recorder-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35279442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","debugging","developer-tools","diagnostics","mcp","model-context-protocol","nodejs","observability","recording","testing","troubleshooting","typescript"],"created_at":"2026-07-08T22:00:58.853Z","updated_at":"2026-07-08T22:01:00.570Z","avatar_url":"https://github.com/oaslananka.png","language":"TypeScript","funding_links":["https://github.com/sponsors/oaslananka","https://buymeacoffee.com/oaslananka","https://www.buymeacoffee.com/oaslananka","https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=%E2%98%95\u0026slug=oaslananka\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff"],"categories":[],"sub_categories":[],"readme":"# debug-recorder-mcp\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first debug memory for MCP clients.\u003c/strong\u003e\u003cbr /\u003e\n  Record incidents, commands, failed attempts, successful fixes, diagnostics, and searchable debugging history in SQLite.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/debug-recorder-mcp\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/debug-recorder-mcp.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/debug-recorder-mcp\"\u003e\u003cimg alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/debug-recorder-mcp.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/ci.yml?branch=main\u0026label=ci\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/release.yml\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/release.yml?branch=main\u0026label=release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/docs.yml\"\u003e\u003cimg alt=\"Docs\" src=\"https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/docs.yml?branch=main\u0026label=docs\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/codeql.yml\"\u003e\u003cimg alt=\"CodeQL\" src=\"https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/codeql.yml?branch=main\u0026label=codeql\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-green.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/oaslananka\"\u003e\u003cimg alt=\"Sponsor\" src=\"https://img.shields.io/badge/sponsor-Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee\u0026logoColor=111827\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://oaslananka.github.io/debug-recorder-mcp/\"\u003ePublished docs\u003c/a\u003e\n  · \u003ca href=\"./docs/usage.md\"\u003eUsage\u003c/a\u003e\n  · \u003ca href=\"./docs/client-recipes.md\"\u003eClient recipes\u003c/a\u003e\n  · \u003ca href=\"./docs/security.md\"\u003eSecurity\u003c/a\u003e\n  · \u003ca href=\"./docs/release-flow.md\"\u003eRelease flow\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/oaslananka\"\u003e\n    \u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=%E2%98%95\u0026slug=oaslananka\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff\" alt=\"Buy me a coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Why this exists\n\nDebugging 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:\n\n\u003e “Have I fixed this before?”\n\nIt 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.\n\n## Highlights\n\n- **Local-first storage:** no external database or hosted service required.\n- **MCP-native tools:** stdio server for desktop MCP clients plus optional Streamable HTTP mode.\n- **Search that survives messy errors:** FTS5 + Fuse.js reranking for stack traces, typos, Unicode, and punctuation-heavy logs.\n- **Reusable search presets:** save common filters and limits for recurring incident patterns.\n- **Safe operations:** redaction-before-store option, explicit destructive confirmations, local HTTP host/origin/auth/body-limit hardening.\n- **Diagnostics:** `get_diagnostics` returns redacted runtime, schema, package, and health signals for support without leaking raw paths, tokens, stack traces, or command output.\n- **Release-grade packaging:** audit, coverage, fuzzing, package-size gates, SBOM/VEX policy, install-script approvals, provenance-ready release workflow, and MCP Registry readiness checks.\n\n## Quick start\n\nRequires Node.js **22 LTS** or **24 LTS** and npm **10+**.\n\n```bash\nnpx debug-recorder-mcp\n```\n\nDefault database path:\n\n```text\n~/.debug-recorder-mcp/sessions.db\n```\n\nUse a custom database path:\n\n```bash\nDEBUG_RECORDER_DB=/path/to/custom.db npx debug-recorder-mcp\n```\n\n## MCP client setup\n\n### Desktop MCP clients\n\n```json\n{\n  \"mcpServers\": {\n    \"debug-recorder-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"debug-recorder-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code / GitHub Copilot\n\nCreate or update `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"debug-recorder-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"debug-recorder-mcp\"]\n    }\n  }\n}\n```\n\nMore setup examples are in [Client setup recipes](./docs/client-recipes.md).\n\n## Available MCP tools\n\n| Tool                   | Purpose                                                                                              |\n| ---------------------- | ---------------------------------------------------------------------------------------------------- |\n| `start_debug_session`  | Start tracking a new issue or incident.                                                              |\n| `add_fix`              | Record a failed or successful fix attempt.                                                           |\n| `record_command`       | Save a command, output, exit code, and session link.                                                 |\n| `close_session`        | Mark a session as resolved or abandoned.                                                             |\n| `update_session`       | Edit title, description, or tags.                                                                    |\n| `delete_session`       | Permanently delete a session with explicit confirmation.                                             |\n| `search_sessions`      | Search history with FTS5, fuzzy reranking, pagination, related groups, and optional Markdown export. |\n| `save_search_preset`   | Store a reusable query, filters, and limit.                                                          |\n| `list_search_presets`  | List saved search presets.                                                                           |\n| `remove_search_preset` | Remove a saved search preset by name.                                                                |\n| `find_similar_errors`  | Ask whether a similar error has appeared before.                                                     |\n| `get_session`          | Fetch full details, fixes, and commands.                                                             |\n| `get_session_context`  | Get an AI-friendly session summary.                                                                  |\n| `list_sessions`        | Browse sessions with filters.                                                                        |\n| `get_stats`            | Summarize debug history.                                                                             |\n| `get_diagnostics`      | Return a redacted operational diagnostics snapshot.                                                  |\n| `export_sessions`      | Export local history for backup or migration.                                                        |\n| `import_sessions`      | Import a validated export payload.                                                                   |\n\n## Real usage examples\n\n### Have I seen this before?\n\nAsk your MCP client:\n\n\u003e I am getting `TypeError: Cannot read properties of undefined`. Have I seen this before?\n\nThe client can call `find_similar_errors`, then inspect the best match with `get_session_context`.\n\n### Record an active incident\n\n1. Call `start_debug_session` with the problem title and error details.\n2. Add terminal commands with `record_command`.\n3. Add each attempted fix with `add_fix`.\n4. Improve title, notes, or tags with `update_session`.\n5. Close the incident with `close_session`.\n\n### Back up or migrate history\n\n1. Call `export_sessions` with JSON output.\n2. Store the returned payload in your backup system.\n3. Restore later with `import_sessions`.\n\n## HTTP transport\n\nThe package also supports local Streamable HTTP:\n\n```bash\nnpm run start:http\n```\n\nUseful routes:\n\n- `GET /health`\n- `GET /version`\n- MCP endpoint: `POST /mcp`\n\nHTTP 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.\n\nFor deliberate non-loopback exposure, set all of these:\n\n```bash\nHOST=0.0.0.0\nDEBUG_RECORDER_REMOTE_HTTP=true\nDEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token\nDEBUG_RECORDER_ALLOWED_HOSTS=debug-recorder.example.com\nDEBUG_RECORDER_ALLOWED_ORIGINS=https://debug-recorder.example.com\nnpm run start:http\n```\n\nWildcard origins are rejected for remote mode.\n\n## Configuration\n\n| Variable                             | Description                                                           |\n| ------------------------------------ | --------------------------------------------------------------------- |\n| `DEBUG_RECORDER_DB`                  | Override the SQLite database path.                                    |\n| `HOST`                               | HTTP bind host. Defaults to `127.0.0.1`.                              |\n| `PORT`                               | HTTP port. Defaults to `3000`.                                        |\n| `DEBUG_RECORDER_HTTP_TOKEN`          | Optional bearer token for local HTTP; required for non-loopback HTTP. |\n| `DEBUG_RECORDER_ALLOWED_HOSTS`       | Comma-separated HTTP `Host` allowlist.                                |\n| `DEBUG_RECORDER_ALLOWED_ORIGINS`     | Comma-separated browser `Origin` allowlist.                           |\n| `DEBUG_RECORDER_MAX_BODY_BYTES`      | HTTP JSON body limit. Defaults to `1048576`.                          |\n| `DEBUG_RECORDER_REMOTE_HTTP`         | Must be `true` before binding to a non-loopback host.                 |\n| `DEBUG_RECORDER_REDACT_BEFORE_STORE` | Set `true` to redact common secret patterns before persistence.       |\n| `LOG_LEVEL`                          | Minimum structured log level: `debug`, `info`, `warn`, or `error`.    |\n| `FUZZY_THRESHOLD`                    | Override the Fuse.js reranking threshold.                             |\n\n## Data and privacy\n\n- Database: local SQLite via `better-sqlite3`.\n- Search index: SQLite FTS5 virtual table.\n- Default path: `~/.debug-recorder-mcp/sessions.db`.\n- Redaction: optional before-store redaction plus diagnostics redaction.\n- Deletion: destructive operations require explicit confirmation.\n- Maintenance: see [Storage retention and maintenance](./docs/storage-retention.md).\n\n\u003e `better-sqlite3` uses a native addon. If Node versions change and bindings fail, run `npm rebuild better-sqlite3`.\n\n## Docker\n\n```bash\ndocker build -t debug-recorder-mcp:local .\ndocker run --rm -p 127.0.0.1:3000:3000 \\\n  -e HOST=0.0.0.0 \\\n  -e DEBUG_RECORDER_REMOTE_HTTP=true \\\n  -e DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token \\\n  -e DEBUG_RECORDER_ALLOWED_HOSTS=127.0.0.1:3000,localhost:3000 \\\n  -e DEBUG_RECORDER_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000 \\\n  debug-recorder-mcp:local\n```\n\nThe image installs with `npm ci`, preserves reviewed native install scripts, prunes development dependencies, and runs as the non-root `node` user.\n\n## Documentation\n\nPublished documentation is generated by `npm run docs:site` and published to GitHub Pages:\n\n```text\nhttps://oaslananka.github.io/debug-recorder-mcp/\n```\n\nImportant docs:\n\n- [Usage](./docs/usage.md)\n- [Client setup recipes](./docs/client-recipes.md)\n- [Configuration](./docs/configuration.md)\n- [Architecture](./docs/architecture.md)\n- [Security](./docs/security.md)\n- [Operations](./docs/operations.md)\n- [Troubleshooting](./docs/troubleshooting.md)\n- [Storage retention](./docs/storage-retention.md)\n- [Testing](./docs/testing.md)\n- [Release flow](./docs/release-flow.md)\n- [Install-script policy](./docs/install-script-policy.md)\n- [SBOM/VEX policy](./docs/security-sbom-vex.md)\n- [Architecture decision records](./docs/adr/README.md)\n\n## Development\n\n```bash\nnpm ci\nnpm run format:check\nnpm run lint\nnpm run check:dead-code\nnpm run test:coverage\nnpm run test:fuzz\nnpm run build\nnpm run test:e2e\nnpm run audit\nnpm run check:install-scripts\nnpm pack --dry-run\nnpm run check:package-size\nnpm run check:version\nnpm run check:mcp\nnpm run check:security-policy\nnpm run docs:site\n```\n\nFull local gate:\n\n```bash\nnpm run ci:local\n```\n\nRelease readiness:\n\n```bash\nnpm run prepublishOnly\nnpm run check:mcp-registry\n```\n\n## Release and npm publishing\n\nThe 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.\n\nFor 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](./docs/release-flow.md).\n\n## License\n\nReleased under the [MIT License](./LICENSE). `package.json` also declares `\"license\": \"MIT\"`, and the npm package includes `LICENSE`.\n\n## Funding\n\nIf this project saves you debugging time, support development here:\n\n- Buy Me a Coffee: \u003chttps://www.buymeacoffee.com/oaslananka\u003e\n- GitHub Sponsors: \u003chttps://github.com/sponsors/oaslananka\u003e\n\nFunding metadata is available in both `.github/FUNDING.yml` and `package.json`.\n\n## Agent plugin and runtime configuration\n\nThis 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.\n\n| File | Purpose |\n| --- | --- |\n| [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) | Claude Code-valid product plugin manifest. |\n| [`.mcp.json`](.mcp.json) | Claude Code project-local MCP server configuration. |\n| [`.codex/config.example.toml`](.codex/config.example.toml) | Codex CLI MCP configuration example. |\n| [`.vscode/mcp.example.json`](.vscode/mcp.example.json) | VS Code / GitHub Copilot workspace MCP configuration example. |\n| [`opencode.example.jsonc`](opencode.example.jsonc) | OpenCode project MCP configuration example. |\n| `.opencode/skills/` | OpenCode-native mirrored skill definitions. |\n| [`docs/agent-runtime-config.md`](docs/agent-runtime-config.md) | Agent runtime setup and validation notes. |\n\nValidate plugin packaging locally:\n\n```bash\nclaude plugin validate .\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foaslananka%2Fdebug-recorder-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foaslananka%2Fdebug-recorder-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foaslananka%2Fdebug-recorder-mcp/lists"}