Mcp Server Patterns

使用 stdio 连接

对于本地客户端，创建一个 stdio 传输并将其传递给服务器的连接方法。确切的 API 因 SDK 版本而异（例如构造函数与工厂函数）。请参阅官方 MCP 文档或查询 Context7 中的 "MCP stdio server" 以获取当前模式。

保持服务器逻辑（工具 + 资源）独立于传输，以便您可以在入口点中插入 stdio 或 HTTP。

远程（可流式 HTTP）

对于 Cursor、云端或其他远程客户端，使用可流式 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 首选的模式格式）进行输入验证。

最佳实践

• 模式优先：为每个工具定义输入模式；记录参数和返回形状。
• 错误处理：返回结构化错误或模型可以解释的消息；避免原始堆栈跟踪。
• 幂等性：尽可能使用幂等工具，以便重试是安全的。
• 速率和成本：对于调用外部 API 的工具，请考虑速率限制和成本；在工具描述中加以说明。
• 版本控制：在 package.json 中固定 SDK 版本；升级时查看发行说明。

官方 SDK 和文档

• JavaScript/TypeScript：@modelcontextprotocol/sdk (npm)。使用库名 "MCP" 的 Context7 以获取当前的注册和传输模式。
• Go：GitHub 上的官方 Go SDK (modelcontextprotocol/go-sdk)。
• C#：适用于 .NET 的官方 C# SDK。