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。