mcp-debug

MCP Debug

Model Context Protocol (MCP) サーバー向けのデバッグおよび開発ツールです。

MCP Debug を使うと、ホットスワップ、セッション記録、自動再生テストにより、MCP サーバーを迅速に開発およびテストできます。

機能

ホットスワップ開発

• MCP クライアントを切断せずにサーバーバイナリを置き換えます
• 開発中にサーバーを動的に追加／削除します
• ツール名を維持します。同じインターフェースで新しい実装を利用できます
• バイナリ置き換え時に、正常な切断／再接続ワークフローを実現します

セッションの記録と再生

• デバッグやドキュメント作成のために JSON-RPC トラフィックを記録します
• クライアント再生モード：サーバーをテストするためにリクエストを再生します
• サーバー再生モード：クライアントをテストするためにレスポンスを再生します
• 記録したセッションを使ったリグレッションテスト

開発プロキシ

• ツール名にプレフィックスを付けて複数のサーバーを集約します
• 接続をリアルタイムで監視します
• サーバーのライフサイクルを制御する管理 API
• 包括的なロギング

インストール

# Using uvx (Python - recommended)
uvx mcp-debug --help

# Using npx (Node.js)
npx @standardbeagle/mcp-debug --help

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

# Or build from source
go install github.com/standardbeagle/mcp-debug@latest

クイックスタート

# Start proxy with a config file
uvx mcp-debug --proxy --config config.yaml

# Or with mcp-tui for interactive testing
mcp-tui uvx mcp-debug --proxy --config config.yaml

使用方法

プロキシモード

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

# With recording
uvx mcp-debug --proxy --config config.yaml --record session.jsonl

# With custom log file
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 - すべてのサーバーとステータスを表示します

再生モード

# Replay recorded requests to test a server
uvx mcp-debug --playback-client session.jsonl | ./your-mcp-server

# Replay recorded responses to test a client
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"  # Log location
MCP_DEBUG=1                         # Enable debug logging
MCP_RECORD_FILE="session.jsonl"     # Auto-record sessions
MCP_CONFIG_PATH="./config.yaml"     # Default config

開発ワークフロー

# 1. Start with empty config
mcp-tui uvx mcp-debug --proxy --config empty-config.yaml

# 2. Add your server dynamically
server_add: {name: myserver, command: ./my-server-v1}

# 3. Test tools: myserver_read_file, myserver_process, etc.

# 4. Make changes and rebuild
go build -o my-server-v2

# 5. Hot-swap the server
server_disconnect: {name: myserver}
server_reconnect: {name: myserver, command: ./my-server-v2}

# 6. Same tools work immediately with new implementation!

CLI コマンド

uvx mcp-debug --help              # Show help
uvx mcp-debug --version           # Show version
uvx mcp-debug config init         # Create default config
uvx mcp-debug config show         # Show current config
uvx mcp-debug config validate     # Validate config file
uvx mcp-debug env list            # List environment variables
uvx mcp-debug env check           # Check required env vars
uvx mcp-debug tools list          # List tools with details

プロジェクト構成

mcp-debug/
├── main.go              # CLI entry point
├── config/              # Configuration loading
├── client/              # MCP client implementation
├── integration/         # Proxy server and wrapper
├── discovery/           # Tool discovery
├── proxy/               # Request forwarding
├── playback/            # Recording and playback
└── test-servers/        # Example MCP servers

ビルド

# Development build
go build -o mcp-debug .

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

# Run tests
go test ./...

貢献

ガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT ライセンスの詳細については、LICENSE を参照してください。