MCP Server 工程踩坑指南：这个 23 万星仓库把最佳实践都整理好了

如果你在搞 AI Agent 开发，大概率绕不开 MCP（Model Context Protocol）。这玩意儿让 AI 能调用工具、读资源、用 Prompt 模板——听起来简单，但真正动手写一个生产级的 MCP Server，才发现坑巨多：传输层选 stdio 还是 HTTP？工具注册 API 每次 SDK 版本都在变怎么办？Zod 验参怎么配才合理？

今天挖到一个宝藏 Skill——mcp-server-patterns，来自 GitHub 23.3 万星的 affaan-m/ECC 仓库，专门解决这些工程问题。

这 Skill 解决什么问题

它不是一个具体的 MCP Server 实现，而是一套经过社区验证的工程模式。当你需要：

• 从零实现一个新的 MCP Server
• 给现有 Server 加工具（tools）或资源（resources）
• 在 stdio 和 Streamable HTTP 之间做架构选择
• 调试 MCP 注册和传输层的问题

的时候，直接调这个 Skill，它会告诉你当前 SDK 版本的正确 API 签名、最佳实践、以及避坑指南。

几个核心设计模式

1. Transport 解耦
本地客户端（Claude Desktop）用 stdio，远程客户端（Cursor、云端）用 Streamable HTTP。代码层面把 Server 逻辑（工具+资源）和传输层完全分开，入口文件里按需插拔，干净利落。

2. Schema First
每个工具都要定义输入 schema，用 Zod 写清楚参数和返回值形状。工具描述里还要写清楚 rate limit 和 cost——这点很多教程都忽略，但生产环境必须考虑。

3. 错误要结构化
别直接抛异常让 AI 看到原始 stack trace，返回模型能理解的结构化错误信息，这样 Agent 才能正确做决策。

4. SDK 版本要 Pin 住
MCP SDK API 变化很快，Skill 里特别强调要在 package.json 里锁定 SDK 版本，升级前看 release notes——这个坑我踩过，升级一个大版本 API 全变了。

怎么用

ECC 仓库里有很多配套 Skill，这个是其中一个。安装方式：

npx skills add https://github.com/affaan-m/ECC --skill mcp-server-patterns

或者直接在 Claude Code 里触发这个 Skill，它会引导你一步步完成。

为什么值得收藏

MCP 现在的热度很高，但大多数资料只讲 hello world。这个 Skill 的价值在于——它把 23 万星社区在实际生产中踩出来的坑全部整理好了。不管你是第一次搭 MCP Server，还是在维护一个老项目，都值得过一遍这个 Skill 的逻辑。

作者是 affaan-m，仓库里还有 api-design、backend-patterns、frontend-patterns 等一系列工程实践 Skill，都是同一个风格——不是教你概念，是教你怎么做生产级代码。

GitHub：https://github.com/affaan-m/ECC

GitHub: https://github.com/affaan-m/ECC