调试

​

调试工具概览

1. MCP Inspector：交互式、与传输无关的 测试 UI。可连接到 stdio 或 Streamable HTTP 服务器，调用 tools、 prompts 和 resources，并观察 通知流。这应该是你的第一站。
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="服务器已成功启动",
    )
    return "done"

await server.sendLoggingMessage({
  level: "info",
  data: "服务器已成功启动",
});

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

​

常见问题

​

工作目录

• 通过客户端配置启动的服务器，其工作目录可能是 未定义的（如 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 的“参数无效”代码，并且会在许多 场景中返回。一个常见原因是服务器向 未声明该能力的客户端发送 sampling 或 elicitation 请求。请检查 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. 提供信息
   • 日志摘录
   • 配置文件
   • 复现步骤
   • 环境详情

​

后续步骤