Everything Claude Code 的 MCP Server Patterns Skill 是构建和维护 MCP（Model Context Protocol）服务器的权威操作指南，适用于 Node.js/TypeScript 技术栈。它帮助开发者用标准 SDK 快速注册 Tool、Resource、Prompt，灵活切换本地 stdio 或远程 HTTP 传输，并用 Zod 实现参数校验。无论是初次搭建 MCP 服务端，还是升级、扩展、排查注册与通信问题，都能通过本 Skill 快速定位最佳实践和常见坑。

Everything Claude Code MCP Server Patterns Skill：Node.js/TypeScript SDK 构建 MCP 服务器与 Zod 验证

在 AI 编程助手（如 Claude Code、Cursor、Codex）生态中，MCP（Model Context Protocol）已成为模型与外部工具、资源交互的事实标准。Everything Claude Code 的 MCP Server Patterns Skill，正是针对 Node.js/TypeScript 开发者打造的生产级 MCP 服务器开发指南。本文将详细讲解该 Skill 能解决哪些实际问题、何时触发、如何分步落地，以及与其他 Agent/Skill 的协作关系，帮助你高效构建和维护 MCP 服务器。

如果你刚接触 Claude Code 插件体系，建议先阅读 Claude Code 快速上手指南：Skills、Hooks、Subagents、MCP 实战配置 了解整体架构。

---

1. 这个 Skill 解决什么问题？

MCP Server Patterns Skill 专为以下场景设计：

• 新建 MCP 服务器：快速搭建支持 Tool/Resource/Prompt 的 AI 工具服务端。
• 扩展/维护现有服务：无缝添加新工具、资源或 Prompt，安全升级 SDK。
• 传输方式决策：本地（stdio）与远程（Streamable HTTP）一键切换，适配 Claude Desktop、Cursor、云端等多种客户端。
• 输入验证与健壮性：用 Zod 定义参数 schema，防止模型调用时参数出错。
• 排查注册/通信问题：对比官方文档和 Context7，规避 SDK 版本差异导致的注册、传输 bug。
• 最佳实践沉淀：统一工具注册、错误处理、幂等性、速率/成本说明等模式，提升代码可维护性。

对比传统做法：未用本 Skill 前，开发者常因 SDK 版本变动、注册 API 差异、传输方式混淆、参数校验缺失等问题踩坑，导致模型调用失败、调试困难、升级阻力大。本 Skill 将这些痛点全部标准化为可复用的模式。

---

2. 何时触发/激活 MCP Server Patterns Skill？

• 实现新 MCP 服务器：项目需要为 Claude Code、Cursor 等 AI 助手提供自定义工具/资源时。
• 添加/修改 Tool、Resource、Prompt：需要注册新功能或调整参数 schema 时。
• 升级 @modelcontextprotocol/sdk 版本：SDK API 发生变动，需查新注册/传输模式时。
• 排查注册与通信异常：遇到工具无法调用、资源无法读取、模型报错等注册/传输相关问题时。
• 切换本地/远程部署模式：决定用 stdio（本地）还是 HTTP（远程）传输，或兼容老旧 HTTP/SSE 客户端时。

Skill 会在上述场景下自动被 Claude Code Agent 检测并推荐，也可手动指定调用。

---

3. 分步骤落地指南（Step by Step）

步骤 1：安装依赖

npm install @modelcontextprotocol/sdk zod

• @modelcontextprotocol/sdk：官方 MCP JS/TS SDK
• zod：参数 schema 校验库

步骤 2：初始化 MCP 服务器

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

不同 SDK 版本的 API 可能有细微区别，建议用 Context7 查询最新注册方法。

步骤 3：注册 Tool（工具）

推荐模式：schema first + handler 解耦

server.tool(
  "search",
  "在指定文档中搜索关键词",
  z.object({
    query: z.string().describe("搜索关键词"),
    docId: z.string().optional().describe("文档ID")
  }),
  async ({ query, docId }) => {
    // 实现搜索逻辑
    return { result: "搜索结果" };
  }
);

• 也可用对象参数模式（部分 SDK 版本）：

  server.tool({
    name: "search",
    description: "在指定文档中搜索关键词",
    inputSchema: z.object({ ... })
  }, handler)

