skill-mcp-patterns

生产级 MCP 服务器模式与最佳实践 — 从协议设计到生产部署全流程覆盖。包含 Zod 模式、工具注解、输出模式、并行处理、多层缓存、重试逻辑、速率限制、RFC 7807 错误设计、STDIO/Streamable HTTP/Edge 部署、OAuth 2.1，以及完整的生产就绪清单，共 13 个自包含模块。

English Documentation

概述

本技能提供了一套全面的 MCP 服务器开发框架，涵盖从协议基础到生产部署的各个方面。它被设计为智能体可消费的技能，通过索引模块化的文档供 Claude Code（或任何 AI 智能体）引用。

快速开始

# 克隆仓库
git clone <repo-url>
cd skill-mcp-patterns

# 安装依赖（本地运行测试需要）
npm install

# 与 Claude Code 一起使用
# Claude 会自动读取 SKILL.md 来发现模块索引

当你需要 MCP 优化帮助时，Claude 将：

1. 读取 SKILL.md（模块索引/路由器）
2. 根据你的请求动态加载相关模块
3. 将指导应用于你的具体代码

模块结构

skill-mcp-patterns/
├── SKILL.md                        # 模块索引 / 路由器
├── CLAUDE.md                       # 项目级指导
├── README.md                       # 英文文档
├── README.zh.md                    # 本文档（中文）
├── package.json                    # npm 包配置
├── vitest.config.ts                # 测试运行器配置
├── .nvmrc                          # Node.js 版本要求
├── .github/workflows/              # CI 流水线
│   └── ci.yml
├── src/                            # 示例代码
│   └── __tests__/
│       └── mcp-patterns.test.ts
├── modules/                        # 核心技能内容
│   ├── 01-protocol-fundamentals.md
│   ├── 02-data-accuracy.md
│   ├── 03-performance.md
│   ├── 04-coverage.md
│   ├── 05-reliability.md
│   ├── 06-automation.md
│   ├── 07-documentation.md
│   ├── 08-architecture.md
│   ├── 09-anti-patterns.md
│   ├── 10-frameworks.md
│   ├── 11-testing.md
│   ├── 12-deployment.md
│   └── 13-checklists.md
└── scripts/                        # 自动化脚本
    ├── _config.sh
    ├── bump-version.sh
    └── publish.sh

模块一览

| # | 模块 | 涵盖内容 | |---|------|---------| | 01 | 协议基础 | 服务器组件、Zod 模式、工具注解（readOnlyHint/destructiveHint）、输出模式（structuredContent）、弃用说明、MCP Inspector 开发工作流 | | 02 | 数据准确性 | 真实数据源替换、混合架构与多层缓存、数据完整性验证 | | 03 | 性能优化 | 瓶颈分析、并行处理与批处理、智能缓存 TTL 策略、实际基准测试 | | 04 | 覆盖范围 | 数据集扩展与覆盖阈值、基于关键字的智能分类、测试覆盖验证 | | 05 | 可靠性 | 指数退避重试、速率限制与批处理延迟、标准化错误响应（RFC 7807）、优雅降级、安全验证 | | 06 | 自动化 | 后台定时刷新与预热、基于保留期的数据清理、服务器主动通知 | | 07 | 文档 | 发布清单、语义化版本管理、迁移指南、npm 发布步骤 | | 08 | 架构 | 分层设计、中间件链、注册表模式、资源 URI 设计、可观测性（日志/指标/健康检查）、12-Factor 配置、工具组合、游标分页、推荐项目结构 | | 09 | 反模式 | 16 个常见陷阱（过度缓存、无速率限制、串行处理、硬编码数据、原始 API 转储等） | | 10 | 框架 | API 网关/插件系统/GraphQL/微服务/ETL/RPC 的设计模式借鉴、五个 MCP 框架对比（SDK vs fastmcp vs mcp-framework vs mcp-ts-core vs zero-mcp） | | 11 | 测试 | 测试金字塔（构建/模式/协议/功能/负载/集成/模糊测试）、Inspector CLI 在 CI 中使用、模糊测试示例代码 | | 12 | 部署 | 传输选择（STDIO/SSE/HTTP/Edge）、Streamable HTTP、OAuth 2.1/PKCE、Docker、服务端部署 | | 13 | 清单 | 成功指标（性能/可靠性/数据质量）、常见问题排障、6 阶段优化完成清单、发布决策 |

使用手册

本技能提供 12 项核心功能，覆盖 MCP 服务器开发的全生命周期。在 Claude Code 中使用下方提示语示例来调用各项功能。

功能一览表

