mcp-server

MCP 原因分析·规范验证

重现问题、对照最新规范与实现、整理不一致的依据、使用 Inspector 验证修改前后

---

输入要求（缺少时请询问）

首先确认以下 3 项

1. 工作目的：原因分析 或 规范验证
2. 目标代码／服务位置：repo path、package 名称、执行入口
3. 运行时／transport：Node(TypeScript) 或 Python，stdio 或 SSE/HTTP

仅在需要时追加确认以下项目

• 重现步骤：错误日志、失败请求／响应、预期行为
• 要检查的 Tool/Resource/Prompt 名称
• 部署环境／认证信息（仅限远程调用问题）

---

决策规则

1. 优先分析和验证，再考虑实现
2. 不在范围内新建服务／脚手架
3. 如需修改，基于现有代码进行最小改动
4. 分开记录已确认的事实与推测性假设

---

安全规则

STDIO 日志记录

• 使用 stdio transport 时，禁止向 stdout 输出日志
• Node 中使用 console.error() 替代 console.log()
• Python 中使用 logging 替代 print()

输入／调用验证

• 首先验证是否缺少必填输入
• 执行 Tool handler 前进行 schema 验证
• 对文件路径输入阻止路径遍历（../）
• 强制为外部 API 调用设置 timeout

---

执行步骤

Step 1. 重现问题

• 定义最小重现场景
• 将失败点归类为 transport、tools、resources 或 prompts
• 将重现结果区分为已确认事实和推测并记录

Step 2. 对照最新规范

1. 首先查看 MCP Specification
2. 对照 MCP SDKs 文档与正在使用的 SDK 版本
3. 将实现代码与规范逐项一一对应
   • transport 初始化／连接方式
   • tools/list、tools/call 请求／响应结构
   • resources/list、resources/read 的公开／读取结构
   • prompt 注册名称、argument schema、handler 路由
   • 响应格式 content、isError
4. 发现不一致时，同时整理影响范围与修改点

Step 3. 整理修改方案

• 按优先级整理各原因对应的修改顺序
• 说明每项修改的影响范围与回归风险
• 一并提供可测试的验证用例

Step 4. Inspector 验证

• 使用修改前后的相同场景比较结果
• 以检查清单记录通过／失败标准

---

Resources / Prompts 验证项

• 确认 resources/list 是否公开预期的资源
• 确认 resources/read 是否返回实际 payload
• 确认 prompt 注册名称是否冲突
• 确认 prompt argument schema 是否与调用 payload 一致
• 确认是否缺少 handler 或路由

---

Inspector 测试检查清单

• 是否满足服务运行并保持 Inspector 连接的标准
• tools/list 结果是否满足预期的 tool 公开标准
• 至少 1 个代表性 tool 的 tools/call 是否满足成功标准
• 响应是否满足 content／isError 结构标准
• 是否满足 stdout 无污染及协议保持标准
• 是否满足验证修改前后结果差异的标准

---

Error 返回标准

符合以下任一条件时，以 isError: true 返回

• 服务运行或连接本身失败
• 因缺少必填输入而无法进行验证
• 确认存在规范不一致
• 因重现失败而无法确定原因
• 因环境限制而无法执行 Inspector 测试

Error 响应至少包含以下项目

1. 失败阶段
2. 观察到的症状
3. 所需的补充输入或后续操作

---

输出约定（Output Contract）

始终按以下顺序整理结果

1. 问题摘要与重现条件
2. 已确认事实／推测性假设
3. 规范对照结果（一致／不一致）
4. 修改点与影响范围
5. Inspector 修改前后验证结果
6. 剩余风险与后续确认事项

---

Tool 返回格式

Success

{
  "content": [{ "type": "text", "text": "..." }]
}

Error

{
  "isError": true,
  "content": [{ "type": "text", "text": "..." }]
}