| name | mcp-server-patterns |
| description | 使用 Node/TypeScript SDK 构建 MCP 服务器 — 工具、资源、提示、Zod 验证、stdio vs Streamable HTTP。使用 Context7 或官方 MCP 文档获取最新 API。 |
MCP 服务器模式
模型上下文协议（MCP）允许 AI 助手调用工具、读取资源和使用服务器的提示。在构建或维护 MCP 服务器时使用此技能。SDK API 会演变；查看 Context7（查询文档 "MCP"）或官方 MCP 文档以获取当前方法名称和签名。
何时使用
当以下情况时使用：实现新的 MCP 服务器、添加工具或资源、选择 stdio vs HTTP、升级 SDK，或调试 MCP 注册和传输问题。
工作原理
核心概念
- 工具：模型可以调用的操作（例如搜索、运行命令）。使用
registerTool() 或 tool() 注册，取决于 SDK 版本。
- 资源：模型可以获取的只读数据（例如文件内容、API 响应）。使用
registerResource() 或 resource() 注册。处理程序通常接收 uri 参数。
- 提示：客户端可展示的可重用、参数化提示模板（例如在 Claude Desktop 中）。使用
registerPrompt() 或等效项注册。
- 传输：stdio 用于本地客户端（例如 Claude Desktop）；Streamable HTTP 优先用于远程（Cursor、云）。传统 HTTP/SSE 用于向后兼容。
Node/TypeScript SDK 可能公开 tool() / resource() 或 registerTool() / registerResource()；官方 SDK 随时间发生了变化。始终对照当前 MCP 文档 或 Context7 进行验证。
使用 stdio 连接
对于本地客户端，创建 stdio 传输并将其传递给服务器的连接方法。确切的 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 版本提供的 API 注册工具和资源：某些版本使用 server.tool(name, description, schema, handler)（位置参数），其他版本使用 server.tool({ name, description, inputSchema }, handler) 或 registerTool()。资源也是如此 — 当 API 提供时，在处理程序中包含 uri。查看官方 MCP 文档或 Context7 以获取当前 @modelcontextprotocol/sdk 签名，以避免复制粘贴错误。
使用 Zod（或 SDK 首选的 schema 格式）进行输入验证。
最佳实践
- Schema 优先：为每个工具定义输入 schema；记录参数和返回形状。
- 错误：返回结构化错误或模型可以解释的消息；避免原始堆栈跟踪。
- 幂等性：尽可能优先使用幂等工具，以便重试安全。
- 速率和成本：对于调用外部 API 的工具，考虑速率限制和成本；在工具描述中记录。
- 版本控制：在 package.json 中固定 SDK 版本；升级时查看发行说明。
官方 SDK 和文档
- JavaScript/TypeScript：
@modelcontextprotocol/sdk（npm）。使用 Context7 和库名称 "MCP" 获取当前注册和传输模式。
- Go：GitHub (
modelcontextprotocol/go-sdk) 上的官方 Go SDK。
- C#：.NET 的官方 C# SDK。
