SDK MCP 服务排障

按进程启动、协议握手、工具列表与执行四个阶段诊断 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 的调试文本混入协议输出。

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

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 运行排障。