MCP Debug

🚀 MCP Debug

Model Context Protocol (MCP) サーバーのデバッグと開発ツールです。このツールは、MCPサーバーの開発とテストを高速化し、ホットスワップ、セッション記録、自動再生テストなどの機能を提供します。

🚀 クイックスタート

設定ファイルを使用してプロキシを起動

uvx mcp-debug --proxy --config config.yaml

対話型テストのために mcp-tui を使用

mcp-tui uvx mcp-debug --proxy --config config.yaml

✨ 主な機能

ホットスワップ開発

• MCPクライアントを切断することなくサーバーのバイナリを置き換えることができます。
• 開発中にサーバーを動的に追加または削除できます。
• ツール名を保持し、同じインターフェースで新しい実装を提供します。
• バイナリ置換時には、クライアントの切断と再接続をスムーズに行います。

セッション記録と再生

• デバッグやドキュメント用にJSON-RPCトラフィックを記録します。
• クライアント再生モードでは、記録したリクエストをサーバーに再送信してテストできます。
• サーバー再生モードでは、記録したレスポンスをクライアントに再送信してテストできます。
• 記録したセッションを使用して回帰テストを行うことができます。

開発用プロキシ

• ツールの接頭辞を使用して複数のサーバーを集約します。
• リアルタイムで接続を監視します。
• サーバーのライフサイクルを制御するための管理APIを提供します。
• 包括的なロギングを行います。

📦 インストール

uvx を使用する場合（Python - 推奨）

uvx mcp-debug --help

npx を使用する場合（Node.js）

npx @standardbeagle/mcp-debug --help

グローバルにインストールする場合

pip install mcp-debug              # Python
npm install -g @standardbeagle/mcp-debug  # Node.js

ソースからビルドする場合

go install github.com/standardbeagle/mcp-debug@latest

💻 使用例

プロキシモード

基本的なプロキシ

uvx mcp-debug --proxy --config config.yaml

記録付き

uvx mcp-debug --proxy --config config.yaml --record session.jsonl

カスタムログファイルを使用する場合

uvx mcp-debug --proxy --config config.yaml --log /tmp/debug.log

管理ツール:

• server_add - サーバーを追加する: {name: "fs", command: "npx -y @mcp/filesystem /path"}
• server_remove - サーバーを完全に削除する
• server_disconnect - サーバーを切断する（ツールはエラーを返す）
• server_reconnect - 新しいコマンドでサーバーを再接続する
• server_list - すべてのサーバーとその状態を表示する

再生モード

記録したリクエストをサーバーに再送信してテストする

uvx mcp-debug --playback-client session.jsonl | ./your-mcp-server

記録したレスポンスをクライアントに再送信してテストする

mcp-tui uvx mcp-debug --playback-server session.jsonl

📚 ドキュメント

設定ファイル

# config.yaml
servers:
  - name: "filesystem"
    prefix: "fs"
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/filesystem", "/home/user"]
    timeout: "30s"

proxy:
  healthCheckInterval: "30s"
  connectionTimeout: "10s"
  maxRetries: 3

環境変数

MCP_LOG_FILE="/tmp/mcp-debug.log"  # ログの保存場所
MCP_DEBUG=1                         # デバッグログを有効にする
MCP_RECORD_FILE="session.jsonl"     # セッションを自動記録する
MCP_CONFIG_PATH="./config.yaml"     # デフォルトの設定ファイル

開発ワークフロー

# 1. 空の設定ファイルで開始
mcp-tui uvx mcp-debug --proxy --config empty-config.yaml

# 2. サーバーを動的に追加
server_add: {name: myserver, command: ./my-server-v1}

# 3. ツールをテストする: myserver_read_file, myserver_process, など
# 4. 変更を加えて再ビルド
go build -o my-server-v2

# 5. サーバーをホットスワップする
server_disconnect: {name: myserver}
server_reconnect: {name: myserver, command: ./my-server-v2}

# 6. 同じツールが新しい実装ですぐに動作します！

CLIコマンド

uvx mcp-debug --help              # ヘルプを表示する
uvx mcp-debug --version           # バージョンを表示する
uvx mcp-debug config init         # デフォルトの設定ファイルを作成する
uvx mcp-debug config show         # 現在の設定を表示する
uvx mcp-debug config validate     # 設定ファイルを検証する
uvx mcp-debug env list            # 環境変数を一覧表示する
uvx mcp-debug env check           # 必要な環境変数をチェックする
uvx mcp-debug tools list          # ツールの詳細を一覧表示する

プロジェクト構造

mcp-debug/
├── main.go              # CLIエントリーポイント
├── config/              # 設定の読み込み
├── client/              # MCPクライアントの実装
├── integration/         # プロキシサーバーとラッパー
├── discovery/           # ツールの検出
├── proxy/               # リクエストの転送
├── playback/            # 記録と再生
└── test-servers/        # サンプルのMCPサーバー

ビルド

開発用ビルド

go build -o mcp-debug .

バージョン情報付きの本番用ビルド

go build -ldflags "-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)" -o mcp-debug .

テストの実行

go test ./...

🤝 コントリビューション

詳細は CONTRIBUTING.md を参照してください。

📄 ライセンス

MITライセンスです。詳細は LICENSE を参照してください。