SuperAPI AI 工具集

mcp-server-patterns

智能体与模型

查看项目

更新于 10-15 21:09

技能介绍

用途:该技能用于构建和维护 MCP(Model Context Protocol)服务器,让 AI 助手能够调用工具、读取资源和获取提示词模板。官方 SDK API 会演进,文中建议通过 Context7(查询文档关键词 "MCP")或官方 MCP 文档核对当前的方法名与签名。

适用时机:新建 MCP 服务器、添加工具或资源、选择 stdio 与 HTTP 传输、升级 SDK,或排查 MCP 注册与传输问题时使用。

核心概念:工具(Tools)是模型可调用的动作,如搜索、执行命令,通过 registerTool() 或 tool() 注册,取决于 SDK 版本;资源(Resources)是模型可读取的只读数据,如文件内容、API 响应,通过 registerResource() 或 resource() 注册,处理函数通常接收 uri 参数;提示词(Prompts)是可复用、带参数的模板,供客户端展示,通过 registerPrompt() 或等价方法注册;传输层方面,stdio 用于本地客户端(如 Claude Desktop),远程场景(Cursor、云)推荐 Streamable HTTP,旧版 HTTP/SSE 仅用于向后兼容。

连接方式:本地客户端创建 stdio 传输并传给服务器的 connect 方法,具体 API 因 SDK 版本而异;远程客户端使用 Streamable HTTP,每个当前规范对应单一 MCP HTTP 端点。建议将服务器逻辑(工具与资源)与传输解耦,以便在入口处灵活替换。

示例与安装:npm install @modelcontextprotocol/sdk zod;使用 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js" 和 Zod 做输入校验。不同版本可能使用 server.tool(name, description, schema, handler) 位置参数形式,或 server.tool({ name, description, inputSchema }, handler)、registerTool() 形式,务必参考当前官方文档。

最佳实践:先定义 schema 并文档化参数与返回结构;返回模型可解析的结构化错误而非堆栈;尽量保证工具幂等以便安全重试;调用外部 API 的工具需考虑速率与成本并在描述中说明;在 package.json 中固定 SDK 版本,升级时查看发布说明。

官方 SDK:JavaScript/TypeScript 为 @modelcontextprotocol/sdk(npm);Go 为 GitHub 上的 modelcontextprotocol/go-sdk;C# 有 .NET 官方 SDK。其他细节(如具体收费、平台支持范围)暂未提供。