Agent Skills
返回列表
MCP 最佳实践决策参考

MCP 最佳实践决策参考

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_15292d5a/yjkj-mcp-best-practices。

技能介绍

解决什么问题

生产 MCP 服务器往往不是缺 demo，而是踩在 SDK 版本、传输会话、工具定义和客户端行为差异上。该技能把 TypeScript SDK 的当前稳定版与 v2 alpha、Streamable HTTP / stdio、Zod schema、tool annotations、错误处理与结果交付等细节整理成决策参考，帮助已有可运行服务器的工程师判断哪里该按规范写，哪里是客户端隐性行为。

核心能力与使用路径

  • 传输与会话：远端无状态优先使用 WebStandardStreamableHTTPServerTransport，并每请求创建 McpServer；长任务或需要状态时才启用 session。
  • 工具设计：优先 search_docs、github_* 这类可区分命名，每个 Zod 字段加 .describe()，并规避 z.union() 在部分已发布 v1 中生成空 schema 等已知坑。
  • 结果交付：明确 content 与 structuredContent 在 Claude Code、Codex CLI、VS Code Copilot、Goose 等客户端的 shadowing 行为；建议同一负载镜像，或每个工具只选一个通道。
  • 错误处理：输入校验、API 失败、业务错误应返回 isError: true 的 tool result，而不是 JSON-RPC protocol error，以便模型看到错误并自我纠正。
  • 性能控制：单个服务控制在 5-15 个工具，合并多步操作，返回精炼结果，避免大量工具定义占用上下文窗口。

适用边界

它不是入门教程，也不承诺所有客户端行为一致。资料中的跨客户端矩阵主要来自 issue tracker、maintainer 说明或实测，具体版本可能变化。使用它适合做上线前架构检查、重构决策和 code review 依据，不适合当作唯一 API 手册。

使用场景

  • 在 K8s 部署无状态远端 MCP 服务时，选择 Streamable HTTP 与 stdio 并决定是否生成 session。
  • 重构工具注册时，检查 Zod 字段是否补 `.describe()`，规避 `z.union()` 导致空 schema。
  • 调试工具返回时，确认 `content` 与 `structuredContent` 是否双发，避免 Claude Code 丢文本。
  • 上线前评估上下文占用，把 80 个工具拆成 5-15 个并合并多步查询。

适合人员

  • 负责 TypeScript MCP 服务上线的工程师，需要核对传输、session 和错误处理是否符合规范。
  • 做 Agent 工具链的架构师，需要审查工具命名、schema 和 annotations 是否可被客户端正确使用。
  • 维护 Hono、Cloudflare Workers 或 Express 集成的后端工程师，需要选择正确的 transport middleware。
  • 准备把 MCP 服务接入 Claude Code 的开发者，需要避免 content 与 structuredContent 被客户端 shadowing。