SDK MCP 服务排障

MCP 排障先把服务器从 SDK 集成中分离测试。这样可以判断问题出在可执行文件、协议、工具定义，还是 SDK 会话配置。

第一层：进程能否启动

核对 command 的绝对路径、args、cwd、执行权限和依赖；使用与 SDK 相同的目录和参数独立运行。GUI 应用可能没有 shell PATH，所以本机终端能启动不证明宿主进程也能找到同一个命令。

Windows .NET 工具要区分直接运行 exe 和由 dotnet 执行 DLL；官方对 npx 给出 cmd /c npx 形式。Linux 用 ldd 检查真实二进制依赖，不把官方 libfoo 占位名当作应安装的包。

第二层：握手和消息格式

正常诊断顺序是 initialize、notifications/initialized，再 tools/list。检查 initialize 返回的协议版本、capabilities 与 serverInfo，然后检查工具名称和 inputSchema。

官方手动示例使用 protocolVersion 2024-11-05，这只是该示例值，不能据此宣称当前 SDK 永远协商这个 MCP 版本。工具列表查询应在已经初始化的同一个连接中进行；分别启动两个独立进程的单行管道不能证明完整会话握手正确。

stdio 服务器应把日志写 stderr，stdout 留给协议消息。检查 UTF-8、没有 BOM，以及每行一个完整 JSON 对象；不要让普通 console.log 的调试文本混入协议输出。

用 Inspector 检查工具

官方给出的交互诊断入口：

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Inspector 可发送测试请求、查看响应并检查工具 Schema。这个命令可能获取并执行工具包，按自己的开发环境依赖策略使用。

第三层：服务器有工具，会话却看不到

检查服务器是否实现 tools/list、是否正确处理 initialized 通知，以及会话 MCP 的 tools 列表是否为空。使用 tools: ["*"] 或明确工具名称，具体字段见SDK MCP。

还要检查 disabledMcpServers 是否精确命中了该服务器。服务器禁用、工具筛选与模型是否决定调用工具是不同环节。

第四层：工具可见但未调用或超时

把任务写成确实需要对应能力的请求，检查 description 是否具体、inputSchema 是否为有效 JSON Schema、必填字段是否列在 required。再核对权限请求，而非单凭模型未调用就调整网络配置。

timeout 的单位为毫秒。官方将 300000 作为慢服务的示例值，不是默认超时；增加它前先检查启动开销、阻塞 I/O 和服务本身的性能。长任务是否支持进度或流式响应取决于服务器，不是提高 timeout 自动获得的能力。

调试日志与复现材料

官方示例通过 env 传 MCP_DEBUG、DEBUG、NODE_DEBUG，但这些值如何生效取决于服务器实现，不应认定每个 MCP 服务器都有同一日志开关。记录原始通信时，日志可能包含全部工具输入输出，先明确保留范围并脱敏。

报告问题时提供 SDK/runtime 版本、服务器类型、去除密钥的配置、initialize 和 tools/list 结果，以及发生错误的具体阶段。涉及 runtime 本身时回到SDK 运行排障。