MCP調(diào)試教程 - 綜合指南與實(shí)用工具
調(diào)試模型上下文協(xié)議 （MCP） 集成的綜合指南
在開發(fā) MCP 服務(wù)器或?qū)⑵渑c應(yīng)用程序集成時(shí)，有效的調(diào)試是必不可少的。本指南介紹了 MCP 生態(tài)系統(tǒng)中可用的調(diào)試工具和方法。
本指南適用于 macOS。其他平臺(tái)的指南即將推出。
調(diào)試工具概述
MCP 提供了多種工具，用于在不同級(jí)別進(jìn)行調(diào)試：
- MCP 檢查器
- 交互式調(diào)試界面
- 直接服務(wù)器測(cè)試
- 有關(guān)詳細(xì)信息，請(qǐng)參閱 Inspector 指南
- Claude 桌面開發(fā)人員工具
- 集成測(cè)試
- 日志收集
- Chrome DevTools 集成
- 服務(wù)器日志記錄
- 自定義日志記錄實(shí)現(xiàn)
- 錯(cuò)誤跟蹤
- 性能監(jiān)控
在 Claude Desktop 中調(diào)試
檢查服務(wù)器狀態(tài)
Claude.app 接口提供基本的服務(wù)器狀態(tài)信息：
- 單擊圖標(biāo)
可查看：
- 連接的服務(wù)器
- 可用的提示和資源
- 單擊圖標(biāo)
可查看：
- 可供模型使用的工具
查看日志
查看 Claude Desktop 中的詳細(xì) MCP 日志：
## Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log日志捕獲：
- 服務(wù)器連接事件
- 配置問(wèn)題
- 運(yùn)行時(shí)錯(cuò)誤
- 消息交換
使用 Chrome DevTools
在 Claude Desktop 中訪問(wèn) Chrome 的開發(fā)人員工具以調(diào)查客戶端錯(cuò)誤：
-
創(chuàng)建一個(gè)設(shè)置為 true 的文件：
developer_settings.json``allowDevToolsecho '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json - 打開 DevTools：
Command-Option-Shift-i
注意：您將看到兩個(gè) DevTools 窗口：
- 主內(nèi)容窗口
- 應(yīng)用程序標(biāo)題欄窗口
使用 Console （控制臺(tái)） 面板檢查客戶端錯(cuò)誤。
使用 Network （網(wǎng)絡(luò)） 面板檢查：
- 消息負(fù)載
- 連接計(jì)時(shí)
常見問(wèn)題
工作目錄
將 MCP 服務(wù)器與 Claude Desktop 一起使用時(shí)：
- 通過(guò) 啟動(dòng)的服務(wù)器的工作目錄可能未定義（如在 macOS 上），因?yàn)?Claude Desktop 可以從任何位置啟動(dòng)
claude_desktop_config.json``/ - 在配置和文件中始終使用絕對(duì)路徑，以確保可靠運(yùn)行
.env - 對(duì)于直接通過(guò)命令行測(cè)試服務(wù)器，工作目錄將是運(yùn)行命令的位置
例如，在 中，使用：claude_desktop_config.json
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
而不是像./data
環(huán)境變量
MCP 服務(wù)器僅自動(dòng)繼承環(huán)境變量的子集，如 USER、HOME 和 PATH。
要覆蓋默認(rèn)變量或提供您自己的變量，您可以在 ：env``claude_desktop_config.json
{
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key",
}
}
}服務(wù)器初始化
常見的初始化問(wèn)題：
- 路徑問(wèn)題
- 服務(wù)器可執(zhí)行文件路徑不正確
- 缺少必需的文件
- 權(quán)限問(wèn)題
- 嘗試對(duì)
command
- 配置錯(cuò)誤
- 無(wú)效的 JSON 語(yǔ)法
- 缺少必填字段
- 類型不匹配
- 環(huán)境問(wèn)題
- 缺少環(huán)境變量
- 變量值不正確
- 權(quán)限限制
連接問(wèn)題
當(dāng)服務(wù)器無(wú)法連接時(shí)：
- 檢查 Claude Desktop 日志
- 驗(yàn)證服務(wù)器進(jìn)程是否正在運(yùn)行
- 使用 Inspector 獨(dú)立測(cè)試
- 驗(yàn)證協(xié)議兼容性
實(shí)施日志記錄
服務(wù)器端日志記錄
當(dāng)構(gòu)建使用本地 stdio 傳輸的服務(wù)器時(shí)，記錄到 stderr （標(biāo)準(zhǔn)錯(cuò)誤） 的所有消息將被主機(jī)應(yīng)用程序（例如 Claude Desktop）自動(dòng)捕獲。
本地 MCP 服務(wù)器不應(yīng)將消息記錄到 stdout（標(biāo)準(zhǔn)輸出），因?yàn)檫@會(huì)干擾協(xié)議作。
對(duì)于所有傳輸層您還可以通過(guò)發(fā)送日志消息通知向客戶端提供日志記錄：
Python
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)TypeScript
server.request_context.session.send_log_message(
level="info",
data="Server started successfully",
)要記錄的重要事件：
- 初始化步驟
- 資源訪問(wèn)
- 工具執(zhí)行
- 錯(cuò)誤條件
- 性能指標(biāo)
客戶端日志記錄
在客戶端應(yīng)用程序中：
- 啟用調(diào)試日志記錄
- 監(jiān)控網(wǎng)絡(luò)流量
- 跟蹤消息交換
- 記錄錯(cuò)誤狀態(tài)
調(diào)試工作流
開發(fā)周期
- 初步開發(fā)
- 使用 Inspector 進(jìn)行基本測(cè)試
- 實(shí)現(xiàn)核心功能
- 添加日志記錄點(diǎn)
- 集成測(cè)試
- 在 Claude Desktop 中測(cè)試
- 監(jiān)控日志
- 檢查錯(cuò)誤處理
測(cè)試更改
要有效地測(cè)試更改，請(qǐng)執(zhí)行以下作：
- 配置更改：重新啟動(dòng) Claude Desktop
- 服務(wù)器代碼更改：使用 Command-R 重新加載
- 快速迭代：在開發(fā)過(guò)程中使用 Inspector
最佳實(shí)踐
日志記錄策略
- 結(jié)構(gòu)化日志記錄
- 使用一致的格式
- 包含上下文
- 添加時(shí)間戳
- 跟蹤請(qǐng)求 ID
- 錯(cuò)誤處理
- 日志堆棧跟蹤
- 包括錯(cuò)誤上下文
- 跟蹤錯(cuò)誤模式
- 監(jiān)視恢復(fù)
- 績(jī)效跟蹤
- 日志作計(jì)時(shí)
- 監(jiān)控資源使用情況
- 跟蹤?quán)]件大小
- 測(cè)量延遲
安全注意事項(xiàng)
調(diào)試時(shí)：
- 敏感數(shù)據(jù)
- 清理日志
- 保護(hù)憑據(jù)
- 屏蔽個(gè)人信息
- 存取控制
- 驗(yàn)證權(quán)限
- 檢查身份驗(yàn)證
- 監(jiān)控訪問(wèn)模式
獲取幫助
遇到問(wèn)題時(shí)：
- 第一步
- 檢查服務(wù)器日志
- 使用 Inspector 進(jìn)行測(cè)試
- 查看配置
- 驗(yàn)證環(huán)境
- 支持渠道
- GitHub 問(wèn)題
- GitHub 討論
- 提供信息
- 日志摘錄
- 配置文件
- 重現(xiàn)步驟
- 環(huán)境詳細(xì)信息
更多建議：