Diagnose MCP

诊断mcp

MCP协议代理服务器-用于调试和监视模型上下文协议（MCP）服务器的透明代理。

特性

• 本地MCP服务器代理：拦截并记录客户端和本地服务器之间的所有MCP消息
• 远程WebSocket支持：通过HTTP/WebSocket连接到远程MCP服务器
• 透明直通：邮件转发时不做任何修改
• 详细日志：跟踪请求、响应、通知和进度更新
• 日志文件支持：将日志写入支持动态模式的文件({timestamp}, {session}, {pid})
• Azure Blob日志记录：为开发/测试环境定期将日志上传到Azure Blob存储（每10秒一次）
• 文件监视：监视文件的更改并显示新内容（尾部行为，非阻塞）
• 文本格式 （默认）：人类可读的时间戳、日志级别、消息类型
• JSON格式 (--json)：用于其他工具解析的结构化输出
• 详细模式 (--verbose)：包括完整的消息有效载荷（可读文本或base64二进制数据）
• 环境传递：服务器继承所有父环境变量
• 优雅地关闭：具有会话统计信息的信号处理（SIGTERM/SIGINT）

安装

go install github.com/shizhMSFT/diagnose-mcp/cmd/diagnose-mcp@latest

或者从源代码构建：

git clone https://github.com/shizhMSFT/diagnose-mcp.git
cd diagnose-mcp
go build -o diagnose-mcp ./cmd/diagnose-mcp

用法

本地模式（代理本地MCP服务器）

diagnose-mcp  [server-args...]

示例：

# Basic usage
diagnose-mcp ./my-mcp-server

# With server arguments
diagnose-mcp ./my-mcp-server --port 8080 --config server.json

# Verbose mode (shows full message payloads)
diagnose-mcp --verbose ./my-mcp-server

# JSON output format
diagnose-mcp --json ./my-mcp-server | jq .

# Write logs to file with timestamp and session ID (ordered chronologically)
diagnose-mcp --log-file "logs/{timestamp}-{session}.log" ./my-mcp-server

# Periodically upload logs to Azure Blob Storage (for dev/test without file access)
diagnose-mcp --log-blob-url "https://.blob.core.windows.net//?" ./my-mcp-server

# Watch files for changes
diagnose-mcp --watch /tmp/server.log --watch /tmp/config.json ./my-mcp-server

# Remote WebSocket server
diagnose-mcp --remote ws://localhost:8080/mcp

Azure Blob存储日志记录（开发/测试）

对于无法导出日志文件的环境，请将日志上传到Azure Blob存储。\ 日志在本地写入，每10秒上传一次到块blob。\ 注： 需要现有的Azure存储帐户。

# Quick setup with helper script
./examples/setup-azure-blob-logging.sh --account mystorageaccount

# Use the generated URL
export LOG_BLOB_URL="https://..."
diagnose-mcp --log-blob-url "$LOG_BLOB_URL" ./my-mcp-server

看 示例/azule-blob-logging.md 了解详细的设置和使用方法。

GitHub复制集成

您可以使用 diagnose-mcp 作为调试和监控GitHub Copilot Coding Agent使用的MCP服务器的透明代理。

MCP配置模板

将以下配置添加到Copilot MCP设置中，以代理现有的MCP服务器：

{
  "mcpServers": {
    "your-mcp-server": {
      "type": "local",
      "command": "bash",
      "args": [
        "-c",
        "cd $(mktemp -d) && curl -sSL https://github.com/shizhMSFT/diagnose-mcp/releases/download/v0.2.0/diagnose-mcp_0.2.0_linux_amd64.tar.gz | tar -xz && ./diagnose-mcp \"$@\"",
        "_",
        "--verbose",
        "--log-blob-url",
        "$LOG_BLOB_URL",
        "your-mcp-server-command",
        "server-args..."
      ],
      "env": {
        "LOG_BLOB_URL": "COPILOT_MCP_LOG_BLOB_URL"
      }
    }
  }
}

配置参数：

• your-mcp-server：替换为您的MCP服务器名称
• your-mcp-server-command：替换为启动MCP服务器的实际命令（例如。， npx, python等等）
• server-args...：替换为MCP服务器所需的任何参数
• COPILOT_MCP_LOG_BLOB_URL：GitHub Actions secret的名称，其中包含用于日志上传的Azure Blob存储SAS URL（请参阅上文的“Azure Blob存储日志记录”部分）。在GitHub Copilot环境设置中配置此密钥。
• env：您可以根据需要添加其他环境变量。值可以是GitHub Actions秘密名称（以开头 COPILOT_MCP_)或字符串文字。
• --verbose：在日志中包含完整的消息有效负载（可选，删除以减少详细输出）
• --log-blob-url：将日志上传到Azure Blob存储（对于无法直接访问容器文件系统的GitHub Copilot环境是必需的）

其他选项：

您可以添加其他 diagnose-mcp 旗帜到 args 根据需要排列：

• --json：以JSON格式输出日志
• --watch：监视附加文件（例如。， --watch, /path/to/file.log)

有关使用MCP服务器扩展GitHub Copilot的更多详细信息，请参阅 官方文档.