MCP 服务器模式 是做什么的？
Model Context Protocol (MCP) 允许 AI 助手调用工具、读取资源以及使用您服务器上的提示词。在构建或维护 MCP 服务器时使用此技能。SDK API 会不断演进；请使用 Context7（查询 query-docs 并搜索 "MCP"）或官方 MCP 文档来获取当前的方法名称和签名。
关于更广泛的路由决策（即能力应作为规则、技能、MCP 还是普通的 CLI/API 工作流），请参阅 docs/capability-surface-selection.md。
何时使用
在以下情况使用：实现新的 MCP 服务器、添加工具或资源、选择 stdio 还是 HTTP、升级 SDK，或调试 MCP 注册与传输问题。
工作原理
核心概念
- 工具：模型可以调用的动作（例如搜索、运行命令）。根据 SDK 版本使用
registerTool()或tool()进行注册。 - 资源：模型可以获取的只读数据（例如文件内容、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 传输对象并将其传递给服务器的 connect 方法。确切的 API 因 SDK 版本而异（例如构造函数 vs 工厂方法）。请参考官方 MCP 文档或查询 Context7 中 "MCP stdio 服务器" 的模式。
保持服务器逻辑（工具 + 资源）与传输无关，以便在入口点中轻松接入 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)。使用库名称 "MCP" 查询 Context7 以获取当前的注册和传输模式。 - Go：官方 Go SDK 在 GitHub 上 (
modelcontextprotocol/go-sdk)。 - C#：适用于 .NET 的官方 C# SDK。