mcp-spy

MCP Spy - 调试 MCP 通信

调试 Model Context Protocol 服务集成。

概述

MCP Spy 可帮助调试：

• Claude 与 MCP 服务之间的消息流量
• 延迟问题
• 失败的请求
• 协议合规性

流量分析

查看近期流量

# Check MCP logs
tail -f ~/.claude/debug/mcp-*.log

# Or specific server
tail -f ~/.claude/debug/mcp-cm.log

按类型筛选

# Tool calls only
grep "tool_use" ~/.claude/debug/mcp-*.log

# Errors only
grep -i "error\|failed" ~/.claude/debug/mcp-*.log

# Specific tool
grep "beads_add" ~/.claude/debug/mcp-*.log

延迟分析

测量响应时间

# Time a specific tool
time claude --print "Run beads_ready" --dangerously-skip-permissions 2>&1 | head -1

查找缓慢调用

# Look for latency warnings in logs
grep -i "timeout\|slow\|latency" ~/.claude/debug/mcp-*.log

失败请求分析

查找失败

# All errors
grep -i "error" ~/.claude/debug/mcp-*.log

# Parse error responses
grep "\"error\":" ~/.claude/debug/mcp-*.log | jq '.'

常见问题

1. 连接被拒绝 - 服务未运行
2. 超时 - 服务过慢
3. 无效 JSON - 请求/响应格式错误
4. 未知工具 - 工具未注册

MCP 服务调试

检查服务状态

# Test server connection
curl -X POST http://localhost:3000/mcp/list_tools \
  -H "Content-Type: application/json" \
  -d '{}'

服务日志

# View server logs (if running as process)
tail -f logs/mcp-server.log

# Or in terminal running server
# Logs appear in stdout

直接测试工具

# Call tool directly
curl -X POST http://localhost:3000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "beads_ready",
    "args": {}
  }'

协议调试

检查消息

# Pretty print JSON messages
grep "message" ~/.claude/debug/mcp-*.log | jq '.'

验证请求

# Check request format
gemini -m pro -o text -e "" "Validate this MCP request format:

$(grep "request" ~/.claude/debug/mcp-*.log | tail -1)

Check:
1. Required fields present
2. Types correct
3. Schema compliance"

故障排除指南

服务无法启动

# Check if port in use
lsof -i :3000

# Check server process
ps aux | grep mcp

# Start with verbose
node server/index.ts --verbose

找不到工具

# List available tools
curl http://localhost:3000/mcp/list_tools | jq '.tools[].name'

# Check tool registration
grep "registerTool\|toolRegistry" server/*.ts

响应缓慢

# Profile tool execution
time curl -X POST http://localhost:3000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -d '{"name": "slow_tool", "args": {}}'

# Check for blocking operations
grep -i "await\|sync" tools/slow_tool/index.ts

JSON 解析错误

# Find malformed JSON
grep -B 5 "JSON\|parse" ~/.claude/debug/mcp-*.log | grep -i error

# Validate JSON
echo '{"test": ...}' | jq '.'

监控

实时查看流量

# Real-time log monitoring
tail -f ~/.claude/debug/mcp-*.log | grep --line-buffered "tool_use\|result"

流量统计

# Count calls per tool
grep "tool_use" ~/.claude/debug/mcp-*.log | \
  grep -oP '"name":"[^"]*"' | \
  sort | uniq -c | sort -rn

健康仪表盘

#!/bin/bash
# mcp-health.sh

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

# Recent 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"

最佳实践

1. 启用日志 - 开发期间保持调试日志开启
2. 先检查健康状态 - 调试前确认服务正在运行
3. 隔离测试 - 先直接测试工具，再通过 Claude 测试
4. 监控延迟 - 留意性能下降
5. 日志轮转 - 不要让日志无限增长
6. 错误告警 - 为失败设置监控