调试mcp-go包装器
⚠️ 原型-仅用于测试和讨论目的
______________________________________________________________________
Go进程管理器和调试mcp PHP mcp服务器的代理，提供具有内存隔离的自动进程重启。
目的
此Go应用程序充当MCP客户端（如Claude Desktop）和PHP调试MCP服务器之间的透明代理，提供：
- 流程管理：自动PHP进程生命周期管理
- 内存隔离：PHP进程获得自己的内存空间，与Go分开
- 定期重启：PHP进程每60秒重启一次，以防止内存泄漏
- 透明代理：客户端在PHP重启期间不会遇到断开连接
- 消息缓冲：在重新启动窗口期间缓冲消息以防止丢失
特性
- 持久连接：保持与MCP客户端的持续连接
- 自动重新启动：PHP进程每60秒重新启动一次
- 消息缓冲：内存缓冲区（最后100条消息）可防止消息丢失
- 优雅关闭：清晰地处理信号情报/信号
- 错误恢复：PHP进程崩溃时自动重启
- 标准代理：使用官方go-sdk进行透明的stdin/stdout代理
安装
从源代码构建
make build这将创建 debug-mcp-wrapper 当前目录中的二进制文件。
为多个平台构建
make build-all为以下对象创建二进制文件：
- Linux（amd64）
- macOS（amd64、arm64）
- Windows（amd64）
用法
基本用法
./debug-mcp-wrapper --cwd=/path/to/debug-mcp包装器将：
- 更改到指定的工作目录
- 启动PHP MCP服务器(
php bin/debug-mcp) - 客户端和PHP进程之间的代理stdin/stdout
- 每60秒重启一次PHP
- 重启窗口期间缓冲消息
命令行参数
--cwd：工作目录（安装调试mcp的位置）- 必需
例子：
./debug-mcp-wrapper --cwd=/Users/username/projects/my-mcp-server环境变量
DEBUG_MCP_DIR：替代--cwd标志PHP_BINARY：PHP二进制路径（默认值：php)
Claude桌面配置
添加到Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"debug-mcp": {
"command": "/absolute/path/to/debug-mcp-wrapper",
"args": ["--cwd", "/absolute/path/to/debug-mcp"]
}
}
}重要：使用绝对路径，而不是相对路径或 ~.
建筑
Claude Desktop
↓ stdin/stdout
Go Wrapper (this program)
├─ Main Process (persistent)
│ ├─ MCP Protocol Handling (via go-sdk)
│ ├─ Message Buffer (100 messages)
│ └─ 60-second Restart Timer
│
└─ PHP Process (restarted every 60s)
└─ debug-mcp Server工艺流程
- 初始化：Go包装器启动，生成PHP进程
- 正常运行：双向代理消息
- 重新启动触发器：每60秒，计时器就会启动
- 缓冲阶段：传入消息缓冲在内存中
- 进程重新启动：旧PHP被淘汰，新PHP诞生（~1s）
- 重播阶段：发送到新PHP的缓冲消息
- 简历：正常操作继续
消息缓冲
在PHP重启过程中（约1秒）：
- 传入消息存储在循环缓冲区中
- 缓冲区大小：100条消息（可配置）
- 如果缓冲区已满，旧消息将被丢弃
- 重新启动后重播到新进程的消息
- 客户端经历短暂的延迟，没有断开连接
建筑
先决条件
- 达到1.21或更高
- Make（可选，用于Makefile使用）
构建命令
# Install dependencies
make install
# Build binary
make build
# Run tests
make test
# Format code
make fmt
# Run linter
make lint
# Clean artifacts
make clean发展
项目结构
debug-mcp-go-wrapper/
├── cmd/
│ └── debug-mcp-wrapper/
│ └── main.go # Entry point
├── internal/
│ ├── proxy/
│ │ ├── proxy.go # Main proxy coordinator
│ │ ├── process.go # PHP process management
│ │ └── buffer.go # Message buffering
│ └── config/
│ └── config.go # Configuration handling
├── go.mod
├── Makefile
└── README.md关键组件
main.go：入口点
- 解析命令行参数
- 初始化代理
- 处理信号（信号/信号）
- 在主goroutine中启动代理
proxy.go：主要协调员
- 使用官方go-sdk进行MCP协议
- 管理PHP子流程生命周期
- 实施60秒重启定时器
- 协调消息缓冲
- 在客户端和PHP之间代理stdio
process.go：流程管理
- 启动PHP进程：
php bin/debug-mcp - 管理stdin/stdout/stderr管道
- 检测进程退出
- 优雅的停止（SIGTERM然后SIGKILL）
buffer.go：消息缓冲区
- 线程安全圆形缓冲区
- 可配置大小（默认值：100）
- 防止重启过程中消息丢失
- 有限内存使用
实现注意事项
Go SDK集成: 使用 modelcontextprotocol/go-sdk 对于MCP协议处理：
- 用于stdin/stdout通信的StdioTransport
- 自动JSON-RPC消息帧
- SDK保证协议合规性
重新启动逻辑:
ticker := time.NewTicker(60 * time.Second)
for range ticker.C {
proxy.RestartPHP()
}错误处理:
- PHP崩溃→ 立即重启
- 反复撞车→ 日志错误，请继续尝试
- 关闭包装器→ 优雅的PHP终止
故障排除
PHP进程无法启动
检查：
- 工作目录正确(
--cwd调试mcp安装的要点） - PHP二进制文件在PATH或set中
PHP_BINARY环境变量 bin/debug-mcp存在并且可执行- composer安装已在debug mcp目录中运行
重启过程中丢失的消息
- 缓冲区大小可能太小
- 检查日志中的缓冲区溢出警告
- 如果需要，增加代码中的缓冲区大小
内存使用率高
- 正常：Go包装器使用最少的内存
- PHP进程内存被隔离，每60秒重置一次
- 如果Go内存增长，请检查缓冲区是否泄漏
连接中断
- 不应该发生-Go保持持久连接
- 检查Claude Desktop日志是否有错误
- 验证包装器是否正在运行（未被杀死/崩溃）
监控
日志
包装器将日志记录到stderr：
- PHP进程启动/停止
- 重新启动事件
- 缓冲区统计信息
- 错误条件
例子：
2024-11-29T15:30:00Z [INFO] Starting PHP process
2024-11-29T15:30:00Z [INFO] PHP process started (PID: 12345)
2024-11-29T15:31:00Z [INFO] Restart timer triggered
2024-11-29T15:31:00Z [INFO] Buffering messages during restart
2024-11-29T15:31:01Z [INFO] PHP process restarted (PID: 12346)
2024-11-29T15:31:01Z [INFO] Replayed 3 buffered messages指标
监控这些指标：
- 重启频率（应每60秒一次）
- 缓冲区使用率（应保持在100条消息以下）
- 重启持续时间（应为约1秒）
- PHP进程崩溃（应该很少见）
演出
- 记忆：Go包装器~10-20MB，PHP进程~50-100MB
- 重新启动时间：约1秒用于进程生成和缓冲区重放
- 消息延迟：正常运行时\<10ms，重启时~1s
- 中央处理器：等待I/O的时间最少，大多处于空闲状态
需求
- 达到1.21或更高
- PHP 8.1或更高版本
- 调试已安装的mcp服务器
仓库
github：https://github.com/wachterjohannes/debug-mcp-go-wrapper
许可证
麻省理工学院