Debug Recorder

debug-recorder-mcp

MCP クライアント向けのローカルファーストなデバッグメモリです。
インシデント、コマンド、失敗した試行、成功した修正、診断情報、検索可能なデバッグ履歴を SQLite に記録します。

公開ドキュメント · 使い方 · クライアント別の設定例 · セキュリティ · リリースの流れ

開発した背景

デバッグの知識は、チャット画面やターミナル、コミット履歴の中に埋もれてしまいがちです。debug-recorder-mcp は、MCP 対応のエージェントや IDE に永続的なローカルメモリを提供し、次のような問いに答えられるようにします。

「これ、以前に修正したことがあるだろうか？」

デバッグセッション、エラー、コマンド、試した修正、うまくいった修正、タグ、コンテキストをローカルの SQLite データベースに保存します。検索では SQLite FTS5 とファジー再ランキングを組み合わせ、再利用可能なプリセット、ページネーションのメタデータ、関連セッションのグループ化、任意の Markdown エクスポートにも対応します。

主な特長

• ローカルファーストのストレージ： 外部データベースやホスト型サービスは不要です。
• MCP ネイティブのツール： デスクトップ MCP クライアント向けの stdio サーバーに加え、オプションで Streamable HTTP モードも利用できます。
• 雑多なエラーにも対応する検索： FTS5 と Fuse.js による再ランキングで、スタックトレース、タイプミス、Unicode、句読点の多いログを検索できます。
• 再利用可能な検索プリセット： 繰り返し発生するインシデントのパターンに備え、よく使うフィルターや上限を保存できます。
• 安全な操作： 保存前の秘匿化オプション、明示的な破壊的操作の確認、ローカル HTTP のホスト／オリジン／認証／リクエスト本文サイズ制限の強化に対応しています。
• 診断： get_diagnostics は、サポートに必要なランタイム、スキーマ、パッケージ、ヘルス状態のシグナルを秘匿化して返します。生のパス、トークン、スタックトレース、コマンド出力が漏れることはありません。
• リリース品質のパッケージング： 監査、カバレッジ、ファジング、パッケージサイズのゲート、SBOM/VEX ポリシー、インストールスクリプトの承認、プロベナンス対応のリリースワークフロー、MCP Registry 対応状況のチェックを備えています。

クイックスタート

Node.js 22 LTS または 24 LTS と npm 10+ が必要です。

npx debug-recorder-mcp

デフォルトのデータベースパス：

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

カスタムのデータベースパスを使用する場合：

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

MCP クライアントの設定

デスクトップ MCP クライアント

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

VS Code / GitHub Copilot

.vscode/mcp.json を作成または更新します：

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

その他の設定例は、クライアント設定レシピをご覧ください。

利用可能な MCP ツール

ツール	用途
start_debug_session	新しい問題またはインシデントの追跡を開始します。
add_fix	修正の試行結果（失敗または成功）を記録します。
record_command	コマンド、出力、終了コード、セッションへのリンクを保存します。
close_session	セッションを解決済みまたは放棄済みとしてマークします。
update_session	タイトル、説明、またはタグを編集します。
delete_session	明示的な確認のうえ、セッションを完全に削除します。
search_sessions	FTS5、あいまい検索による再ランキング、ページネーション、関連グループ、およびオプションの Markdown エクスポートを使用して履歴を検索します。
save_search_preset	再利用可能なクエリ、フィルター、上限件数を保存します。
list_search_presets	保存済みの検索プリセットを一覧表示します。
remove_search_preset	名前を指定して、保存済みの検索プリセットを削除します。
find_similar_errors	類似のエラーが以前に発生したことがあるかを確認します。
get_session	詳細情報、修正内容、コマンドを取得します。
get_session_context	AI が利用しやすいセッションの概要を取得します。
list_sessions	フィルターを指定してセッションを参照します。
get_stats	デバッグ履歴の概要をまとめます。
get_diagnostics	運用診断のスナップショットを、機密情報を伏せて返します。
export_sessions	JSON の完全なバックアップ、または軽量な概要一覧をエクスポートします。
import_sessions	検証済みのエクスポートデータをインポートします。

