MCP 服务器模式

模型上下文协议（Model Context Protocol，MCP）允许 AI 助手从您的服务器调用工具、读取资源和使用提示词。在构建或维护 MCP 服务器时使用此技能。SDK API 会不断演进；请查阅 Context7（查询“MCP”的文档）或官方 MCP 文档以获取当前的方法名称和签名。

使用时机

适用场景：实现新的 MCP 服务器、添加工具或资源、选择 stdio 与 HTTP 传输、升级 SDK，或调试 MCP 注册和传输问题。

工作原理

核心概念

• 工具 (Tools)：模型可以调用的操作（例如搜索、运行命令）。根据 SDK 版本，使用 registerTool() 或 tool() 进行注册。
• 资源 (Resources)：模型可以获取的只读数据（例如文件内容、API 响应）。使用 registerResource() 或 resource() 进行注册。处理函数通常接收一个 uri 参数。
• 提示词 (Prompts)：客户端可以呈现的可重用、参数化的提示词模板（例如在 Claude Desktop 中）。使用 registerPrompt() 或等效方法进行注册。
• 传输 (Transport)：stdio 用于本地客户端（例如 Claude Desktop）；Streamable HTTP 是远程客户端（Cursor、云端）的首选。传统的 HTTP/SSE 仅用于向后兼容。

Node/TypeScript SDK 可能暴露 tool() / resource() 或 registerTool() / registerResource()；官方 SDK 随时间发生了变化。始终根据当前的 MCP 文档 或 Context7 进行验证。

使用 stdio 连接

对于本地客户端，创建一个 stdio 传输并将其传递给服务器的 connect 方法。确切的 API 因 SDK 版本而异（例如构造函数与工厂模式）。请参阅官方 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 首选的架构格式）进行输入验证。

最佳实践

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

官方 SDK 和文档

• JavaScript/TypeScript：@modelcontextprotocol/sdk（npm）。使用 Context7，库名为“MCP”，获取当前注册和传输模式。
• Go：GitHub 上的官方 Go SDK（modelcontextprotocol/go-sdk）。
• C#：官方的 .NET C# SDK。