Mcp Debug

io.github.standardbeagle由 GitHub 账号 standardbeagle 发布v1.1.6更新于 Oct 24, 2026

Debug and develop MCP servers with hot-swapping, session recording, and playback testing

已验证STDIO仅桌面开发者工具安全与监控

概览

AI 生成的概览

一个用于 MCP 服务器的开发代理，支持热替换服务器二进制、录制 JSON-RPC 会话并回放测试。

可以做什么
MCP Debug 作为代理运行在一个或多个 MCP 服务器之前，为工具添加前缀进行聚合，并提供 server_add、server_remove、server_disconnect、server_reconnect、server_list 等管理工具。它可以把 JSON-RPC 流量录制到会话文件，并以客户端或服务器模式回放，用于回归测试。还提供 config init/show/validate、环境检查和工具列表等命令行命令。
适用场景
适合在开发或调试自己的 MCP 服务器时使用，例如希望不重启客户端就替换服务器二进制、检查或回放已录制的会话，或在开发期间把多个服务器聚合到一个端点后面。
运行要求
通过 stdio 在本地运行。可用 uvx（Python）、npx（Node.js）、pip、npm 或 Go 构建安装。代理模式需要 YAML 配置文件。可选环境变量包括 MCP_LOG_FILE、MCP_DEBUG、MCP_RECORD_FILE 和 MCP_CONFIG_PATH。未声明身份验证。
安装前请注意
该代理会根据配置中的命令启动并管理其他服务器进程，因此只应指向你信任的命令。录制会把 JSON-RPC 流量（可能包含工具参数和结果）写入会话文件，应将这些文件视为敏感数据。管理工具可以添加、移除、断开和重新连接服务器。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Debug，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

MCP Debug

A debugging and development tool for Model Context Protocol (MCP) servers.

[Go Version] [MCP Spec] [License: MIT] [PyPI] [npm]

MCP Debug enables rapid development and testing of MCP servers with hot-swapping, session recording, and automated playback testing.

Features

Hot-Swap Development

  • Replace server binaries without disconnecting MCP clients
  • Add/remove servers dynamically during development
  • Tool name preservation - same interface, new implementation
  • Graceful disconnect/reconnect workflow for binary replacement

Session Recording & Playback

  • Record JSON-RPC traffic for debugging and documentation
  • Playback client mode - replay requests to test servers
  • Playback server mode - replay responses to test clients
  • Regression testing with recorded sessions

Development Proxy

  • Multi-server aggregation with tool prefixing
  • Real-time connection monitoring
  • Management API for server lifecycle control
  • Comprehensive logging

Installation

bash
# Using uvx (Python - recommended)uvx mcp-debug --help
# Using npx (Node.js)npx @standardbeagle/mcp-debug --help
# Or install globallypip install mcp-debug              # Pythonnpm install -g @standardbeagle/mcp-debug  # Node.js
# Or build from sourcego install github.com/standardbeagle/mcp-debug@latest

Quick Start

bash
# Start proxy with a config fileuvx mcp-debug --proxy --config config.yaml
# Or with mcp-tui for interactive testingmcp-tui uvx mcp-debug --proxy --config config.yaml

Usage

Proxy Mode

bash
# Basic proxyuvx mcp-debug --proxy --config config.yaml
# With recordinguvx mcp-debug --proxy --config config.yaml --record session.jsonl
# With custom log fileuvx mcp-debug --proxy --config config.yaml --log /tmp/debug.log

Management Tools:

  • server_add - Add a server: {name: "fs", command: "npx -y @mcp/filesystem /path"}
  • server_remove - Remove server completely
  • server_disconnect - Disconnect server (tools return errors)
  • server_reconnect - Reconnect with new command
  • server_list - Show all servers and status

Playback Modes

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

Configuration

yaml
# config.yamlservers:  - name: "filesystem"    prefix: "fs"    transport: "stdio"    command: "npx"    args: ["-y", "@modelcontextprotocol/filesystem", "/home/user"]    timeout: "30s"
proxy:  healthCheckInterval: "30s"  connectionTimeout: "10s"  maxRetries: 3

Environment Variables

bash
MCP_LOG_FILE="/tmp/mcp-debug.log"  # Log locationMCP_DEBUG=1                         # Enable debug loggingMCP_RECORD_FILE="session.jsonl"     # Auto-record sessionsMCP_CONFIG_PATH="./config.yaml"     # Default config

Development Workflow

bash
# 1. Start with empty configmcp-tui uvx mcp-debug --proxy --config empty-config.yaml
# 2. Add your server dynamicallyserver_add: {name: myserver, command: ./my-server-v1}
# 3. Test tools: myserver_read_file, myserver_process, etc.
# 4. Make changes and rebuildgo build -o my-server-v2
# 5. Hot-swap the serverserver_disconnect: {name: myserver}server_reconnect: {name: myserver, command: ./my-server-v2}
# 6. Same tools work immediately with new implementation!

CLI Commands

bash
uvx mcp-debug --help              # Show helpuvx mcp-debug --version           # Show versionuvx mcp-debug config init         # Create default configuvx mcp-debug config show         # Show current configuvx mcp-debug config validate     # Validate config fileuvx mcp-debug env list            # List environment variablesuvx mcp-debug env check           # Check required env varsuvx mcp-debug tools list          # List tools with details

Project Structure

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

Building

bash
# Development buildgo build -o mcp-debug .
# Production build with version infogo build -ldflags "-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse HEAD)" -o mcp-debug .
# Run testsgo test ./...

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

来源：README.md，提交 28f7706

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.1.6最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分