在构建 MCP 服务器或 MCP 工具时使用 —— 系统化的生产级 MCP 构建方法论，覆盖工具设计、错误处理、传输层选择与测试，让 AI 助手连接外部能力

MCP 服务器构建系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。 1. 协议核心概念 MCP 定义三种原语： Tools（工具）：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。 Resources（资源）：AI 助手只读访问的数据源，用 URI 标识。如 users://{id}/profile 。 Prompts（提示词模板）：预定义交互模板，引导用户触发工作流。选择原则：执行操作 → Tool 读取数据 → Resource 引导交互 → Prompt 2. 项目结构规范 TypeScript 关键依赖： @modelcontextprotocol/sdk + zod Python 关键依赖： mcp + pydantic 3. Tool 设计原则命名 snake case 格式，动词开头： search users 、 create issue 、 delete file 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用参数每个参数有类型约束和 .describe() 描述可选参数给默认值，减少 AI 决策负担用枚举代替布尔开关描述说明用途 + 返回内容 + 限制，这是 AI 选择工具的关键依据：输出结构化数据 → JSON，人类可读内容 → Markdown 始终用 content: [{ type: "text", text: "..." }] 格式返回 4. 输入验证和错误处理用 Zod/Pydantic 做 Schema 级校验，业务级校验放 handler 开头：错误处理四原则： 1. 永远不让服务器崩溃 — try/catch 包裹所有外部调用 2. 返回可操作的错误信息 — 告诉 AI 问题是什么、能做什么 3. 使用 isError: true — 让 AI 知道调用失败 4. 区分错误类型 — 参数错误、权限不足、资源不存在、服务不可用 5. 资源管理和生命周期关键点：使用连接池、所有外部调用设超时、优雅关闭清理资源。 6. 测试策略单元测试 — 业务逻辑与 MCP 注册分离集成测试 — 用 SDK Client 做端到端验证 MCP Inspector — 交互式调试在浏览器中查看所有 tools/resources，手动调用并查看结果。测试要点：每个 Tool 覆盖正常 + 异常路径、边界值、外部服务失败模拟。 7. 安全考虑权限控制：最小权限原则，读写 Tool 分离危险操作要求确认参数（如 confirm: true ）输入安全： SQL 注入 → 参数化查询，绝不拼接路径遍历 → 校验路径，禁止 ../ 命令注入 → 用 execFile 而非 exec 敏感数据：密钥通过环境变量传入，不硬编码日志不打印完整敏感信息返回数据做脱敏处理沙箱：文件操作限制目录、网络请求限制白名单、设置资源配额。 8. 部署和分发 npm 发布用户配置： pip 发布 Docker — 适用于复杂依赖或隔离场景 9. 调试技巧关键：MCP 用 stdio 通信，不能用 console.log ，会破坏协议流。常见问题：症状原因解决启动无响应 transport 未连接检查 server.connect() Tool 不出现注册在 connect 之后先注册再 connect AI 不调用 Tool 描述不清晰改善名称和描述参数总错 Schema 不明确添加 .describe() 调用超时外部服务慢加超时和缓存调试流程： Inspector 验证基本功能 → 手动调用确认输入输出 → 连接真实 AI 客户端观察调用模式 → 根据实际行为调整设计。 10. 构建检查清单设计 [ ] 明确 Tools vs Resources vs Prompts 分工 [ ] Tool 命名动词名词，描述说明用途和返回内容 [ ] 参数简洁，可选参数有合理默认值实现 [ ] 输入用 Zod/Pydantic 校验 [ ] 外部调用有 try/catch 和超时 [ ] 错误返回 isError: true 并附可操作信息 [ ] 不用 console.log （用 stderr 或 SDK 日志） [ ] 敏感数据走环境变量测试 [ ] 核心逻辑有单元测试 [ ] 有集成测试验证 MCP 协议交互 [ ] 用 MCP Inspector 手动验证过 [ ] 用真实 AI 客户端测试过部署 [ ] README 含安装和配置说明 [ ] 提供客户端配置 JSON 示例 [ ] 遵循 semver，无硬编码密钥

mcp-builder