MCP Debug

🚀 MCP調試工具

MCP調試工具是一款專門為模型上下文協議（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。