| # | 功能 | 说明 | 示例提示语 | |---|------|------|-----------| | 01 | 协议设计 | 设计 MCP 服务器结构、工具、资源、提示词、Zod 模式、注解和输出模式 | • "Help me design the tool and resource architecture for my MCP server"• "为我搜索工具添加 Zod schema 和 tool annotations"• "Design a server-level instructions block for my npm advisor server"• "Check if my server uses any deprecated MCP features"• "设置 outputSchema 和 structuredContent 的正确方式是什么" | | 02 | 数据准确性审计 | 查找替换硬编码/估算数据、接入真实 API 源、设置多层缓存 | • "帮我排查 MCP 服务器中的数据准确性问题和硬编码值"• "Find estimated values in my trending tool and replace them with real API data"• "Add data integrity checks after fetching from upstream"• "Design a hybrid architecture with multi-layer caching for my server"• "为不同类型的数据设置不同的缓存 TTL" | | 03 | 性能调优 | 瓶颈分析、并行处理、缓存策略、批处理+延迟模式 | • "我的 MCP 服务器很慢，帮我做性能分析和优化"• "Convert my serial API calls to parallel processing with batch limits"• "为排行榜数据和详情数据设置不同的智能缓存 TTL"• "Add batch+delay pattern to protect upstream API rate limits"• "Help me benchmark before and after optimization" | | 04 | 覆盖范围扩展 | 扩展数据集、定义覆盖阈值、实现基于关键字的智能分类 | • "帮我扩展 MCP 服务器的数据覆盖范围和分类体系"• "Expand my dataset from 15 packages to 100+ with proper categorization"• "Add coverage validation that checks minimum items per category"• "Implement an auto-categorization function using keyword rules"• "验证边界情况：缺失数据、已弃用项目、空结果处理" | | 05 | 可靠性工程 | 重试逻辑、速率限制、标准化错误响应、优雅降级、安全验证 | • "帮我的 MCP 服务器增加重试机制和错误处理"• "Add exponential backoff retry logic to my API calls"• "用 McpError 和 formatError 设计标准化错误响应"• "Implement graceful degradation when upstream APIs are down"• "为工具处理器添加输入验证和安全检查" | | 06 | 后台自动化 | 定时刷新+预热、基于保留策略的数据清理、服务端主动通知 | • "帮我的 MCP 服务器添加后台数据自动刷新机制"• "Add setInterval auto-refresh with startup prewarming"• "根据数据类型设置保留规则的数据清理"• "Implement server notifications on data changes"• "创建维护工作流：刷新→检测变更→清理→通知" | | 07 | 架构审查 | 分层架构、中间件链、注册表模式、游标分页 | • "帮我审查 MCP 服务器的架构设计是否合理"• "重构工具处理器使其符合分层架构设计"• "为日志、缓存、认证添加中间件链"• "为大结果集实现基于游标的分页"• "Review my project structure against recommended patterns" | | 08 | 反模式检测 | 扫描代码库中 16 种常见 MCP 陷井：过度缓存、原始 API 转储、1:1 API 映射等 | • "帮我审查 MCP 代码是否存在常见的反模式"• "Check my server against the 16 common MCP anti-patterns"• "Find places where I'm doing raw API dumps or 1:1 endpoint mapping"• "Review if my tool names and server instructions follow best practices"• "识别过度优化或缺少上下文最小化的地方" | | 09 | 框架选型 | 对比并选择合适框架：Official SDK、fastmcp、mcp-framework、mcp-ts-core、zero-mcp | • "帮我选择适合我的场景的 MCP 框架"• "Compare fastmcp vs official SDK for my use case"• "Which MCP framework is best for an agent-built production server?"• "我需要 OAuth 和快速搭建——该选哪个框架"• "Evaluate mcp-framework scaffolding vs mcp-ts-core contract-first approach" | | 10 | 测试与验证 | 搭建测试金字塔、在 CI 中集成 MCP Inspector、编写模糊测试 | • "帮我的 MCP 服务器搭建完整的测试体系"• "Set up the MCP test pyramid: build, schema, protocol, functional, load, integration"• "在 CI 流水线中添加 MCP Inspector CLI 命令"• "Write fuzz tests to verify adversarial input safety"• "Create a pre-release validation script: build + test + Inspector + fuzz" | | 11 | 部署规划 | 传输选型（STDIO/SSE/HTTP/Edge）、OAuth 配置、Docker 化、边缘部署 | • "帮我的 MCP 服务器设计部署方案"• "Should I use STDIO, SSE, or Streamable HTTP for my server?"• "Set up OAuth 2.1/PKCE authentication for my remote MCP server"• "创建 Dockerfile 和生产部署配置"• "将 MCP 服务器部署到 Cloudflare Workers" | | 12 | 生产就绪 | 完整清单验证：指标、故障排查、安全、可观测性、发布决策 | • "帮我对 MCP 服务器做上线前的最终检查"• "Run the full production readiness checklist against my server"• "检查成功指标：p90 延迟、错误率、缓存命中率"• "排查服务器频繁触发速率限制的原因"• "验证所有可观测性：结构化日志、指标、健康检查端点" |

使用方式

1. 在 Claude Code 中打开你的 MCP 服务器项目
2. 确保本技能可被项目上下文访问
3. 从上表中选择一条示例提示语对 Claude 说出
4. Claude 将读取相关模块并将指导应用到你的代码

多阶段优化推荐顺序：

数据准确性 → 性能优化 → 覆盖扩展 → 可靠性增强 → 后台自动化 → 文档发布

贡献指南

1. 在 modules/ 中创建或更新模块
2. 如果添加新模块，更新 SKILL.md 中的模块索引
3. 运行 npm test 验证示例代码仍然通过
4. 运行 bash scripts/bump-version.sh [patch|minor|major] 升级版本号
5. 运行 bash scripts/publish.sh "变更描述" 提交并发布

相关链接

• MCP 规范
• MCP Inspector
• Claude Code Skills