调试

​

调试工具概览

1. MCP Inspector：交互式、与传输无关的测试 UI。连接到 stdio 或 Streamable HTTP 服务器，调用工具、提示和资源，并观察通知流。这应当是你的第一站。
2. 服务器日志：结构化日志输出到 stderr（stdio 传输）或通过 notifications/message（所有传输）。
3. 客户端开发者工具：大多数 MCP 客户端都暴露日志和连接状态。参见下方在 Claude Desktop 中调试作为一个示例，或查阅你客户端的文档。

​

实现日志记录

​

服务器端日志

@server.tool()
async def my_tool(ctx: Context) -> str:
    await ctx.session.send_log_message(
        level="info",
        data="Server started successfully",
    )
    return "done"

await server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

• 初始化步骤
• 资源访问
• 工具执行
• 错误情况
• 性能指标

​

常见问题

​

工作目录

• 通过客户端配置启动的服务器的工作目录可能是未定义的（例如 macOS 上的 /），因为客户端可能从任何位置启动
• 在你的配置和 .env 文件中始终使用绝对路径，以确保可靠运行
• 对于直接通过命令行测试服务器，工作目录将是你运行命令的位置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    }
  }
}

​

环境变量

{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

​

服务器初始化

1. 路径问题
   • 不正确的服务器可执行文件路径
   • 缺少必需的文件
   • 权限问题
   • 尝试为 command 使用绝对路径
2. 配置错误
   • 无效的 JSON 语法
   • 缺少必需的字段
   • 类型不匹配
3. 环境问题
   • 缺少环境变量
   • 不正确的变量值
   • 权限限制

​

连接问题

1. 检查客户端日志
2. 验证服务器进程正在运行
3. 使用 Inspector 独立测试
4. 验证协议兼容性
5. 检查能力协商：错误 -32602 是标准的 JSON-RPC “Invalid params” 代码，会在许多上下文中返回。一个常见原因是服务器向未声明相应能力的客户端发送了采样或征询请求。检查 initialize 交换以验证双方都声明了你所期望的内容

​

在 Claude Desktop 中调试

​

检查服务器状态

​

查看日志

• macOS：~/Library/Logs/Claude
• Windows：%APPDATA%\Claude\logs

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

type "$env:AppData\Claude\logs\mcp*.log"

• 服务器连接事件
• 配置问题
• 运行时错误
• 消息交换

​

使用 Chrome DevTools

1. 创建一个 developer_settings.json 文件，并将 allowDevTools 设为 true：

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"

2. 打开 DevTools：Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）

• 主内容窗口
• 应用标题栏窗口

• 消息负载
• 连接时序

​

调试工作流

​

开发周期

1. 初始开发
   • 使用 Inspector 进行基本测试
   • 实现核心功能
   • 添加日志记录点
2. 集成测试
   • 在你的目标 MCP 客户端中测试
   • 监控日志
   • 检查错误处理

​

测试变更

• 配置变更：重启 MCP 客户端
• 服务器代码变更：重启客户端（对于 Claude Desktop，完全退出并重新打开；仅关闭窗口是不够的）
• 快速迭代：在开发过程中使用 Inspector

​

最佳实践

​

日志策略

1. 结构化日志
   • 使用一致的格式
   • 包含上下文
   • 添加时间戳
   • 跟踪请求 ID
2. 错误处理
   • 记录堆栈跟踪
   • 包含错误上下文
   • 跟踪错误模式
   • 监控恢复
3. 性能跟踪
   • 记录操作时序
   • 监控资源使用
   • 跟踪消息大小
   • 测量延迟

​

安全考量

1. 敏感数据
   • 净化日志
   • 保护凭据
   • 屏蔽个人信息
2. 访问控制
   • 验证权限
   • 检查身份认证
   • 监控访问模式

​

获取帮助

1. 第一步
   • 检查服务器日志
   • 使用 Inspector 测试
   • 审查配置
   • 验证环境
2. 支持渠道
   • GitHub issues
   • GitHub discussions
3. 提供信息
   • 日志摘录
   • 配置文件
   • 复现步骤
   • 环境详情

​

后续步骤