調試

在開發 MCP 服務器或將其與應用程序集成時，進行有效的調試至關重要。本指南涵蓋了 MCP 生態系統中可用的調試工具和方法。

本指南適用於 macOS。其他平臺的指南即將推出。

調試工具概述

MCP 提供了多種不同級別的調試工具：

  1. MCP 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. 啟用 DevTools：
jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json
  1. 打開 DevTools：Command-Option-Shift-i

注意：您將看到兩個 DevTools 窗口：

  • 主內容窗口
  • 應用程序標題欄窗口

使用 Console 面板檢查客戶端錯誤。

使用 Network 面板檢查：

  • 消息負載
  • 連接時間

常見問題

環境變量

MCP 服務器僅自動繼承一部分環境變量，如 USER、HOME 和 PATH。

要覆蓋默認變量或提供自定義變量，可以在 claude_desktop_config.json 中指定 env 鍵：

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

服務器初始化

常見的初始化問題：

  1. 路徑問題

    • 服務器可執行文件路徑不正確
    • 缺少必需文件
    • 權限問題

  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.sendLoggingMessage({
      level: "info",
      data: "服務器啟動成功",
    });
    ```

重要事件記錄：

  • 初始化步驟
  • 資源訪問
  • 工具執行
  • 錯誤條件
  • 性能指標

客戶端日誌

在客戶端應用程序中：

  1. 啟用調試日誌
  2. 監控網絡流量
  3. 跟蹤消息交換
  4. 記錄錯誤狀態

調試工作流程

開發週期

  1. 初始開發

    • 使用 Inspector 進行基本測試
    • 實現核心功能
    • 添加日誌記錄點

  2. 集成測試

    • 在 Claude 桌面中測試
    • 監控日誌
    • 檢查錯誤處理

測試更改

高效測試更改：

  • 配置更改：重啟 Claude 桌面
  • 服務器代碼更改：使用 Command-R 重新加載
  • 快速迭代：在開發過程中使用 Inspector

最佳實踐

日誌策略

  1. 結構化日誌

    • 使用一致的格式
    • 包含上下文
    • 添加時間戳
    • 跟蹤請求 ID

  2. 錯誤處理

    • 記錄堆棧跟蹤
    • 包含錯誤上下文
    • 跟蹤錯誤模式
    • 監控恢復

  3. 性能跟蹤

    • 記錄操作時間
    • 監控資源使用
    • 跟蹤消息大小
    • 測量延遲

安全考慮

調試時：

  1. 敏感數據

    • 清理日誌
    • 保護憑據
    • 屏蔽個人信息

  2. 訪問控制

    • 驗證權限
    • 檢查身份驗證
    • 監控訪問模式

獲取幫助

遇到問題時：

  1. 第一步

    • 檢查服務器日誌
    • 使用 Inspector 測試
    • 查看配置
    • 驗證環境

  2. 支持渠道

    • GitHub 問題
    • GitHub 討論

  3. 提供信息

    • 日誌摘錄
    • 配置文件
    • 重現步驟
    • 環境詳情

下一步

MCP Inspector
學習使用 MCP Inspector