実際の使用例

以前にも同じ問題が発生したことがありますか？

MCP クライアントに次のように尋ねます：

TypeError: Cannot read properties of undefined が発生しています。以前にも同じ問題が起きたことがありますか？

クライアントは find_similar_errors を呼び出し、その後 get_session_context で最も一致する結果を確認できます。

発生中のインシデントを記録する

1. 問題のタイトルとエラーの詳細を指定して start_debug_session を呼び出します。
2. record_command でターミナルコマンドを追加します。
3. add_fix で試した修正をそれぞれ追加します。
4. update_session でタイトル、メモ、タグを整えます。
5. close_session でインシデントを終了します。

履歴のバックアップまたは移行

1. format: "json" を指定して export_sessions を呼び出します。レスポンスには format: "json" が指定され、sessions、fixes、commands の全配列が含まれます。
2. 返されたオブジェクトをバックアップシステムに保存します。
3. 後で復元するには、そのオブジェクトを import_sessions.payload に渡します。

簡易的なインベントリには、format: "summary" を指定して export_sessions を呼び出します。サマリーレスポンスには format: "summary" が指定され、集計した stats と簡略化されたセッション行が含まれますが、復元用のペイロードではありません。

HTTP トランスポート

このパッケージはローカルの Streamable HTTP にも対応しています。

npm run start:http

便利なルート：

• GET /health
• GET /version
• MCP エンドポイント：POST /mcp

HTTP モードは、デフォルトでローカル優先です。127.0.0.1 にバインドし、リクエストごとに分離されたステートレスな MCP サーバー／トランスポートを作成し、Host を検証します。また、指定されている場合はブラウザーの Origin を検証し、MCP トランスポートがリクエストを受け取る前に JSON ボディサイズの上限を適用します。

意図的にループバック以外に公開するには、次のすべてを設定します。

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

リモートモードではワイルドカードのオリジンは拒否されます。静的ベアラートークンはプライベート／共有シークレットモードです。すべての呼び出し元が同じ ID、同じ権限レベル、同じ SQLite データセットを共有します。ループバック、暗号化された信頼できるネットワーク、またはプライベートな認証プロキシには適していますが、OAuth ではなく、ユーザーごとのスコープや失効には対応していません。

現在のリリースでは、一般公開のマルチユーザー HTTP はサポートされていません。想定されているアーキテクチャでは、保護されたリソースの検出、オーディエンスに紐付けられたトークン、スコープ、レート制限、監査イベント、サブジェクトを考慮したストレージに対応する、外部の認可サーバーと MCP 対応ゲートウェイを使用します。一般公開 HTTP の認可とADR-0006を参照してください。

設定

変数	説明
DEBUG_RECORDER_DB	SQLite データベースのパスを上書きします。
HOST	HTTP のバインド先ホストです。デフォルトは 127.0.0.1 です。
PORT	HTTP ポートです。デフォルトは 3000 です。
DEBUG_RECORDER_HTTP_TOKEN	プライベート／共有シークレットトークンです。ループバック以外の HTTP では必須ですが、OAuth ではありません。
DEBUG_RECORDER_ALLOWED_HOSTS	カンマ区切りの HTTP Host 許可リストです。
DEBUG_RECORDER_ALLOWED_ORIGINS	カンマ区切りのブラウザー Origin 許可リストです。
DEBUG_RECORDER_MAX_BODY_BYTES	HTTP の JSON ボディ上限です。デフォルトは 1048576 です。
DEBUG_RECORDER_REMOTE_HTTP	true、1、または yes でループバック以外の HTTP を有効にします。
DEBUG_RECORDER_REDACT_BEFORE_STORE	true、1、または yes で保存前の編集を有効にします。
LOG_LEVEL	構造化ログの最小レベルです：debug、info、warn、または error。
FUZZY_THRESHOLD	Fuse.js の再ランキングしきい値を上書きします。

