全面调试模型上下文协议（MCP）集成的指南

在开发 MCP 服务器或将其与应用程序集成时，有效的调试至关重要。本指南涵盖了 MCP 生态系统中可用的调试工具和方法。

本指南适用于 macOS。其他平台的指南将很快推出。

调试工具概述

MCP 提供了多个用于不同级别调试的工具：

  1. MCP 检查器（MCP Inspector）

  2. Claude 桌面开发者工具（Claude Desktop Developer Tools）

    • 集成测试
    • 日志收集
    • Chrome 开发者工具集成

  3. 服务器日志（Server Logging）

    • 自定义日志实现
    • 错误跟踪
    • 性能监控

在 Claude 桌面上进行调试

检查服务器状态

Claude.app 界面提供基本的服务器状态信息：

  1. 点击 调试 - 图1 图标查看：

    • 连接的服务器
    • 可用的提示和资源

  2. 点击 调试 - 图2 图标查看：

    • 提供给模型的工具

查看日志

通过 Claude 桌面查看详细的 MCP 日志：

  1. # 实时跟踪日志
  2. tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

日志捕获：

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

使用 Chrome 开发者工具

在 Claude 桌面内访问 Chrome 的开发者工具，以调查客户端错误：

  1. 创建 developer_settings.json 文件，并将 allowDevTools 设置为 true：
  1. echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
  1. 打开开发者工具：Command-Option-Shift-i

注意：你会看到两个开发者工具窗口：

  • 主要内容窗口
  • 应用程序标题栏窗口

使用 Console 面板检查客户端错误。

使用 Network 面板检查：

  • 消息负载
  • 连接时序

常见问题

工作目录

在使用 MCP 服务器与 Claude 桌面时：

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

例如，在 claude_desktop_config.json 中使用：

  1. {
  2.   "command": "npx",
  3.   "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
  4. }

而不是像 ./data 这样的相对路径。

环境变量

MCP 服务器仅会自动继承一部分环境变量，如 USER、HOME 和 PATH。

要覆盖默认变量或提供自定义变量，可以在 claude_desktop_config.json 中指定 env 键：

  1. {
  2.   "myserver": {
  3.     "command": "mcp-server-myapp",
  4.     "env": {
  5.       "MYAPP_API_KEY": "some_key"
  6.     }
  7.   }
  8. }

服务器初始化

常见的初始化问题：

  1. 路径问题

    • 服务器可执行文件路径错误
    • 缺少必需的文件
    • 权限问题
    • 尝试为 command 使用绝对路径

  2. 配置错误

    • 无效的 JSON 语法
    • 缺少必需的字段
    • 类型不匹配

  3. 环境问题

    • 缺少环境变量
    • 环境变量值错误
    • 权限限制

连接问题

当服务器无法连接时：

  1. 检查 Claude 桌面日志
  2. 验证服务器进程是否正在运行
  3. 使用 检查器 独立测试
  4. 验证协议兼容性

实现日志记录

服务器端日志

当构建使用本地 stdio 传输 的服务器时，所有日志到 stderr（标准错误）的消息将被主机应用程序（例如，Claude 桌面）自动捕获。

本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议的操作。

对于所有 传输，你也可以通过发送日志消息通知将日志提供给客户端：

  • Python
  • TypeScript
  1. server.request_context.session.send_log_message(
  2.   level="info",
  3.   data="Server started successfully",
  4. )

需要记录的重要事件：

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

客户端日志

在客户端应用程序中：

  1. 启用调试日志
  2. 监控网络流量
  3. 跟踪消息交换
  4. 记录错误状态

调试工作流程

开发周期

  1. 初始开发

    • 使用 检查器 进行基本测试
    • 实现核心功能
    • 添加日志点

  2. 集成测试

    • 在 Claude 桌面测试
    • 监控日志
    • 检查错误处理

测试更改

为了有效测试更改：

  • 配置更改：重新启动 Claude 桌面
  • 服务器代码更改：使用 Command-R 重新加载
  • 快速迭代：在开发过程中使用 检查器

最佳实践

日志记录策略

  1. 结构化日志

    • 使用一致的格式
    • 包括上下文
    • 添加时间戳
    • 跟踪请求 ID

  2. 错误处理

    • 记录堆栈跟踪
    • 包括错误上下文
    • 跟踪错误模式
    • 监控恢复情况

  3. 性能跟踪

    • 记录操作时长
    • 监控资源使用
    • 跟踪消息大小
    • 测量延迟

安全考虑

在调试时：

  1. 敏感数据

    • 清理日志
    • 保护凭证
    • 掩盖个人信息

  2. 访问控制

    • 验证权限
    • 检查身份验证
    • 监控访问模式

获取帮助

遇到问题时：

  1. 第一步

    • 检查服务器日志
    • 使用 检查器 测试
    • 审查配置
    • 验证环境

  2. 支持渠道

    • GitHub 问题
    • GitHub 讨论

  3. 提供信息

    • 日志摘录
    • 配置文件
    • 重现步骤
    • 环境详情