> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 调试
> 模型上下文协议 (MCP) 集成调试综合指南
在开发 MCP 服务器或将其与应用程序集成时，有效的调试至关重要。本指南涵盖了 MCP 生态系统中可用的调试工具和方法。
## 调试工具概述
MCP 提供了多种在不同层级进行调试的工具：
1. **[MCP 检查器](/docs/tools/inspector)**：交互式、与传输无关的测试 UI。连接到 stdio 或 Streamable HTTP 服务器，调用 [工具](/specification/latest/server/tools)、[提示词](/specification/latest/server/prompts) 和 [资源](/specification/latest/server/resources)，并观察通知流。这应该是你的首选工具。
2. **服务器日志**：结构化日志输出到 stderr（stdio 传输）或通过 [`notifications/message`](/specification/latest/server/utilities/logging#log-message-notifications)（所有传输）。
3. **客户端开发者工具**：大多数 MCP 客户端都会暴露日志和连接状态。参见下方的 [在 Claude Desktop 中调试](#debugging-in-claude-desktop) 作为一个示例，或查阅你的客户端文档。
## 实现日志记录
### 服务器端日志记录
当构建使用本地 [stdio 传输](/specification/latest/basic/transports#stdio) 的服务器时，所有记录到 stderr（标准错误）的消息将由宿主应用程序自动捕获。
本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议操作。
对于使用 [Streamable HTTP 传输](/specification/latest/basic/transports#streamable-http) 的服务器，客户端不会捕获 stderr。请使用下方的日志消息通知、你自己的服务器端日志聚合，或标准 HTTP 工具（curl、浏览器 DevTools Network 面板）来检查请求、[`Mcp-Session-Id` 头](/specification/latest/basic/transports#session-management) 和 SSE 流。
对于所有 [传输](/specification/latest/basic/transports)，你还可以通过发送日志消息通知向客户端提供日志记录：
```python Python theme={null}
@server.tool()
async def my_tool(ctx: Context) -> str:
await ctx.session.send_log_message(
level="info",
data="Server started successfully",
)
return "done"
```
```typescript TypeScript theme={null}
await server.sendLoggingMessage({
level: "info",
data: "Server started successfully",
});
```
MCP 定义了八个 [RFC 5424 严重性级别](/specification/latest/server/utilities/logging#log-levels)（`debug` 到 `emergency`）。客户端可以通过 [`logging/setLevel`](/specification/latest/server/utilities/logging#setting-log-level) 请求在运行时调整最低级别。
需要记录的重要事件：
* 初始化步骤
* 资源访问
* 工具执行
* 错误条件
* 性能指标
## 常见问题
下面的示例使用 Claude Desktop 的 [`claude_desktop_config.json`](/docs/develop/connect-local-servers)；同样的原则适用于任何基于 stdio 的 MCP 客户端。
### 工作目录
当 MCP 客户端启动 stdio 服务器时：
* 通过客户端配置启动的服务器的工作目录可能是未定义的（如 macOS 上的 `/`），因为客户端可以从任何地方启动
* 始终在配置和 `.env` 文件中使用绝对路径以确保可靠运行
* 对于通过命令行直接测试服务器，工作目录将是你运行命令的位置
例如在 `claude_desktop_config.json` 中，使用：
```json theme={null}
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/data"
]
}
}
}
```
而不是相对路径如 `./data`
### 环境变量
通过 stdio 启动的 MCP 服务器仅自动继承有限的环境变量子集（确切集合取决于平台）。
要覆盖默认变量或提供你自己的变量，你可以在 `claude_desktop_config.json` 中指定 `env` 键：
```json theme={null}
{
"mcpServers": {
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key"
}
}
}
}
```
### 服务器初始化
常见的初始化问题：
1. **路径问题**
* 服务器可执行文件路径不正确
* 缺少必需文件
* 权限问题
* 尝试对 `command` 使用绝对路径
2. **配置错误**
* 无效的 JSON 语法
* 缺少必需字段
* 类型不匹配
3. **环境问题**
* 缺少环境变量
* 变量值不正确
* 权限限制
### 连接问题
当服务器无法连接时：
1. 检查客户端日志
2. 验证服务器进程是否正在运行
3. 使用 [检查器](/docs/tools/inspector) 独立测试
4. 验证 [协议兼容性](/specification/latest/basic/lifecycle#version-negotiation)
5. 检查 [能力协商](/specification/latest/basic/lifecycle#capability-negotiation)：错误 [`-32602`](/specification/latest/basic/lifecycle#error-handling) 是标准的 JSON-RPC "无效参数" 代码，并在许多上下文中返回。一个常见的原因是服务器向未声明该能力的客户端发送 [采样](/specification/latest/client/sampling) 或 [征询](/specification/latest/client/elicitation) 请求。检查 [`initialize` 交换](/specification/latest/basic/lifecycle#initialization) 以验证双方都声明了你预期的内容
## 在 Claude Desktop 中调试
Claude Desktop 是众多 MCP 客户端之一。它可用于
macOS 和 Windows。
### 检查服务器状态
点击聊天输入框中的“添加文件、连接器等”加号图标，然后将鼠标悬停在 **Connectors** 菜单上以查看连接的服务器和可用工具。
### 查看日志
日志文件写入到：
* macOS: `~/Library/Logs/Claude`
* Windows: `%APPDATA%\Claude\logs`
```bash macOS theme={null}
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```
```powershell Windows theme={null}
type "$env:AppData\Claude\logs\mcp*.log"
```
日志捕获：
* 服务器连接事件
* 配置问题
* 运行时错误
* 消息交换
### 使用 Chrome DevTools
在 Claude Desktop 内部访问 Chrome 开发者工具以调查客户端错误：
1. 创建一个 `developer_settings.json` 文件，将 `allowDevTools` 设置为 true：
```bash macOS theme={null}
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```
```powershell Windows theme={null}
'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"
```
2. 打开 DevTools：`Command-Option-I` (macOS) 或 `Ctrl+Alt+I` (Windows)
注意：你将看到两个 DevTools 窗口：
* 主内容窗口
* 应用程序标题栏窗口
使用 Console 面板检查客户端错误。
使用 Network 面板检查：
* 消息负载
* 连接计时
## 调试工作流
### 开发周期
1. 初始开发
* 使用 [检查器](/docs/tools/inspector) 进行基本测试
* 实现核心功能
* 添加日志记录点
2. 集成测试
* 在你的目标 MCP 客户端中测试
* 监控日志
* 检查错误处理
### 测试更改
为了有效地测试更改：
* **配置更改**：重启 MCP 客户端
* **服务器代码更改**：重启客户端（对于 Claude Desktop，完全退出并重新打开；仅关闭窗口是不够的）
* **快速迭代**：在开发期间使用 [检查器](/docs/tools/inspector)
## 最佳实践
### 日志记录策略
1. **结构化日志记录**
* 使用一致的格式
* 包含上下文
* 添加时间戳
* 跟踪请求 ID
2. **错误处理**
* 记录堆栈跟踪
* 包含错误上下文
* 跟踪错误模式
* 监控恢复情况
3. **性能跟踪**
* 记录操作计时
* 监控资源使用情况
* 跟踪消息大小
* 测量延迟
### 安全注意事项
调试时：
1. **敏感数据**
* 清理日志
* 保护凭据
* 掩盖个人信息
2. **访问控制**
* 验证权限
* 检查身份验证
* 监控访问模式
有关 MCP 攻击向量和缓解措施的完整处理，请参阅 [安全最佳实践](/docs/tutorials/security/security_best_practices)。
## 获取帮助
遇到问题时：
1. **第一步**
* 检查服务器日志
* 使用 [检查器](/docs/tools/inspector) 测试
* 审查配置
* 验证环境
2. **支持渠道**
* [GitHub 问题](https://github.com/modelcontextprotocol/modelcontextprotocol/issues)
* [GitHub 讨论](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions)
3. **提供信息**
* 日志摘录
* 配置文件
* 复现步骤
* 环境详情
## 下一步
学习使用 MCP 检查器
逐步了解从头构建服务器
完整的 claude\_desktop\_config.json 参考和故障排除