mcp-spy
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMCP Spy - Debug MCP Communication
MCP Spy - 调试MCP通信
Debug Model Context Protocol server integrations.
调试模型上下文协议（Model Context Protocol）服务器集成。
Overview
概述
MCP Spy helps debug:
- Message traffic between Claude and MCP servers
- Latency issues
- Failed requests
- Protocol compliance
MCP Spy可帮助调试以下问题：
- Claude与MCP服务器之间的消息流量
- 延迟问题
- 请求失败
- 协议合规性
Traffic Analysis
流量分析
View Recent Traffic
查看近期流量
bash
undefinedbash
undefinedCheck MCP logs
查看MCP日志
tail -f ~/.claude/debug/mcp-*.log
tail -f ~/.claude/debug/mcp-*.log
Or specific server
或指定服务器
tail -f ~/.claude/debug/mcp-cm.log
undefinedtail -f ~/.claude/debug/mcp-cm.log
undefinedFilter by Type
按类型过滤
bash
undefinedbash
undefinedTool calls only
仅查看工具调用
grep "tool_use" ~/.claude/debug/mcp-*.log
grep "tool_use" ~/.claude/debug/mcp-*.log
Errors only
仅查看错误
grep -i "error|failed" ~/.claude/debug/mcp-*.log
grep -i "error|failed" ~/.claude/debug/mcp-*.log
Specific tool
特定工具
grep "beads_add" ~/.claude/debug/mcp-*.log
undefinedgrep "beads_add" ~/.claude/debug/mcp-*.log
undefinedLatency Analysis
延迟分析
Measure Response Times
测量响应时间
bash
undefinedbash
undefinedTime a specific tool
测试特定工具的耗时
time claude --print "Run beads_ready" --dangerously-skip-permissions 2>&1 | head -1
undefinedtime claude --print "Run beads_ready" --dangerously-skip-permissions 2>&1 | head -1
undefinedFind Slow Calls
查找缓慢调用
bash
undefinedbash
undefinedLook for latency warnings in logs
在日志中查找延迟警告
grep -i "timeout|slow|latency" ~/.claude/debug/mcp-*.log
undefinedgrep -i "timeout|slow|latency" ~/.claude/debug/mcp-*.log
undefinedFailed Request Analysis
失败请求分析
Find Failures
查找失败案例
bash
undefinedbash
undefinedAll errors
所有错误
grep -i "error" ~/.claude/debug/mcp-*.log
grep -i "error" ~/.claude/debug/mcp-*.log
Parse error responses
解析错误响应
grep ""error":" ~/.claude/debug/mcp-*.log | jq '.'
undefinedgrep ""error":" ~/.claude/debug/mcp-*.log | jq '.'
undefinedCommon Issues
常见问题
- Connection refused - Server not running
- Timeout - Server too slow
- Invalid JSON - Malformed request/response
- Unknown tool - Tool not registered
- Connection refused - 服务器未运行
- Timeout - 服务器响应过慢
- Invalid JSON - 请求/响应格式错误
- Unknown tool - 工具未注册
MCP Server Debug
MCP服务器调试
Check Server Status
检查服务器状态
bash
undefinedbash
undefinedTest server connection
测试服务器连接
undefinedundefinedServer Logs
服务器日志
bash
undefinedbash
undefinedView server logs (if running as process)
查看服务器日志（如果以进程运行）
tail -f logs/mcp-server.log
tail -f logs/mcp-server.log
Or in terminal running server
或在运行服务器的终端中查看
Logs appear in stdout
日志会输出到标准输出
undefinedundefinedTest Tool Directly
直接测试工具
bash
undefinedbash
undefinedCall tool directly
直接调用工具
curl -X POST http://localhost:3000/mcp/call_tool
-H "Content-Type: application/json"
-d '{ "name": "beads_ready", "args": {} }'
-H "Content-Type: application/json"
-d '{ "name": "beads_ready", "args": {} }'
undefinedcurl -X POST http://localhost:3000/mcp/call_tool
-H "Content-Type: application/json"
-d '{ "name": "beads_ready", "args": {} }'
-H "Content-Type: application/json"
-d '{ "name": "beads_ready", "args": {} }'
undefinedProtocol Debugging
协议调试
Inspect Messages
检查消息
bash
undefinedbash
undefinedPretty print JSON messages
格式化打印JSON消息
grep "message" ~/.claude/debug/mcp-*.log | jq '.'
undefinedgrep "message" ~/.claude/debug/mcp-*.log | jq '.'
undefinedValidate Requests
验证请求
bash
undefinedbash
undefinedCheck request format
检查请求格式
gemini -m pro -o text -e "" "Validate this MCP request format:
$(grep "request" ~/.claude/debug/mcp-*.log | tail -1)
Check:
- Required fields present
- Types correct
- Schema compliance"
undefinedgemini -m pro -o text -e "" "Validate this MCP request format:
$(grep "request" ~/.claude/debug/mcp-*.log | tail -1)
Check:
- Required fields present
- Types correct
- Schema compliance"
undefinedTroubleshooting Guide
故障排除指南
Server Won't Start
服务器无法启动
bash
undefinedbash
undefinedCheck if port in use
检查端口是否被占用
lsof -i :3000
lsof -i :3000
Check server process
检查服务器进程
ps aux | grep mcp
ps aux | grep mcp
Start with verbose
以 verbose 模式启动
node server/index.ts --verbose
undefinednode server/index.ts --verbose
undefinedTool Not Found
工具未找到
bash
undefinedbash
undefinedList available tools
列出可用工具
curl http://localhost:3000/mcp/list_tools | jq '.tools[].name'
curl http://localhost:3000/mcp/list_tools | jq '.tools[].name'
Check tool registration
检查工具注册情况
grep "registerTool|toolRegistry" server/*.ts
undefinedgrep "registerTool|toolRegistry" server/*.ts
undefinedSlow Responses
响应缓慢
bash
undefinedbash
undefinedProfile tool execution
分析工具执行耗时
time curl -X POST http://localhost:3000/mcp/call_tool
-H "Content-Type: application/json"
-d '{"name": "slow_tool", "args": {}}'
-H "Content-Type: application/json"
-d '{"name": "slow_tool", "args": {}}'
time curl -X POST http://localhost:3000/mcp/call_tool
-H "Content-Type: application/json"
-d '{"name": "slow_tool", "args": {}}'
-H "Content-Type: application/json"
-d '{"name": "slow_tool", "args": {}}'
Check for blocking operations
检查阻塞操作
grep -i "await|sync" tools/slow_tool/index.ts
undefinedgrep -i "await|sync" tools/slow_tool/index.ts
undefinedJSON Parse Errors
JSON解析错误
bash
undefinedbash
undefinedFind malformed JSON
查找格式错误的JSON
grep -B 5 "JSON|parse" ~/.claude/debug/mcp-*.log | grep -i error
grep -B 5 "JSON|parse" ~/.claude/debug/mcp-*.log | grep -i error
Validate JSON
验证JSON格式
echo '{"test": ...}' | jq '.'
undefinedecho '{"test": ...}' | jq '.'
undefinedMonitoring
监控
Watch Traffic Live
实时查看流量
bash
undefinedbash
undefinedReal-time log monitoring
实时日志监控
tail -f ~/.claude/debug/mcp-*.log | grep --line-buffered "tool_use|result"
undefinedtail -f ~/.claude/debug/mcp-*.log | grep --line-buffered "tool_use|result"
undefinedTraffic Stats
流量统计
bash
undefinedbash
undefinedCount calls per tool
统计各工具的调用次数
grep "tool_use" ~/.claude/debug/mcp-.log |
grep -oP '"name":"[^"]"' |
sort | uniq -c | sort -rn
grep -oP '"name":"[^"]"' |
sort | uniq -c | sort -rn
undefinedgrep "tool_use" ~/.claude/debug/mcp-.log |
grep -oP '"name":"[^"]"' |
sort | uniq -c | sort -rn
grep -oP '"name":"[^"]"' |
sort | uniq -c | sort -rn
undefinedHealth Dashboard
健康仪表盘
bash
#!/bin/bashbash
#!/bin/bashmcp-health.sh
mcp-health.sh
echo "=== MCP Server Health ==="
echo "=== MCP Server Health ==="
Check server
检查服务器状态
if curl -s http://localhost:3000/health > /dev/null 2>&1; then
echo "Server: UP"
else
echo "Server: DOWN"
fi
if curl -s http://localhost:3000/health > /dev/null 2>&1; then
echo "Server: UP"
else
echo "Server: DOWN"
fi
Recent errors
近期错误数
ERRORS=$(grep -c "error" ~/.claude/debug/mcp-*.log 2>/dev/null || echo 0)
echo "Recent errors: $ERRORS"
ERRORS=$(grep -c "error" ~/.claude/debug/mcp-*.log 2>/dev/null || echo 0)
echo "Recent errors: $ERRORS"
Tool count
工具数量
TOOLS=$(curl -s http://localhost:3000/mcp/list_tools 2>/dev/null | jq '.tools | length' || echo 0)
echo "Registered tools: $TOOLS"
undefinedTOOLS=$(curl -s http://localhost:3000/mcp/list_tools 2>/dev/null | jq '.tools | length' || echo 0)
echo "Registered tools: $TOOLS"
undefinedBest Practices
最佳实践
- Enable logging - Keep debug logs on during development
- Check health first - Verify server running before debugging
- Test isolation - Test tools directly before through Claude
- Monitor latency - Watch for degradation
- Log rotation - Don't let logs grow unbounded
- Error alerts - Set up monitoring for failures
- 启用日志 - 开发期间保持调试日志开启
- 先检查健康状态 - 调试前先验证服务器是否运行
- 隔离测试 - 通过Claude测试前先直接测试工具
- 监控延迟 - 留意性能下降情况
- 日志轮转 - 避免日志无限制增长
- 错误告警 - 为故障设置监控告警