agentmentoragentmentor

第 06 节:用 Inspector 调试到能交给 host

本节 objectives:

  • 能用 MCP Inspector 启动并测试本地 server。
  • 能检查 tools/resources/prompts 是否按预期暴露。
  • 能根据常见错误定位配置、schema、stdout、安全问题。

先修:已有一个可运行的 stdio server ｜ 上一节 << 05 ｜ 下一节:完成

先别急着塞进真正的 host

把 server 直接接进日常 host,失败时会很难分清:是 host 配置错、server 没启动、schema 错、还是 tool handler 抛错。

MCP Inspector 是官方的交互式测试和调试工具,用来在浏览器里连接 server、查看 tools/resources/prompts、调用工具、看错误输出。1 先用 Inspector 测通,再交给 Codex 或其他 host,调试面会小很多。

讲解

用 Inspector 测 stdio server 的基本形状:

bash
npx @modelcontextprotocol/inspector node /absolute/path/to/mcp-notes-lab/server.mjs

Inspector 会启动一个本地 UI 和一个 proxy。官方 GitHub README 提到默认客户端 UI 端口是 6274,proxy 端口是 6277。2 打开 UI 后,你通常要做三件事:

  1. 连接 server。
  2. 在 Tools/Resources/Prompts 标签里点 list。
  3. 调用一个低风险 tool,检查输入输出。

如果 list 都失败,先看启动配置和 stderr。如果 list 成功但调用失败,再看 schema、handler、权限和输入。

跟我做一遍(worked example)

先跑 Inspector:

bash
npx @modelcontextprotocol/inspector node /absolute/path/to/mcp-notes-lab/server.mjs

然后按顺序检查:

text
Tools:  - summarize_note 是否出现  - description 是否能让人知道它做什么  - input schema 是否要求 note
Resources:  - notes://policy 是否出现  - read resource 后 text 是否完整
Prompts:  - review_week 是否出现  - topic 参数是否需要填写

最后调用 summarize_note:

json
{  "note": "# MCP\n\nTools are actions. Resources are context."}

预期输出应该是一段 text content,而不是裸字符串、undefined 或异常栈。

换你补全(faded example)

下面是一次失败现象。请补全优先排查方向:

text
现象: Inspector 能启动,但连接 server 后 list tools 失败。server 代码里有 console.log("started")。
最可能原因: ______________________________修复方式: ________________________________

参考答案:

text
最可能原因: console.log 把普通文本写进 stdout,污染了 stdio JSON-RPC 协议流。修复方式: 删除 console.log,或改成 console.error/日志文件,让 stdout 只输出协议消息。

再看一个:

text
现象: list tools 成功,调用 delete_file 时模型传了 "../secrets.txt"。
最小修复: ________________________________

参考答案:

text
最小修复: 在 handler 里 resolve 路径并确认它仍位于允许目录内;拒绝 ..、编码后的 traversal 和逃出根目录的 symlink。

官方 SDK 文档也把 filesystem-backed resource 的路径清理列为安全要求:任何用户影响的 path 都要 resolve 后确认仍在预期 root 内。3

小结 + 通向下一节

一个 MCP server 到这里才算能交给 host:它能启动,能被 Inspector 发现,低风险 tool 能被调用,resource/prompt 能列出,安全边界写得清楚。

接下来你可以选一个真实小工作流继续做:项目 ADR reader、学习日志 server、issue 查询 server、内部文档 resource server。每次都从最小只读边界开始,再逐步加会改变状态的 tool。

Footnotes

  1. MCP Inspector Documentation — https://modelcontextprotocol.io/docs/tools/inspector ↩

  2. MCP Inspector GitHub Repository — https://github.com/modelcontextprotocol/inspector ↩

  3. MCP TypeScript SDK — https://github.com/modelcontextprotocol/typescript-sdk ↩

练习

Level 1: 用 Inspector 连接你的 notes server,分别截图或记录 Tools、Resources、Prompts 三个 list 结果。

自评