使用 MCP 检查器

开发 MCP 服务器需要处理不可见的数据流。您的 Python 或 TypeScript 代码通过标准输入输出 (stdio) 进行通信，交换 JSON-RPC 消息，这些消息在没有拦截的情况下很难追踪。在尝试将服务器连接到像 Claude Desktop 这样的 LLM 客户端之前，您必须验证您的实现是否遵循协议并按预期运行。MCP 检查器就是这个验证层。

MCP 检查器是一个以网页界面形式运行的开发工具。它充当一个代理客户端，连接到您的服务器，允许您浏览资源、执行工具和手动调整提示。这种隔离消除了 LLM 的不确定性。如果在检查器内部工具执行失败，问题就出在您的代码中。如果它在检查器中成功但在 LLM 中失败，问题很可能出在工具描述或模式清晰度上。

安装和运行检查器

检查器以 Node.js 包的形式分发。您无需全局安装它；最好使用 npx 来执行，以确保您使用的是调试协议的最新版本。该命令结构要求您将通常用于运行服务器的命令作为参数传递给检查器。

对于使用 uv 的 Python 服务器，命令遵循以下模式：

npx @modelcontextprotocol/inspector uv run server.py

对于直接构建或运行的 TypeScript 服务器：

npx @modelcontextprotocol/inspector node build/index.js

执行后，检查器将您的服务器作为子进程启动。它附加到服务器的 stdin 和 stdout 流，充当传输层。同时，它会启动一个本地 Web 服务器（通常在 localhost:5173 上），您可以在其中与用户界面进行交互。

调试会话的架构，显示了用户界面、检查器代理和目标服务器之间的分离。

验证资源

网页界面加载后，检查器会启动 initialize 握手。如果成功，"资源" 选项卡将填充您的服务器暴露的数据端点列表。此视图验证了您的实现的两个重要方面。首先，它确认 resources/list 处理程序返回了正确的元数据结构。其次，它允许您测试内容获取逻辑。

点击特定资源会发送带有特定 URI 的 resources/read 请求。检查器会在主视图中渲染返回的内容（文本或二进制）。这对于调试动态资源特别有用。例如，如果您的资源 URI 包含 file:///logs/{date} 这样的参数，检查器允许您验证您的模式匹配逻辑是否正确路由请求并提取变量。

测试工具执行

工具通常包含 MCP 服务器中最复杂的逻辑。检查器会为您的模式中定义的每个工具生成一个动态表单。此表单严格源自您在代码中提供的 inputSchema JSON 模式。

如果表单中缺少必填字段，或者某个字段本应是整数却允许字符串，这表明您的 Pydantic 模型或 Zod 定义存在错误。您可以将测试值输入这些表单并执行工具。检查器会发送 tools/call 请求并显示结果。

这种手动执行是必要的，用于捕获不会触发异常的逻辑错误。例如，一个数据库查询工具可能在技术上成功（返回 200 OK 状态），但由于 SQL 语句格式错误而返回空列表。通过检查检查器中的原始 JSON 输出，您可以区分“未找到数据”的场景和静默失败。

服务器调试会话期间观察到的典型请求类型分类。

追踪 JSON-RPC 消息

检查器最强大的功能是连接日志。该日志位于底部面板或专用选项卡中，记录了检查器与您的服务器之间交换的每个 JSON-RPC 消息。

调试时，您会在日志流中寻找三个特定组件：

1. 请求结构： 验证方法名称（例如 tools/call）和 params 对象。确保参数正确嵌套。
2. 响应匹配： 每个请求都带有一个唯一的 id（整数或字符串）。服务器的响应必须带有相同的 id。如果 ID 不匹配，客户端将丢弃该响应。
3. 错误传播： 如果您的服务器崩溃或抛出未处理的异常，检查器应接收一个标准的 JSON-RPC 错误对象。

请看标准错误格式：

$$Error_{response} = \{ "code": \text{整数}, "message": \text{字符串}, "data": \text{可选} \}$$

如果您的服务器直接将 Python 堆栈跟踪打印到 stdout，它会违反 JSON 结构，检查器将报告解析错误。日志允许您精准定位服务器输出偏离 JSON 规范的位置。

处理标准输入输出噪音

集成过程中一个常见问题是“标准输入输出噪音”。当您的服务器代码或依赖项将调试信息（例如 print("Connecting to DB...")）打印到标准输出时，就会发生这种情况。由于 MCP 使用标准输出进行协议通信，这些纯文本字符串会破坏 JSON 流。

检查器分离了 stdout（协议）和 stderr（日志）。要修复检查器中出现的解析错误，请确保您的所有应用程序日志都导向 stderr。在 Python 中，使用配置为写入 sys.stderr 的 logging 模块。在 Node.js 中，使用 console.error() 用于日志，并将 console.log() 严格保留给 MCP 消息，如果您正在手动管理传输（尽管推荐使用 SDK 抽象）。

管理环境变量

检查器在其自己的进程环境中运行。除非特定环境变量（如 API 密钥）存在于您当前的 shell 会话中，否则它不会自动继承。如果您的服务器在检查器下运行时无法与外部服务认证，检查环境配置是第一步。

您可以在启动检查器时内联传递环境变量：

# Linux/macOS
OPENAI_API_KEY=sk-... npx @modelcontextprotocol/inspector uv run server.py

# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."; npx @modelcontextprotocol/inspector uv run server.py

通过使用检查器系统地验证资源、工具和消息完整性，您可以确保服务器足够强大，可以应对后续集成阶段中 LLM 驱动交互的不可预测性。