用途
mcp-builder 是一套系统化设计、实现、测试和部署 Model Context Protocol（MCP）服务器的方法论，面向需要构建 MCP 服务器或 MCP 工具、让 AI 助手连接外部能力的场景。
协议核心概念
MCP 定义三种原语：
- Tools（工具）：AI 助手主动调用的函数，有副作用，如搜索、创建、删除操作。
- Resources（资源）：AI 助手只读访问的数据源，用 URI 标识，如 users://{id}/profile。
- Prompts（提示词模板）：预定义交互模板，引导用户触发工作流。
选择原则：执行操作 → Tool；读取数据 → Resource；引导交互 → Prompt。
项目结构规范
TypeScript 关键依赖：@modelcontextprotocol/sdk + zod。结构包含 src/index.ts（入口，注册 tools/resources）、src/tools/、src/resources/、src/lib/（客户端封装、校验逻辑）、tests/、package.json、tsconfig.json。
Python 关键依赖：mcp + pydantic。结构包含 src/my_mcp_server/server.py、src/my_mcp_server/tools/、src/my_mcp_server/lib/、tests/、pyproject.toml。
Tool 设计原则
命名：snake_case 格式，动词开头，如 search_users、create_issue、delete_file；名称需自解释，因为 AI 助手靠名称选工具，模糊命名会导致误调用。
参数：每个参数有类型约束和 .describe() 描述；可选参数给默认值以减少 AI 决策负担；用枚举代替布尔开关。示例中 search_issues 的 query 为字符串，status 为枚举 open/closed/all 且默认 open，limit 为 1-100 的数字且默认 20。
描述：说明用途 + 返回内容 + 限制，这是 AI 选择工具的关键依据。
输出：结构化数据用 JSON，人类可读内容用 Markdown；始终用 content: [{ type: "text", text: "..." }] 格式返回。
输入验证和错误处理
用 Zod/Pydantic 做 Schema 级校验，业务级校验放 handler 开头。错误处理四原则：
- 永远不让服务器崩溃 — try/catch 包裹所有外部调用。
- 返回可操作的错误信息 — 告诉 AI 问题是什么、能做什么。
- 使用 isError: true — 让 AI 知道调用失败。
- 区分错误类型 — 参数错误、权限不足、资源不存在、服务不可用。
资源管理和生命周期
资源通过 server.resource 注册，返回 contents 数组并指定 mimeType。生命周期顺序：先初始化 → 再 connect → 监听关闭信号。关键点包括使用连接池、所有外部调用设超时、优雅关闭清理资源。
测试策略
- 单元测试：业务逻辑与 MCP 注册分离，tools/search.ts 导出纯函数独立测试。
- 集成测试：用 SDK Client 做端到端验证，通过 InMemoryTransport.createLinkedPair() 连接并调用 callTool。
- MCP Inspector：交互式调试，命令为 npx @modelcontextprotocol/inspector node dist/index.js，可在浏览器中查看所有 tools/resources、手动调用并查看结果。
测试要点：每个 Tool 覆盖正常 + 异常路径、边界值、外部服务失败模拟。
安全考虑
权限控制：最小权限原则，读写 Tool 分离；危险操作要求确认参数（如 confirm: true）。
输入安全：SQL 注入用参数化查询，绝不拼接；路径遍历校验路径，禁止 ../；命令注入用 execFile 而非 exec。
敏感数据：密钥通过环境变量传入，不硬编码；日志不打印完整敏感信息；返回数据做脱敏处理。
沙箱：文件操作限制目录、网络请求限制白名单、设置资源配额。
部署和分发
- npm 发布：配置 bin 与 files 字段，用户通过 mcpServers 配置 JSON 指定 command、args 和 env（API_KEY）。
- pip 发布：在 [project.scripts] 中声明入口，如 mcp-server-myservice = "my_mcp_server.server:main"。
- Docker：适用于复杂依赖或隔离场景，基于 node:20-slim 构建。
调试技巧
MCP 用 stdio 通信，不能用 console.log，会破坏协议流。正确做法是用 console.error("[DEBUG]", info) 或 server.sendLoggingMessage({ level: "info", data: "处理中" })。
常见问题对照：启动无响应多为 transport 未连接；Tool 不出现多为注册在 connect 之后；AI 不调用 Tool 多为描述不清晰；参数总错多为 Schema 不明确；调用超时多为外部服务慢，需加超时和缓存。
调试流程：Inspector 验证基本功能 → 手动调用确认输入输出 → 连接真实 AI 客户端观察调用模式 → 根据实际行为调整设计。
构建检查清单
设计：明确 Tools vs Resources vs Prompts 分工；Tool 命名 动词_名词，描述说明用途和返回内容；参数简洁，可选参数有合理默认值。
实现：输入用 Zod/Pydantic 校验；外部调用有 try/catch 和超时；错误返回 isError: true 并附可操作信息；不用 console.log（用 stderr 或 SDK 日志）；敏感数据走环境变量。
测试：核心逻辑有单元测试；有集成测试验证 MCP 协议交互；用 MCP Inspector 手动验证过；用真实 AI 客户端测试过。
部署：README 含安装和配置说明；提供客户端配置 JSON 示例；遵循 semver，无硬编码密钥。
限制
资料未说明该技能的具体价格、授权方式、支持平台或性能指标，暂未提供。