• 注意：handler 返回结构化对象，避免抛出原生错误。

步骤 4：注册 Resource（资源）

server.resource(
  "getFile",
  "读取指定文件内容",
  z.object({
    uri: z.string().describe("文件路径 URI")
  }),
  async ({ uri }) => {
    // 读取文件逻辑
    return { content: "文件内容" };
  }
);

• Resource handler 通常接收 uri 参数，返回只读数据。

步骤 5：注册 Prompt（参数化提示模板）

server.registerPrompt(
  "summaryPrompt",
  "生成摘要的提示模板",
  z.object({
    topic: z.string().describe("摘要主题")
  }),
  ({ topic }) => `请为主题“${topic}”生成一段简明摘要。`
);

某些 SDK 版本可能用 prompt() 或其他注册方法，具体以官方文档和 Context7 为准。

步骤 6：选择传输方式（stdio vs HTTP）

• 本地（Claude Desktop 等）：使用 stdio 传输

  import { createStdioTransport } from "@modelcontextprotocol/sdk/transport/stdio";
  server.connect(createStdioTransport());

• 远程（Cursor、云端）：使用 Streamable HTTP

  import { createHttpTransport } from "@modelcontextprotocol/sdk/transport/http";
  server.connect(createHttpTransport({ port: 8080 }));

• 兼容老客户端：如需支持 SSE/旧 HTTP，查阅官方文档，优先推荐 Streamable HTTP。

步骤 7：测试与调试

• 用 MCP 客户端（如 Claude Code、Cursor）连接服务器，验证工具/资源/Prompt 能被正确发现和调用。
• 遇到注册/通信问题，优先用 Context7 查“当前 MCP 注册/传输模式”。

---

4. 输出示例

注册 Tool 后，模型可自动发现并调用：

{
  "tool": "search",
  "description": "在指定文档中搜索关键词",
  "parameters": {
    "query": "Claude Code",
    "docId": "doc-123"
  },
  "result": {
    "result": "搜索结果"
  }
}

注册 Resource 后，模型可读取指定资源：

{
  "resource": "getFile",
  "parameters": {
    "uri": "/tmp/readme.md"
  },
  "result": {
    "content": "# 项目说明 ..."
  }
}

Prompt 可被客户端（如 Claude Desktop）动态渲染参数化输入界面。

---

5. 常见配套 Agent/Skill 与协作关系

• 与 Agent 协作：如 Build Error Resolver、Code Reviewer 等 Agent 可通过 MCP Server Patterns Skill 自动注册和暴露自定义工具，提升 AI 代码修复/审查能力。
• 与其他 Skill 协作：可与 Backend Patterns Skill、API Design Skill 等结合，统一后端架构和接口风格。
• 与 Hooks/Rules 配合：结合 Everything Claude Code Hooks 实战 可实现注册前后自动校验、日志等自动化。

---

6. 最佳实践与注意事项

• Schema first：所有 Tool/Resource 必须用 Zod 明确参数和返回类型，便于模型安全调用。
• 错误处理：handler 只返回结构化错误信息，避免泄露堆栈。
• 幂等性：设计 Tool 时优先保证幂等，便于模型重试。
• 速率/成本说明：如工具涉及外部 API，需在 description 中注明限制和费用。
• SDK 版本管理：固定 SDK 版本，升级时查 release notes，避免注册/传输 API 差异导致兼容性问题。
• 官方文档/Context7 查询：遇到注册、传输方式、API 签名变动，优先查 Context7 或 MCP 官方文档。

---

FAQ

Q: MCP Server Patterns Skill 适用于哪些 AI 编程助手？ A: 主要适用于 Claude Code、Cursor、Codex 等支持 MCP 协议的 AI 编程助手，兼容本地和云端多种部署模式。

Q: SDK API 经常变动，如何避免踩坑？ A: 固定依赖版本，注册 Tool/Resource/Prompt 时优先查官方 MCP 文档或 Context7，避免复制旧代码导致注册失败。

Q: Zod 校验和模型调用的关系是什么？ A: Zod schema 可确保模型调用工具/资源时参数类型和格式正确，降低运行时错误率，提升 AI 调用体验。

---