SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mcp-server-patterns

mcp-server-patterns

编程与开发

查看项目

更新于 10-15 08:38

技能介绍

用途

MCP Server Patterns 用于指导开发者构建和维护 MCP（Model Context Protocol）服务器。MCP 让 AI 助手能够调用工具、读取资源并使用服务器提供的提示。当需要实现新的 MCP 服务器、为现有服务器添加工具或资源、在 stdio 与 HTTP 之间做传输选择、升级 SDK，或调试 MCP 注册与传输问题时，可以使用该技能。

对于“某项能力应当做成规则、技能、MCP，还是普通 CLI/API 工作流”这类更上层的路由决策，资料指向 docs/capability-surface-selection.md。

主要能力

该技能围绕 MCP 的核心概念展开：

  • 工具（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 核实。

使用方式

安装与服务器初始化

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 时，在处理函数中包含 uri。建议查阅官方 MCP 文档或通过 Context7 查询当前 @modelcontextprotocol/sdk 的签名，以避免复制粘贴错误。输入校验使用 Zod（或 SDK 偏好的 schema 格式）。

使用 stdio 连接

对于本地客户端，创建 stdio 传输并将其传给服务器的 connect 方法。具体 API 因 SDK 版本而异（例如构造函数 vs 工厂函数）。请参阅官方 MCP 文档，或通过 Context7 查询 “MCP stdio server” 获取当前模式。建议让服务器逻辑（工具 + 资源）与传输保持独立，以便在入口处灵活接入 stdio 或 HTTP。

远程（Streamable HTTP）

对于 Cursor、云端或其他远程客户端，使用 Streamable HTTP（按当前规范为单一 MCP HTTP 端点）。仅在需要向后兼容时支持旧版 HTTP/SSE。

最佳实践

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

适用场景

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

官方 SDK 与文档

  • JavaScript/TypeScript：@modelcontextprotocol/sdk（npm）。使用 Context7 并以 “MCP” 作为库名查询当前注册与传输模式。
  • Go：GitHub 上的官方 Go SDK（modelcontextprotocol/go-sdk）。
  • C#：面向 .NET 的官方 C# SDK。

限制

资料未提供具体的收费、价格、平台支持范围或效果数据。SDK API 会持续演进，具体方法名与签名需以官方 MCP 文档或 Context7 查询结果为准。