写 MCP 服务器必看：这份 Skill 把生产级坑全避了

如果你在用 TypeScript 构建 MCP 服务器，这篇文章你一定要看完。

最近 MCP（Model Context Protocol）的热度不用我多说了吧？Claude Desktop、Cursor、Windsurf 都在抢着接 MCP，整个生态在 2026 年彻底爆发。但问题是——用 TS SDK 写出一个能跑的 MCP 服务器很容易，写出一个生产级的、真正靠谱的服务器，难。

我最近挖到一个宝藏 Skill——mcp-best-practices，来自 tenequm/skills 这个仓库，专门解决这个痛点。它不是教程，而是一份生产级 MCP 服务器的决策参考，假设你已经有了一个能跑的服务，需要把它做对、做快、做安全。

这玩意儿解决什么问题？

MCP 社区这两年最大的变化就是 SDK 的两个时代切换——2025 年的 legacy 协议和 2026-07-28 的新 spec。这份 Skill 把这俩时代的差异讲得明明白白：

• 升级到 SDK v2 不等于升级到新协议——很多人踩过这个坑
• stateless vs stateful 远程服务器的传输层选择
• sessionIdGenerator 怎么配，什么时候该用，什么时候必须为空
• 工具命名规范（别用 `search` 这种通用名，会跟其他服务器冲突）

对于正在做 MCP 基础设施的团队来说，这些细节直接决定了服务器能不能上生产、能不能 scale。

几个特别值的点

1. 传输层决策树 — 远程无状态（K8s/Cloudflare Workers）用 `WebStandardStreamableHTTPServerTransport` 配 `sessionIdGenerator: undefined`，有状态长任务才用 `randomUUID()` 生成 session。这个坑很多人在生产环境才踩到。

2. Token 膨胀治理 — MCP 里有个很讨厌的问题：工具结果太大导致 token 爆炸。这份 Skill 里有具体的防御策略，比如配置 `MAX_MCP_OUTPUT_TOKENS` 和 `result-size` 预算。

3. SDK 迁移指南 — v1 到 v2 的 `registerTool()` API 变化、import 路径迁移、废弃的 positional overloads，全都整理好了，不用在 GitHub issues 里翻半天。

4. 工具输出设计 — `structuredContent` 和 `text` 两个 channel 必须传完全相同的 payload，否则在 Claude Code/Codex/Copilot 里 text 会静默消失。这个细节文档几乎没提，但 Skill 里写得清清楚楚。

适合谁用？

已经在用 `@modelcontextprotocol/sdk` 或 `@modelcontextprotocol/server` v2 的开发者，需要写生产级 MCP 服务器的 AI 工程团队，以及想把现有 MCP 服务做安全加固的同学。

如果你刚接触 MCP，这个 Skill 不适合你——它不是入门教程，是给有基础的人查漏补缺的。

怎么装？

一行命令搞定：

npx skills add https://github.com/tenequm/skills --skill mcp-best-practices

装完在 Claude Code 或 Codex 里直接激活，相关的传输配置、工具设计、安全建议就会自动出现在上下文里。

在 AI Agent 大爆发的时间点，MCP 基础设施的质量直接决定 Agent 的能力边界。这个 Skill 把社区踩过的坑系统化整理了一遍，非常适合收藏备用。

GitHub：tenequm/skills – mcp-best-practices

GitHub: https://github.com/tenequm/skills/tree/main/skills/mcp-best-practices