mcp-server-patterns

MCP Server 模式与实践

Model Context Protocol (MCP) 允许 AI 助手调用你服务器上的 Tool（工具）、读取 Resource（资源）以及使用 Prompt（提示词模板）。在开发或维护 MCP 服务端时可以使用本 Skill。由于 SDK 接口一直在迭代更新，最新的方法名称与函数签名请查阅 Context7（搜索“MCP”）或参考 MCP 官方文档。

关于何时该将某项能力设计为 Rule、Skill、MCP 还是普通 CLI/API 工作流的框架选型指南，详见 docs/capability-surface-selection.md。

适用场景

当遇到以下情况时使用：实现全新的 MCP 服务器、添加 Tool 或 Resource、选择 stdio 或 HTTP 传输层、升级 SDK，或者排查 MCP 注册与传输链路相关的 bug。

工作原理

核心概念

• Tools（工具）：模型可以执行的具体操作（如搜索、运行命令等）。根据 SDK 版本不同，可使用 registerTool() 或 tool() 进行注册。
• Resources（资源）：模型可以读取的只读数据（如文件内容、API 返回体等）。使用 registerResource() 或 resource() 进行注册，处理函数通常会接收到 uri 参数。
• Prompts（提示词）：客户端（如 Claude Desktop）可以调出的可复用参数化提示词模板。使用 registerPrompt() 或类似方法注册。
• Transport（传输协议）：本地客户端（如 Claude Desktop）推荐使用 stdio；远程客户端（如 Cursor、云端环境）首选 Streamable HTTP；传统的 HTTP/SSE 仅用于向下兼容。

Node/TypeScript SDK 可能会暴露 tool() / resource() 或 registerTool() / registerResource() 方法，官方 SDK 随版本有所调整。请始终对照最新的 MCP 官方文档 或 Context7 进行确认。

使用 stdio 进行连接

对于本地客户端，需创建一个 stdio 传输实例并传入服务器的 connect 方法。具体的 API 形式取决于 SDK 版本（如构造函数模式 vs 工厂函数模式）。请查阅 MCP 官方文档或在 Context7 中查询 "MCP stdio server" 获取最新的实现模式。

建议将服务器的核心逻辑（工具 + 资源）与传输层解耦，以便在入口文件中灵活切换 stdio 或 HTTP。

远程连接（Streamable HTTP）

针对 Cursor、云端环境或其他远程客户端，请使用 Streamable HTTP（按当前规范，每个 MCP 仅需单个 HTTP 端点）。只有在必须向下兼容旧版本时才提供传统的 HTTP/SSE 支持。

代码示例

安装与服务器初始化

npm install @modelcontextprotocol/sdk zod

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

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

根据你所用的 SDK 版本接口注册工具和资源：部分版本采用 server.tool(name, description, schema, handler) 的位置参数写法，另一些版本则使用 server.tool({ name, description, inputSchema }, handler) 或 registerTool()。Resource 的注册同理 —— 当 API 传递参数时，记得在 handler 中包含 uri。请务必核对 MCP 官方文档或 Context7 中最新的 @modelcontextprotocol/sdk 签名，避免直接复制粘贴旧版代码导致的报错。

建议使用 Zod（或 SDK 推荐的 Schema 格式）来进行输入参数的校验。

最佳实践

• Schema 优先：为每个 Tool 显式定义输入 Schema，并清晰描述参数与返回值结构。
• 结构化报错：返回模型易于理解的结构化错误或提示信息，避免直接丢出原始堆栈轨迹（Stack Trace）。
• 幂等性设计：尽可能确保 Tool 的幂等性，以便在重试时保证安全。
• 速率与成本控制：涉及调用外部 API 的 Tool，需考虑频率限制与调用成本，并在 Tool 的 description 中显式标注。
• 版本锁定：在 package.json 中锁定 SDK 的具体版本；升级前仔细阅读 Release Notes。

官方 SDK 与相关文档

• JavaScript/TypeScript：@modelcontextprotocol/sdk (npm)。可在 Context7 中搜索 "MCP" 库名以获取最新的注册与传输实现模式。
• Go：GitHub 上的官方 Go SDK (modelcontextprotocol/go-sdk)。
• C#：适用于 .NET 的官方 C# SDK。