mcp-use 高级特性实战指南：OpenAPI 生成、代理服务器、通知订阅与 Elicitation

后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载本篇指南以 advanced-features.md 为核心骨架系统讲解 mcp-use TypeScript MCP Server 的五类高级能力从 OpenAPI 文档一键生成工具、代理组合上游 MCP 服务器、请求作用域内的实时通知、列表与资源的失效广播到面向强交互客户端的 Elicitation 结构化输入采集。读者完成后将掌握这些特性的启用条件、调用时机、边界限制与安全约束能够在真实项目中直接落地使用。文中所有结论均可在 libraries/typescript/packages/server/src 目录下的源码中得到验证。前置说明这些特性属于进阶用法仅在任务确实需要时才引入。mcp-use 仍在快速演进使用前请以当前安装的包版本为准核对具体选项与现有限制参见 SKILL.md 中以已安装版本为事实来源的工作流约定。OpenAPI 生成工具把 REST API 变成 MCP 工具MCPServer.fromOpenAPI()允许将一个已解析并打包bundled的 OpenAPI 3.x 文档直接转换为一个预填充好工具的 MCP 服务器。每一个被包含的 OpenAPI 操作operation都会注册为一个工具工具会校验输入、调用对应的上游 HTTP 端点并以 SDK 原生的工具结果形态返回响应。用法如下const spec await fetch(https://api.example.com/openapi.json) .then((response) response.json()); const server MCPServer.fromOpenAPI({ spec }); await server.listen(3000);关键选项与输入映射规则fromOpenAPI接受一个FromOpenAPIOptions选项对象常用字段包括spec解析后的 OpenAPI 文档对象必须是 JSON 对象不能是字符串或文件路径。baseUrl当文档内没有可用的 server URL 时使用。源码中resolveBaseUrl的优先级为options.baseUrl ?? options.spec.servers?.[0]?.url两者都缺失时抛出错误MCPServer.fromOpenAPI requires options.baseUrl or spec.servers[0].url见 openapi/index.ts。因此建议始终显式传入baseUrl避免依赖文档中的 server 声明。tags按操作标签tags过滤只暴露命中标签的 operation。exclude排除规则数组可按method、operationId支持字符串精确匹配或正则、path、tags组合排除见 openapi/index.ts。auth{ type: bearer, token }或{ type: header, name, value }生成的工具调用上游时会自动附加认证头见 openapi/index.ts。fetch可选的自定义 fetch 实现默认使用globalThis.fetch见 openapi/index.ts。生成工具的输入 Schema 覆盖以下来源见 openapi/index.tspath 参数占位符会被插值进 URL 并做encodeURIComponent编码path 参数始终标记为 required。query 参数追加到查询字符串数组值会逐项追加为多个同名参数空值会被跳过。header 参数写入请求头。JSON 兼容的请求体映射为名为body的输入字段只有当 OpenAPI 文档声明该 body 为 required 时才标记必填。只识别application/json、application/*json及包含json的媒体类型见 openapi/index.ts提交时自动设置content-type: application/json。工具命名优先使用operationId缺省时退化为${method}_${path}的形式经过 slug 化处理并截断到 64 字符重名时自动追加_2、_3后缀见 openapi/index.ts。工具描述会拼接 operation 的 summary、description 以及HTTP: METHOD /path行。必须知晓的三条边界先打包外部$ref再传入源码中的resolveRef只处理以#/开头的内部引用见 openapi/index.tsMCPServer.fromOpenAPI的文档注释也明确说明外部$ref不会被拉取。因此凡是引用了外部文件如common.yaml#/components/schemas/...的文档必须在创建服务器之前用工具如apidevtools/swagger-parser、redocly bundle完成打包。cookie 参数与非 JSON 请求体不暴露createInputBindings会过滤掉parameter.in cookie的参数见 openapi/index.ts非 JSON 媒体类型的请求体如表单、二进制流不会生成输入字段。不生成outputSchema生成的工具不会从响应定义推导结构化输出 Schema调用结果以原始 JSON若响应为 JSON 则同时写入structuredContent或纯文本形式返回见 openapi/index.ts。如果下游客户端需要结构化结果需另行包装。小技巧当同一参数名在 path/query/header 多处出现或与body字段同名时输入字段会自动加上_in后缀如id_path、id_query以避免冲突若仍冲突则追加数字后缀见 openapi/index.ts。代理 MCP 服务器组合上游能力server.proxy()可以把上游的 MCP 服务器挂载到当前服务器上将其工具、资源和提示词转发给当前服务器的客户端。这在聚合多个领域服务的场景下非常实用——例如把天气服务、数据库服务和文件服务统一暴露在一个端点下。await server.proxy({ weather: { url: https://weather.example.com/mcp, authToken: process.env.WEATHER_MCP_TOKEN, }, });两种挂载方式与所有权语义proxy()有两种重载见 server.ts配置映射形式proxy(Recordstring, ProxyServerConfig)以名称作为 key 配置上游 HTTP 连接通过可选的mcp-use/clientv2 peer 建立连接。每个 key 自动成为命名空间挂载的工具、静态资源和提示词都会被前缀化避免多上游之间重名冲突。config 创建的连接由服务器自身拥有服务器关闭时会被自动关闭见 server.ts 的#proxyOwners与关闭逻辑。现成连接形式proxy(ProxyConnection)传入一个已就绪的mcp-use/client连接此时以该连接协商出的服务器名作为命名空间连接仍归调用方所有应用需要自行关闭它。匿名连接无服务器名无法作为命名空间因此该重载会拒绝匿名连接。硬性前提与安全提示必须安装可选依赖mcp-use/client源码在proxy()内部通过动态import(./mcp-proxy.js)加载实现见 server.ts未安装时会抛出错误。调用时机必须在listen()或第一次server.fetch请求之前调用服务器已启动或已关闭后调用会抛错#assertOpen守卫。认证需显式提供代理启动流程不会运行交互式 OAuth。bearer token 或自定义 header 必须由你显式传入如上面的authToken。连接与挂载的容错连接、内省introspection和命名冲突失败会被诊断并跳过不会丢弃其余可挂载的能力见 server.ts 的注释及 mcp-proxy.ts 实现。能力转发并非全量不要假设每个能力都会被转发。在设计依赖 resource templates资源模板、completions补全、subscriptions订阅以及上游列表重新同步list resynchronization的架构之前务必先确认当前版本对这些能力的实际支持情况。若你的代理场景必须用到这些能力需要先在真实上游上做端到端验证。请求作用域的通知仅存活于回调期间mcp-use 的请求上下文Request Context提供了三个通知方法用于在工具、资源、提示词回调执行期间向客户端发送状态更新。它们与回调结束后广播的消息通道有本质区别必须在回调活跃期间使用并 await它们不是响应后的广播通道。await ctx.sendNotification(com.example/import-status, { status: started }); await ctx.reportProgress(50, 100, Halfway); await ctx.sendLog(info, { imported: 42 }, import-worker);这三个方法在 context.ts 中的实现值得关注sendNotification(method, params)发送自定义协议通知底层调用ctx.mcpReq.notify({ method, params })。method 命名建议遵循自定义通知的惯例如com.example/import-status。reportProgress(progress, total?, message?)发送标准notifications/progress通知。关键行为它读取请求元数据中的progressToken当调用方客户端未提供进度令牌时返回false见 context.ts你可以据此判断进度是否真的会被送达从而决定是否降级为日志输出。sendLog(level, data, logger?)发送标准notifications/message日志通知参数与协议字段一一对应level、data、可选的logger。使用建议把状态上报放在回调的中段或长耗时操作的循环里并在回调返回前await这些调用确保通知已发出不要依赖它们传递回调已完成这类回调结束后才产生的事件。列表与资源失效面向订阅者的非持久广播当服务器的可发现列表工具、提示词、资源清单或某个资源的表示内容发生变更时可以调用服务器级别的通知方法向持有活跃订阅监听器的 v2 客户端发布变更通知见 server.tsawait server.notifyToolsChanged(); await server.notifyPromptsChanged(); await server.notifyResourcesChanged(); await server.notifyResourceUpdated(config://settings);notifyToolsChanged()/notifyPromptsChanged()/notifyResourcesChanged()分别广播工具列表、提示词列表、资源列表的变化。notifyResourceUpdated(uri)针对单个资源 URI 的表示变更进行定向通知。语义上的重要边界这些通知是非持久的缓存失效信号non-durable cache invalidations。不要把它们当作可靠的事件总线来设计架构应当让资源或注册表registry本身保持权威读取操作可重复幂等绝不依赖每个事件的送达——客户端可能没有订阅、连接可能中断、通知可能丢失把客户端稍后重新拉取列表/资源作为兜底路径确保即使全部通知丢失系统仍然正确。这些方法与请求作用域的ctx.*通知不同它们是跨请求的服务器级广播只投递给当前已建立订阅的 v2 客户端。调用前服务器需要已完成挂载源码中先#ensureSkillsPrimed()再#ensureMounted()因此在服务器尚未启动时调用会抛错。Elicitation在工具调用中采集结构化输入Elicitation 是 mcp-use 为能理解并返回结构化输入的客户端设计的能力当工具回调需要收集结构化输入或完成一个外部流程如人工审批时使用ctx.elicit(key, message, schemaOrUrl)向客户端发起请求。基本用法与状态机const approval await ctx.elicit(publish-approval, Publish now?, schema); if (approval.status required) return approval.result; if (approval.status ! accept || !approval.data.approve) { return { isError: true, content: [{ type: text, text: Not approved }] }; }调用结果approval是一个状态对象需要按状态分派处理status required客户端要求服务器先返回结果再继续此时应直接返回approval.result通常是带inputRequired标记的结果信封告诉客户端需要补充输入。status accept客户端已接受并返回输入数据读取approval.data继续执行业务逻辑。status decline/status cancel客户端拒绝或取消按失败路径处理。关键点在于工具回调会因输入缺失而重跑rerun。第一轮调用返回required结果后客户端补充输入并重新发起调用此时回调再次执行ctx.elicit这次拿到的是已填写的accept结果。这就是为什么每次调用都要同时处理required、accept、decline、cancel四种分支。仓库的 conformance 示例中大量使用了这一模式展示了inputRequired.elicit(...)与后续分支判断的完整写法见 conformance/src/index.ts。安全与连续性守则Elicitation 引入了跨轮次延续的执行模型随之而来的是更严格的安全要求副作用时机只在收到 accepted 输入之后再执行不可逆的副作用写库、发消息、扣款等不要在首轮就执行。稳定且唯一的 key每个问题使用独立、稳定的 key如publish-approval避免不同问题共用一个 key 导致状态混淆。校验裸输入对任何直接给出的输入bare input responses都要做独立校验不能假设客户端返回的数据一定符合 Schema。验证请求状态当连续性影响授权或业务逻辑时使用经过验证的请求状态如 OAuth 配置下的ctx.auth来判断后续轮次是否仍由同一主体发起。严禁采集敏感信息永远不要在表单式 Elicitation 中收集密码、API 密钥、支付详情或 OAuth 密钥。这类机密应通过专门的认证流程参见 auth.md处理。组合使用与验证建议这五类特性可以组合出复杂的服务器行为例如用fromOpenAPI快速接入 REST 后端 → 用proxy聚合多个内部 MCP 服务 → 在回调中通过ctx.reportProgress反馈长任务进度 → 变更注册表后调用server.notifyToolsChanged()广播失效 → 对需要人工确认的发布操作使用ctx.elicit采集审批。由于这些特性大多依赖客户端的主动支持订阅、进度令牌、Elicitation 能力声明落地时务必做到先检查客户端能力回调上下文提供ctx.client.can(...)和ctx.client.capabilities()用于探测客户端是否支持sampling、elicitation、subscriptions等能力见 context.ts据此决定是否降级。用最小生命周期验证为每项特性编写覆盖真实生命周期的最小验证——例如先确认reportProgress返回true有 progressToken再断言客户端确实收到通知。以已安装版本为准包版本之间的行为细节如 proxy 的能力转发范围、OpenAPI 工具的 Schema 转换策略可能变化编写代码前先核对当前mcp-use版本的声明文件.d.ts与 CHANGELOG。更完整的服务器基础能力工具、资源、提示词、MCP 中间件、请求上下文、结果信封参见 server.md涉及认证与授权时参见 auth.md。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐mcp-use MCP 服务端高级特性实战指南OpenAPI 生成工具、服务器代理、请求级通知与 Elicitation 交互mcp use MCP 服务端高级特性实战指南OpenAPI 生成工具、服务器代理、请求级通知与 Elicitation 交互 本指南基于 mcp use 官后端MCP 服务MCP ClientsAI Agent人工智能Prisma DBML Generator 与其他数据库文档工具的对比分析Prisma DBML Generator 与其他数据库文档工具的对比分析 Prisma DBML Generator 是一款强大的数据库文档生成工具它能够将Inspector MCP 服务器 UX 处理器与交互模式深度解析Sampling、Elicitation、Roots 与表单生成实战指南Inspector MCP 服务器 UX 处理器与交互模式深度解析Sampling、Elicitation、Roots 与表单生成实战指南 导读 本文以 MC开发工具MCP Clients调试器上一篇闲鱼数据采集实战基于uiautomator2的移动端自动化爬虫技术解析下一篇魔兽争霸3在Windows 11完美运行的终极解决方案WarcraftHelper完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考