ブール値の設定では false、0、no も使用できます。値の大文字と小文字は区別されず、空白は無視されます。サポートされていない値が指定された場合は、ただちにエラーになります。Diagnostics は、変更された環境変数の文字列を再読み込みするのではなく、解決済みの有効な値を報告します。

データとプライバシー

• データベース：better-sqlite3 を使用したローカルの SQLite。
• 検索インデックス：SQLite FTS5 仮想テーブル。
• デフォルトのパス：~/.debug-recorder-mcp/sessions.db。
• マスキング：保存前の任意のマスキングと診断データのマスキング。
• 削除：破壊的な操作には明示的な確認が必要です。
• メンテナンス：ストレージの保持とメンテナンスを参照してください。

better-sqlite3 はネイティブアドオンを使用します。Node のバージョンが変わってバインディングに問題が発生した場合は、npm rebuild better-sqlite3 を実行してください。

Docker

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

イメージは npm ci でインストールし、レビュー済みのネイティブインストールスクリプトを保持したうえで、開発用の依存関係を削除し、非 root の node ユーザーとして実行します。

ドキュメント

公開ドキュメントは npm run docs:site で生成され、GitHub Pages に公開されます。

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

重要なドキュメント：

• 使い方
• クライアント設定のレシピ
• 設定
• アーキテクチャ
• セキュリティ
• パブリック HTTP の認可
• 運用
• トラブルシューティング
• ストレージの保持
• テスト
• リリースフロー
• インストールスクリプトのポリシー
• SBOM/VEX ポリシー
• アーキテクチャ決定記録

開発

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

ローカルで実行するすべてのチェック：

npm run ci:local

リリース準備：

npm run prepublishOnly
npm run check:mcp-registry

リリースと npm への公開

通常のリリースワークフローでは、Release Please を使用してリリースアセットをビルドし、SBOM とチェックサムを生成し、tarball を証明したうえで、GitHub Release のアセットをアップロードし、来歴情報付きで npm に公開します。

最初に npm パッケージを作成する際は、リポジトリシークレット NPM_TOKEN を使用して、手動の Initial npm Token Publish ワークフローを実行してください。パッケージの作成後、npm の信頼された公開を設定すると、通常の Release ワークフローから GitHub OIDC を介して公開できます。詳細はリリースフローを参照してください。

ライセンス

MIT Licenseのもとで公開されています。package.json にも "license": "MIT" と記載されており、npm パッケージには LICENSE が含まれます。

資金援助

このプロジェクトによってデバッグの時間を節約できた場合は、こちらから開発をご支援ください。

• Buy Me a Coffee：https://www.buymeacoffee.com/oaslananka
• GitHub Sponsors：https://github.com/sponsors/oaslananka

資金援助に関するメタデータは、.github/FUNDING.yml と package.json の両方で確認できます。

エージェントプラグインとランタイム設定

このリポジトリは、debug-recorder-mcp の製品レベルのエージェントプラグイン、MCP ランタイム設定、および製品固有のスキルを管理します。中央の agent-tools リポジトリにはこのプラグインを登録する必要がありますが、マニフェストとワークフローの手順は、実際の MCP サーバーパッケージと常に同期できるよう、このリポジトリに置いています。

ファイル	目的
.claude-plugin/plugin.json	Claude Code で有効な製品プラグインマニフェスト。
.mcp.json	Claude Code のプロジェクトローカル MCP サーバー設定。
.codex/config.example.toml	Codex CLI の MCP 設定例。
.vscode/mcp.example.json	VS Code / GitHub Copilot ワークスペースの MCP 設定例。
opencode.example.jsonc	OpenCode プロジェクトの MCP 設定例。
.opencode/skills/	OpenCode ネイティブ形式のミラーリングされたスキル定義。
docs/agent-runtime-config.md	エージェントのランタイム設定と検証に関する注意事項。

プラグインのパッケージングをローカルで検証します。

claude plugin validate .