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。