Skip to Content
文档

教程

调试

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

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

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

​ 调试工具概述

MCP提供了几种不同级别的调试工具：

  1. MCP Inspector

    • 交互式调试界面
    • 直接服务端测试
    • 详情请参阅 Inspector指南

  2. Claude桌面开发者工具

    • 集成测试
    • 日志收集
    • Chrome DevTools集成

  3. 服务端日志

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

​ 在Claude桌面中调试

​

检查服务端状态

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

  1. 点击 图标查看：

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

  2. 点击 图标查看：

    • 提供给模型的工具

​

查看日志

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

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

日志捕获的内容：

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

​

使用Chrome DevTools

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

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

注意：你会看到两个DevTools窗口：

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

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

使用Network面板检查：

  • 消息负载
  • 连接时间

​ 常见问题

​

工作目录

当在Claude桌面中使用MCP服务端时：

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

例如在 claude_desktop_config.json 中，使用：

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

而不是相对路径如 ./data

​

环境变量

MCP服务端自动继承的环境变量只有一部分，如 USER、HOME 和 PATH。

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

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

​

服务端初始化

常见的初始化问题：

  1. 路径问题

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

  2. 配置错误

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

  3. 环境问题

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

​

连接问题

当服务端无法连接时：

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

​ 实现日志记录

​

服务端端日志记录

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

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

对于所有 传输，你还可以通过发送日志消息通知向客户端提供日志记录：

    server.request_context.session.send_log_message(
      level="info",
      data="Server started successfully",
    )

需要记录的重要事件：

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

​

客户端日志记录

在客户端应用程序中：

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

​ 调试工作流程

​

开发周期

  1. 初始开发

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

  2. 集成测试

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

​

测试更改

为了高效测试更改：

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

​ 最佳实践

​

日志记录策略

  1. 结构化日志记录

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

  2. 错误处理

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

  3. 性能跟踪

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

​

安全注意事项

在调试时：

  1. 敏感数据

    • 清理日志
    • 保护凭据
    • 屏蔽个人信息

  2. 访问控制

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

​ 获取帮助

遇到问题时：

  1. 第一步

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

  2. 支持渠道

    • GitHub issues
    • GitHub discussions

  3. 提供信息

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

​ 下一步

学习使用MCP Inspector
使用我们的交互式调试工具测试和检查您的 MCP 服务端
最后更新于:
面向服务端开发者