后端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是一个面向 ChatGPT / Claude 等客户端与 AI Agent 的全栈 MCP 框架既可以用 TypeScript 编写支持工具、资源、提示词、中间件、认证的 MCP Server也可以构建带交互式 Views 的 MCP Apps。本文基于仓库中官方 Skill 文档 skills/mcp-apps-builder/SKILL.md 及其全套 references系统讲解从项目脚手架、工具注册、Views 绑定、OAuth 认证、Skills over MCP 到迁移与验证的完整开发流程。读完本文你将掌握一套以已安装包类型声明为准的可靠开发方法能够独立搭建、调试、迁移并验证一个生产可用的 TypeScript MCP 服务。Skill 定位与适用场景mcp-apps-builder是仓库skills/目录下官方提供的构建型 Skill其余还有mcp-builder、openapi-to-mcp、chatgpt-app-builder等其使命是指导开发者完成以下工作构建从零搭建 TypeScript MCP Server 与 MCP Apps修改在既有项目上安全地增删工具、资源、提示词、中间件调试与验证通过开发服务器、Inspector 与 CLI 客户端验证行为迁移将旧版mcp-use模式如widget、mcp-use/server导入迁移到当前推荐形态审查对照核心不变量Core invariants审查代码质量。Skill 声明frontmatter明确其适用范围tools, resources, prompts, middleware, Views, authentication, Skills over MCP, scaffolding, and advanced features即覆盖框架的绝大多数核心能力。核心工作流以安装版本为唯一事实源Skill 的首要原则是把已安装的mcp-use包、其导出的类型、生成的声明文件以及项目既有代码当作事实源source of truth。在选择 API 或改动代码之前必须先检查安装版本。这一原则贯穿全文目的是避免开发者依据旧教程、历史 changelog 或网上示例写出与当前版本不兼容的代码。推荐的五步工作流如下检查现状阅读package.json、服务器入口、导出的工具引用tool refs、mcp-env.d.ts、views/、skills/目录以及已安装的mcp-use版本脚手架新稳定项目用create-mcp-use-applatest配合合适的模板创建见下文若工作对象是 beta、canary 或既有版本化项目则匹配对应包版本或 dist-tag按需阅读参考文档只读与当前任务相关的 references 文件Server工具、资源、提示词、MCP 中间件、请求上下文与结果封装Views交互式 MCP Apps、React hooks、模型上下文、宿主能力、静态资源与 CSPAuthenticationOAuth 提供商、已验证身份、scopes、权限与授权Skills over MCP让服务器随工具一起发布可复用工作流Advanced featuresOpenAPI、代理、通知、订阅与 elicitationMigration仅在项目出现已退役或兼容性导入时阅读Verification在汇报实现完成之前阅读按已安装类型实现优先遵循框架当前约定而非照抄示例代码或历史 changelog最小验证先验证能证明行为变更的最小真实生命周期再按风险比例扩大检查范围。核心不变量Core invariantsSkill 归纳了所有 mcp-use 开发都必须遵守的架构性约定这些不变量也是后续Guardrails的依据导入路径服务器 API 从mcp-use导入React API 从mcp-use/react导入OAuth 提供商适配器从mcp-use/oauth/*子路径导入Schema工具参数用inputSchema定义结构化结果与每个绑定 View 的工具必须增加outputSchema结果封装工具回调返回原始 MCP 结果封装——成功的 schema-backed 工具必须包含匹配的structuredContent预期失败可返回isError: true并附上模型可读的contentView 布局每个 View 放在views/name/view.tsx并用view: { name: name }绑定导出规则导出 View 消费的每个静态声明工具引用ToolRef默认导出mcp-use dev/build/start使用的服务器入口状态边界身份与可变工作流状态必须是请求作用域request-scoped或放在外部存储中客户端上报的元数据一律视为未验证unverifiedSkills over MCP当服务器需要暴露可复现的多步工作流、而这些工作流会撑爆工具描述时优先考虑使用 Skill 承载。项目脚手架与生命周期对于全新稳定项目不要手工重造框架样板直接使用脚手架npx create-mcp-use-applatest my-server --template mcp-server从仓库源码看create-mcp-use-app提供blank、mcp-server、mcp-apps等模板目录见 libraries/typescript/packages/create-mcp-use-app/src/templates其中mcp-server模板即普通 MCP Servermcp-apps模板内置views/my-view/view.tsx交互式示例。服务器生命周期有三条铁律从mcp-use导入MCPServer默认导出服务器入口让mcp-use dev、mcp-use build、mcp-use start接管监听器与 View 管线只有显式独立程序才调用server.listen()。工具注册与结果通道工具用 Standard Schema 兼容的校验器Zod、ArkType、Valibot 均可声明参数。字段描述能帮助客户端或模型选择合法输入时应尽量补全。完整示例来自 references/server.mdimport { MCPServer } from mcp-use; import { z } from zod; const server new MCPServer({ name: inventory, version: 1.0.0 }); export const lookupInventory server.tool( { name: lookup-inventory, description: Return available inventory for one SKU, inputSchema: z.object({ sku: z.string().describe(Inventory SKU) }), outputSchema: z.object({ sku: z.string(), available: z.number().int() }), annotations: { readOnlyHint: true, openWorldHint: false }, }, async ({ sku }) { const data { sku, available: await inventory.count(sku) }; return { content: [{ type: text, text: JSON.stringify(data) }], structuredContent: data, }; }, ); export default server;要点补充visibility: app用于仅供 Views 调用、对模型隐藏的辅助工具annotations是行为提示不是授权控制结果通道分工content放精炼的模型可读文本存在outputSchema时structuredContent放 schema 校验过的 JSON_meta放仅本次调用、仅 View 可见的数据View 内需自行校验或收窄预期运维失败返回isError: true并附有用content只有意外故障才应抛出异常使其成为协议错误。资源与提示词单个稳定 URI 用server.resource()URI 族用server.resourceTemplate()。回调返回{ contents: [...] }每条必须包含 URI 与 text 或 base64 blob 二者之一模板回调签名是(uri, params, ctx)模板值可以是string | string[]提示词用server.prompt()参数用schema注意不是工具的inputSchema回调返回{ messages: [...] }。字符串字段包一层completable()可让客户端获得建议值同时不限制其他合法字符串。MCP 中间件与请求上下文协议中间件用server.use(mcp:method, handler)注册。原则使用最窄的操作、调用next()并返回其结果除非刻意替换server.use(mcp:tools/call, async (ctx, next) { const startedAt Date.now(); const result await next(); console.log(${ctx.params.name}: ${Date.now() - startedAt}ms); return result; });工具、资源、提示词回调都会收到请求作用域上下文ctx.signal取消信号ctx.client客户端自报能力不得用于授权ctx.auth仅在配置了 OAuth 时可用。静态能力应在构造服务器时注册当可发现列表或资源内容变化时使用 Advanced features 中的通知辅助函数server.notifyToolsChanged()等发布失效。构建交互式 MCP AppsViews绑定 View创建views/name/view.tsx导出渲染工具引用、声明其outputSchema、绑定view: { name }并返回匹配的structuredContent。目录名与view.name必须完全一致。结果分工与工具一致content给模型读摘要structuredContent放类型化渲染数据_meta放仅 View 可见的调用数据。读取渲染调用在组件中解构useToolContext()并在读取toolOutput前收窄其判别联合discriminated lifecycleimport { useToolContext } from mcp-use/react; export default function ProductResults() { const { status, toolInput, toolOutput, error, meta } useToolContextsearch-products(); if (status pending) { return SearchSkeleton query{toolInput?.query} /; } if (status error) { return ErrorBanner message{error.message} /; } const source typeof meta?.source string ? meta.source : undefined; return ( Results items{toolOutput.items} source{source} / ); }注意pending 状态下toolInput可能是部分值meta是无类型外部数据使用前必须校验或收窄。交互通道针对不同交互场景选择 hook均从mcp-use/react导入useCallTool(tool-name)调用已导出的服务器工具类型自动推断useDynamicTool调用运行时生成的工具无静态引用时useSendFollowUp请求新一轮模型对话useOpenExternal请宿主在沙箱外打开 URLuseDisplayMode查看并请求支持的展示模式useViewTool暴露一个作用于已挂载 UI 的临时操作useFiles在确认宿主支持后使用宿主文件能力。宿主动作一律用useHostContext()的能力信号做守卫。宿主可能拒绝或修改请求因此必须渲染 pending 与失败状态并读取宿主返回的最终状态。状态与模型上下文临时 UI 细节模型无需知道的用 React 状态JSON 可序列化的选择、过滤、草稿或进度用useViewState(objectDefault)——未来模型轮次需要理解它们用ModelContext content...声明式描述当前可见 UI持久业务数据放在后端不放 View 状态密钥与大型仅渲染数据不得进入模型可见状态_uiContext保留给运行时使用。展示、资源与 CSPThemeProvider、ViewControls、useViewTheme、viewConfig仅在确实需要其行为时才使用——运行时默认已引导宿主桥接并启用自动尺寸调整具名viewConfig可限制支持的展示模式或禁用自动调整。View 代码与 CSS 收在各自 View 目录下共享公共文件放public/并通过框架公共资源基址解析不要硬编码 localhost URL。外部来源必须在view.csp中精确声明connectDomainsfetch、EventSource、WebSocketresourceDomains脚本、样式、图片、字体、媒体frameDomains内嵌 framebaseUriDomains仅在刻意使用外部 base URI 时设置。OAuth 认证与已验证身份选择集成方式当服务器需要识别调用者、或按用户/组织/角色/scope/权限授权时配置 OAuth身份提供商支持资源服务器与动态客户端注册Dynamic Client Registration流程时用内置提供商适配器其他兼容提供商用mcp-use/oauth的oauthCustomProvider上游授权服务器使用预注册凭证而非 DCR 时用 OAuth 代理与验证辅助函数适配器必需选项与环境变量以已安装声明和提供商文档为准。适配器从显式子路径导入import { MCPServer } from mcp-use; import { oauthAuth0Provider } from mcp-use/oauth/auth0; const server new MCPServer({ name: secure-server, version: 1.0.0, oauth: oauthAuth0Provider({ domain: process.env.AUTH0_DOMAIN! }), });生产环境应在启动时校验配置而不是依赖非空断言!。使用已验证的请求身份配置 OAuth 后回调上下文包含ctx.auth.user提供商归一化的已验证身份内置用户含id其余字段视提供商而定ctx.auth.scopes来自已验证认证信息的授权范围ctx.auth.permissions提供商映射的应用权限ctx.auth.payload已验证的 claims 或 introspection 数据ctx.auth.accessTokenBearer 令牌仅用于刻意的下游委托ctx.auth.clientId、expiresAt、resource可用时提供。授权要针对具体动作而不是只检查用户存在async ({ documentId }, ctx) { if (!ctx.auth.permissions.includes(documents:delete)) { return { isError: true, content: [{ type: text, text: Forbidden }], }; } await deleteOwnedDocument(documentId, ctx.auth.user.id); return { content: [{ type: text, text: Document deleted }] }; };优先使用归一化用户字段仅当提供商未映射所需已验证值时才读取原始 payload claims。安全边界绝不把ctx.client.user()、locale、location、subject、会话 ID 或其他请求元数据当作已认证身份授权逻辑紧贴敏感操作或放在窄范围的 MCP 中间件中access token 只转发给预期上游资源绝不记录或回传客户端密钥、令牌、完整 claims、提供商 payload 不得出现在示例、日志、工具 content、结构化输出、_meta或 View 状态中多请求状态放在可信外部存储敏感 elicitation 流程使用已验证请求状态不从模块全局或传输细节推断连续性。Skills over MCP随服务器发布可复用工作流当任务需要可复现的多步工作流、策略、参考资料、模板或脚本而这些内容会撑爆工具描述时用 Skill 承载。原则不要用散文替换可执行能力——工具执行动作、资源暴露内容、提示词返回模型就绪消息、Skill 教 Agent 如何安全组合它们。添加 Skill在服务器入口旁创建约定的skills/目录其存在即自动启用发现skills/ process-refund/ SKILL.md references/ policy.md templates/ confirmation.md每个 Skill 需要一个与目录同名的SKILL.md含精简触发元数据与任务指令--- name: process-refund description: Check refund eligibility and process approved customer refunds --- # Process refunds Read references/policy.md before deciding eligibility. Use templates/confirmation.md after a successful refund.SKILL.md保持过程性、精简详细策略与领域知识放 references确定性操作放脚本输出模板或二进制材料放支持文件。所有支持文件都必须在SKILL.md中直接链接并说明何时读取或使用。配置发现通常从MCPServer配置中省略skills只有行为需要差异时才显式设置new MCPServer({ name: shop, version: 1.0.0, skills: true }); new MCPServer({ name: shop, version: 1.0.0, skills: false }); new MCPServer({ name: shop, version: 1.0.0, skills: { directory: server-skills }, });语义true要求存在约定目录false忽略约定目录自定义目录相对项目路径使用--mcp-dir时自动发现跟随 MCP 源目录显式自定义目录仍相对项目路径。发现与验证机制服务器对外通告 draft Skills over MCP 扩展宿主通过skills/list查看目录、skills/get获取某个 Skill、通过资源目录与文件读取读取支持内容。SDK不会把 Skill 文本注入服务器指令或工具描述——激活与否由宿主决定。只服务可信 Skill宿主在激活 Skill 或其允许的工具前应获得用户批准。开发与构建行为不同mcp-use dev遇到无效 Skill 只记录并跳过修复后恢复mcp-use build严格失败于无效目录并把验证通过的快照嵌入生产构建。高级特性按需启用以下特性仅在任务需要时使用确切选项与当前限制以已安装包为准。OpenAPI 生成工具MCPServer.fromOpenAPI()接收解析且捆绑bundled后的 OpenAPI 3.x 文档文档无可用 server URL 时提供baseUrl用tags与exclude限制暴露的操作。外部$ref目标须在创建服务器前捆绑。生成的输入覆盖路径、查询、头部与 JSON 兼容请求体cookie 参数与非 JSON 请求体不暴露生成工具不会从响应定义推导outputSchema。代理 MCP 服务器server.proxy()依赖可选包mcp-use/client须在listen()或首个server.fetch请求前调用。配置映射的键为上游工具、静态资源与提示词做命名空间。Bearer 令牌或请求头须显式提供——代理启动不运行交互式 OAuth。配置创建的连接归服务器所有应用自行关闭显式提供的MCPConnection。不要假定所有能力都被转发设计前确认资源模板、补全、订阅与上游列表重新同步的当前支持情况。请求作用域通知仅在回调活跃期间发送状态await ctx.sendNotification(com.example/import-status, { status: started }); await ctx.reportProgress(50, 100, Halfway); await ctx.sendLog(info, { imported: 42 }, import-worker);返回前必须等待通知完成它不是响应后的广播通道。调用方未提供进度令牌时reportProgress()返回false。列表与资源失效只向有活跃订阅监听器的客户端发布跨请求失效await server.notifyToolsChanged(); await server.notifyPromptsChanged(); await server.notifyResourcesChanged(); await server.notifyResourceUpdated(config://settings);这些是非持久缓存失效保持资源或注册表为权威、让读取可重复、绝不依赖每条事件都被投递。Elicitation输入采集当有能力的客户端需要采集结构化输入或完成外部流程时用ctx.elicit(key, message, schemaOrUrl)。直接返回required.result并在回调重跑时处理accept、decline、cancelconst 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 }] }; }输入必需轮次中回调会重跑不可逆副作用只在输入被接受后执行每个问题使用不同的稳定 key校验任何裸输入响应当连续性影响授权或业务逻辑时使用已验证请求状态。绝不在表单 elicitation 中采集密码、API 密钥、支付信息或 OAuth 密钥。从旧模式迁移仅在项目包含已退役或兼容性模式时阅读迁移指南。迁移的是行为不只是名字且每个变更边界都要对照已安装类型验证。核心替换关系速查完整表格见 references/migration.md旧/兼容模式当前推荐从mcp-use/server导入服务器从mcp-use导入公共服务器 API工具schema工具inputSchema提示词参数仍用schema内联回调字段回调作为注册方法的第二参数链式server.tool(...).tool(...)分别注册tool()返回ToolRef嵌套资源模板配置顶层uriTemplate与complete字段响应辅助函数作为默认结果路径原始工具/资源/提示词协议封装resources/name/widget.tsxviews/name/view.tsx工具widget: { name }工具view: { name }widget({ props, output }){ content, structuredContent, _meta? }useWidget()/useWidgetProps()解构useToolContexttool-name()聚合 Provider 包装运行时引导 聚焦的 React hooks 与组件聚合 widget 状态与宿主方法useViewState、useHostContext、useDisplayMode等聚焦 hooks不要机械重命名每个schema——提示词刻意保留该字段资源与提示词回调签名需独立于工具确认。重建交互式 UI对每个渲染工具把入口移到views/name/view.tsx从服务器入口导出工具引用添加outputSchema与view: { name }模型可读文本放content、类型化渲染数据放structuredContent、仅 View 数据放_meta解构useToolContext()并先处理 pending/error/ready 再读toolOutput用聚焦 hooks 替换聚合 UI 方法把 CSP 移入view.csp公共资源经框架基址解析。移除传输与会话假设回调是请求作用域且可能并发用请求上下文或外部存储替换活跃会话注册表、会话亲和、内存用户身份与响应后客户端定位。ctx.client只用于自报能力ctx.auth用于已验证身份。MCP 端点路径用basePath外部可见公共源用MCP_URL——不要从 localhost 假设重建公共 URL。迁移检查清单在源码、测试、示例与项目文档中搜索上述退役标识符对照已安装包确认公共导入与注册签名先跑类型生成与类型检查再解读下游错误用真实客户端逐一演练每个工具、资源模板与提示词渲染每个迁移后的 View测试 pending/error/ready、交互、资源与 CSP 行为相关边界变化时通过受支持客户端测试认证、通知与 elicitation包导出或依赖变化时打包并从干净消费者导入验证。验证清单提交前必做验证原则先跑能证明所需行为的最小检查涉及生成类型、认证、Views、包边界或并发时再扩大范围。静态检查npx mcp-use typecheck npm run typecheck npm run build不要假设每个项目都定义了两个 typecheck 命令。mcp-use build负责打包与转译不能替代类型检查。新引入的类型、lint、包边界、生成注册表失败都应在交接前解决。服务器与能力检查启动真实开发服务器经公共 MCP 端点连接并驱动被改能力npm run dev npx mcp-use client connect dev http://localhost:3000/mcp npx mcp-use client dev tools list npx mcp-use client dev tools call lookup-inventory skuitem-1工具测试合法输入、schema 拒绝、预期失败与匹配的structuredContent资源读取静态与模板 URI 并演练补全提示词检查精确生成的消息与建议涉及授权与取消路径时一并演练。View 检查在 Inspector 中通过绑定工具渲染每个受影响的 View验证pending/ready/error 渲染View 到工具调用与宿主动作模型可见状态与临时 UI 状态的区别主题、尺寸、支持展示模式与可访问性公共资源、外部请求、CORS、运行时错误与 CSP。用截图命令而非tools call标志捕获真实 Viewnpx mcp-use screenshot --server dev --tool show-product iditem-1高级与打包检查Skills over MCP验证目录、获取 Skill、读取支持文件并跑严格生产构建通知保持监听器活跃确认非持久失效行为Elicitation测试 required/accept/decline/cancel、非法输入、回调重放与副作用顺序代理或 OpenAPI验证代表性生成能力与文档化的不支持边界导出/依赖/打包变化打包后在空的临时消费者中安装——工作区构建无法证明发布边界。最后不要仅为验证源码变更而部署。若用户未要求部署验证本地构建产物并如实说明未测试的外部边界。与仓库其他 Skill 的关系仓库skills/下还提供 mcp-builder专注服务器构建、chatgpt-app-builder 与 openapi-to-mcpOpenAPI 转 MCP等配套 Skill。mcp-apps-builder覆盖面最全——它同时涵盖 Server、Views、认证、Skills over MCP 与迁移验证是理解框架全貌的最佳入口其余 Skill 是面向特定场景的纵深补充。References 中多处注明以已安装包声明为准这正是整套 Skill 体系的统一方法论文档与示例只是向导类型声明才是最终裁判。参考与延伸阅读Skill 主文档skills/mcp-apps-builder/SKILL.md服务器参考references/server.mdViews 参考references/views.md认证参考references/auth.mdSkills over MCP 参考references/skills-over-mcp.md高级特性参考references/advanced-features.md迁移参考references/migration.md验证参考references/verification.md脚手架实现libraries/typescript/packages/create-mcp-use-app服务器源码libraries/typescript/packages/server/src客户端含 React hooks源码libraries/typescript/packages/client/src赞分享后端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点击查看免费下载相关推荐RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本 RedisInsight 是 Redis 官方出品的 GUI数据库客户端桌面应用后端前端数据可视化MCP Go SDK 实战指南使用官方 Go SDK 快速构建 MCP Server 与 ClientMCP Go SDK 实战指南使用官方 Go SDK 快速构建 MCP Server 与 Client 本篇技术指南围绕官方 Go SDKgithub.coMCP 服务AI Agent工具调用LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册 本文是 LightGBM 官方参数参考文档 docs/Parameters后端MCP 服务MCP ClientsAI Agent人工智能上一篇在 Kilo Code 中使用 TrustedRouter接入可证明路由与零数据留存 AI 网关下一篇Nautilus Trader 执行适配器测试规范基于 ExecTester 的订单生命周期与状态机验证矩阵创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 mcp-use 构建 TypeScript MCP Server 与 MCP Apps：官方 Skill 实战指南
后端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是一个面向 ChatGPT / Claude 等客户端与 AI Agent 的全栈 MCP 框架既可以用 TypeScript 编写支持工具、资源、提示词、中间件、认证的 MCP Server也可以构建带交互式 Views 的 MCP Apps。本文基于仓库中官方 Skill 文档 skills/mcp-apps-builder/SKILL.md 及其全套 references系统讲解从项目脚手架、工具注册、Views 绑定、OAuth 认证、Skills over MCP 到迁移与验证的完整开发流程。读完本文你将掌握一套以已安装包类型声明为准的可靠开发方法能够独立搭建、调试、迁移并验证一个生产可用的 TypeScript MCP 服务。Skill 定位与适用场景mcp-apps-builder是仓库skills/目录下官方提供的构建型 Skill其余还有mcp-builder、openapi-to-mcp、chatgpt-app-builder等其使命是指导开发者完成以下工作构建从零搭建 TypeScript MCP Server 与 MCP Apps修改在既有项目上安全地增删工具、资源、提示词、中间件调试与验证通过开发服务器、Inspector 与 CLI 客户端验证行为迁移将旧版mcp-use模式如widget、mcp-use/server导入迁移到当前推荐形态审查对照核心不变量Core invariants审查代码质量。Skill 声明frontmatter明确其适用范围tools, resources, prompts, middleware, Views, authentication, Skills over MCP, scaffolding, and advanced features即覆盖框架的绝大多数核心能力。核心工作流以安装版本为唯一事实源Skill 的首要原则是把已安装的mcp-use包、其导出的类型、生成的声明文件以及项目既有代码当作事实源source of truth。在选择 API 或改动代码之前必须先检查安装版本。这一原则贯穿全文目的是避免开发者依据旧教程、历史 changelog 或网上示例写出与当前版本不兼容的代码。推荐的五步工作流如下检查现状阅读package.json、服务器入口、导出的工具引用tool refs、mcp-env.d.ts、views/、skills/目录以及已安装的mcp-use版本脚手架新稳定项目用create-mcp-use-applatest配合合适的模板创建见下文若工作对象是 beta、canary 或既有版本化项目则匹配对应包版本或 dist-tag按需阅读参考文档只读与当前任务相关的 references 文件Server工具、资源、提示词、MCP 中间件、请求上下文与结果封装Views交互式 MCP Apps、React hooks、模型上下文、宿主能力、静态资源与 CSPAuthenticationOAuth 提供商、已验证身份、scopes、权限与授权Skills over MCP让服务器随工具一起发布可复用工作流Advanced featuresOpenAPI、代理、通知、订阅与 elicitationMigration仅在项目出现已退役或兼容性导入时阅读Verification在汇报实现完成之前阅读按已安装类型实现优先遵循框架当前约定而非照抄示例代码或历史 changelog最小验证先验证能证明行为变更的最小真实生命周期再按风险比例扩大检查范围。核心不变量Core invariantsSkill 归纳了所有 mcp-use 开发都必须遵守的架构性约定这些不变量也是后续Guardrails的依据导入路径服务器 API 从mcp-use导入React API 从mcp-use/react导入OAuth 提供商适配器从mcp-use/oauth/*子路径导入Schema工具参数用inputSchema定义结构化结果与每个绑定 View 的工具必须增加outputSchema结果封装工具回调返回原始 MCP 结果封装——成功的 schema-backed 工具必须包含匹配的structuredContent预期失败可返回isError: true并附上模型可读的contentView 布局每个 View 放在views/name/view.tsx并用view: { name: name }绑定导出规则导出 View 消费的每个静态声明工具引用ToolRef默认导出mcp-use dev/build/start使用的服务器入口状态边界身份与可变工作流状态必须是请求作用域request-scoped或放在外部存储中客户端上报的元数据一律视为未验证unverifiedSkills over MCP当服务器需要暴露可复现的多步工作流、而这些工作流会撑爆工具描述时优先考虑使用 Skill 承载。项目脚手架与生命周期对于全新稳定项目不要手工重造框架样板直接使用脚手架npx create-mcp-use-applatest my-server --template mcp-server从仓库源码看create-mcp-use-app提供blank、mcp-server、mcp-apps等模板目录见 libraries/typescript/packages/create-mcp-use-app/src/templates其中mcp-server模板即普通 MCP Servermcp-apps模板内置views/my-view/view.tsx交互式示例。服务器生命周期有三条铁律从mcp-use导入MCPServer默认导出服务器入口让mcp-use dev、mcp-use build、mcp-use start接管监听器与 View 管线只有显式独立程序才调用server.listen()。工具注册与结果通道工具用 Standard Schema 兼容的校验器Zod、ArkType、Valibot 均可声明参数。字段描述能帮助客户端或模型选择合法输入时应尽量补全。完整示例来自 references/server.mdimport { MCPServer } from mcp-use; import { z } from zod; const server new MCPServer({ name: inventory, version: 1.0.0 }); export const lookupInventory server.tool( { name: lookup-inventory, description: Return available inventory for one SKU, inputSchema: z.object({ sku: z.string().describe(Inventory SKU) }), outputSchema: z.object({ sku: z.string(), available: z.number().int() }), annotations: { readOnlyHint: true, openWorldHint: false }, }, async ({ sku }) { const data { sku, available: await inventory.count(sku) }; return { content: [{ type: text, text: JSON.stringify(data) }], structuredContent: data, }; }, ); export default server;要点补充visibility: app用于仅供 Views 调用、对模型隐藏的辅助工具annotations是行为提示不是授权控制结果通道分工content放精炼的模型可读文本存在outputSchema时structuredContent放 schema 校验过的 JSON_meta放仅本次调用、仅 View 可见的数据View 内需自行校验或收窄预期运维失败返回isError: true并附有用content只有意外故障才应抛出异常使其成为协议错误。资源与提示词单个稳定 URI 用server.resource()URI 族用server.resourceTemplate()。回调返回{ contents: [...] }每条必须包含 URI 与 text 或 base64 blob 二者之一模板回调签名是(uri, params, ctx)模板值可以是string | string[]提示词用server.prompt()参数用schema注意不是工具的inputSchema回调返回{ messages: [...] }。字符串字段包一层completable()可让客户端获得建议值同时不限制其他合法字符串。MCP 中间件与请求上下文协议中间件用server.use(mcp:method, handler)注册。原则使用最窄的操作、调用next()并返回其结果除非刻意替换server.use(mcp:tools/call, async (ctx, next) { const startedAt Date.now(); const result await next(); console.log(${ctx.params.name}: ${Date.now() - startedAt}ms); return result; });工具、资源、提示词回调都会收到请求作用域上下文ctx.signal取消信号ctx.client客户端自报能力不得用于授权ctx.auth仅在配置了 OAuth 时可用。静态能力应在构造服务器时注册当可发现列表或资源内容变化时使用 Advanced features 中的通知辅助函数server.notifyToolsChanged()等发布失效。构建交互式 MCP AppsViews绑定 View创建views/name/view.tsx导出渲染工具引用、声明其outputSchema、绑定view: { name }并返回匹配的structuredContent。目录名与view.name必须完全一致。结果分工与工具一致content给模型读摘要structuredContent放类型化渲染数据_meta放仅 View 可见的调用数据。读取渲染调用在组件中解构useToolContext()并在读取toolOutput前收窄其判别联合discriminated lifecycleimport { useToolContext } from mcp-use/react; export default function ProductResults() { const { status, toolInput, toolOutput, error, meta } useToolContextsearch-products(); if (status pending) { return SearchSkeleton query{toolInput?.query} /; } if (status error) { return ErrorBanner message{error.message} /; } const source typeof meta?.source string ? meta.source : undefined; return ( Results items{toolOutput.items} source{source} / ); }注意pending 状态下toolInput可能是部分值meta是无类型外部数据使用前必须校验或收窄。交互通道针对不同交互场景选择 hook均从mcp-use/react导入useCallTool(tool-name)调用已导出的服务器工具类型自动推断useDynamicTool调用运行时生成的工具无静态引用时useSendFollowUp请求新一轮模型对话useOpenExternal请宿主在沙箱外打开 URLuseDisplayMode查看并请求支持的展示模式useViewTool暴露一个作用于已挂载 UI 的临时操作useFiles在确认宿主支持后使用宿主文件能力。宿主动作一律用useHostContext()的能力信号做守卫。宿主可能拒绝或修改请求因此必须渲染 pending 与失败状态并读取宿主返回的最终状态。状态与模型上下文临时 UI 细节模型无需知道的用 React 状态JSON 可序列化的选择、过滤、草稿或进度用useViewState(objectDefault)——未来模型轮次需要理解它们用ModelContext content...声明式描述当前可见 UI持久业务数据放在后端不放 View 状态密钥与大型仅渲染数据不得进入模型可见状态_uiContext保留给运行时使用。展示、资源与 CSPThemeProvider、ViewControls、useViewTheme、viewConfig仅在确实需要其行为时才使用——运行时默认已引导宿主桥接并启用自动尺寸调整具名viewConfig可限制支持的展示模式或禁用自动调整。View 代码与 CSS 收在各自 View 目录下共享公共文件放public/并通过框架公共资源基址解析不要硬编码 localhost URL。外部来源必须在view.csp中精确声明connectDomainsfetch、EventSource、WebSocketresourceDomains脚本、样式、图片、字体、媒体frameDomains内嵌 framebaseUriDomains仅在刻意使用外部 base URI 时设置。OAuth 认证与已验证身份选择集成方式当服务器需要识别调用者、或按用户/组织/角色/scope/权限授权时配置 OAuth身份提供商支持资源服务器与动态客户端注册Dynamic Client Registration流程时用内置提供商适配器其他兼容提供商用mcp-use/oauth的oauthCustomProvider上游授权服务器使用预注册凭证而非 DCR 时用 OAuth 代理与验证辅助函数适配器必需选项与环境变量以已安装声明和提供商文档为准。适配器从显式子路径导入import { MCPServer } from mcp-use; import { oauthAuth0Provider } from mcp-use/oauth/auth0; const server new MCPServer({ name: secure-server, version: 1.0.0, oauth: oauthAuth0Provider({ domain: process.env.AUTH0_DOMAIN! }), });生产环境应在启动时校验配置而不是依赖非空断言!。使用已验证的请求身份配置 OAuth 后回调上下文包含ctx.auth.user提供商归一化的已验证身份内置用户含id其余字段视提供商而定ctx.auth.scopes来自已验证认证信息的授权范围ctx.auth.permissions提供商映射的应用权限ctx.auth.payload已验证的 claims 或 introspection 数据ctx.auth.accessTokenBearer 令牌仅用于刻意的下游委托ctx.auth.clientId、expiresAt、resource可用时提供。授权要针对具体动作而不是只检查用户存在async ({ documentId }, ctx) { if (!ctx.auth.permissions.includes(documents:delete)) { return { isError: true, content: [{ type: text, text: Forbidden }], }; } await deleteOwnedDocument(documentId, ctx.auth.user.id); return { content: [{ type: text, text: Document deleted }] }; };优先使用归一化用户字段仅当提供商未映射所需已验证值时才读取原始 payload claims。安全边界绝不把ctx.client.user()、locale、location、subject、会话 ID 或其他请求元数据当作已认证身份授权逻辑紧贴敏感操作或放在窄范围的 MCP 中间件中access token 只转发给预期上游资源绝不记录或回传客户端密钥、令牌、完整 claims、提供商 payload 不得出现在示例、日志、工具 content、结构化输出、_meta或 View 状态中多请求状态放在可信外部存储敏感 elicitation 流程使用已验证请求状态不从模块全局或传输细节推断连续性。Skills over MCP随服务器发布可复用工作流当任务需要可复现的多步工作流、策略、参考资料、模板或脚本而这些内容会撑爆工具描述时用 Skill 承载。原则不要用散文替换可执行能力——工具执行动作、资源暴露内容、提示词返回模型就绪消息、Skill 教 Agent 如何安全组合它们。添加 Skill在服务器入口旁创建约定的skills/目录其存在即自动启用发现skills/ process-refund/ SKILL.md references/ policy.md templates/ confirmation.md每个 Skill 需要一个与目录同名的SKILL.md含精简触发元数据与任务指令--- name: process-refund description: Check refund eligibility and process approved customer refunds --- # Process refunds Read references/policy.md before deciding eligibility. Use templates/confirmation.md after a successful refund.SKILL.md保持过程性、精简详细策略与领域知识放 references确定性操作放脚本输出模板或二进制材料放支持文件。所有支持文件都必须在SKILL.md中直接链接并说明何时读取或使用。配置发现通常从MCPServer配置中省略skills只有行为需要差异时才显式设置new MCPServer({ name: shop, version: 1.0.0, skills: true }); new MCPServer({ name: shop, version: 1.0.0, skills: false }); new MCPServer({ name: shop, version: 1.0.0, skills: { directory: server-skills }, });语义true要求存在约定目录false忽略约定目录自定义目录相对项目路径使用--mcp-dir时自动发现跟随 MCP 源目录显式自定义目录仍相对项目路径。发现与验证机制服务器对外通告 draft Skills over MCP 扩展宿主通过skills/list查看目录、skills/get获取某个 Skill、通过资源目录与文件读取读取支持内容。SDK不会把 Skill 文本注入服务器指令或工具描述——激活与否由宿主决定。只服务可信 Skill宿主在激活 Skill 或其允许的工具前应获得用户批准。开发与构建行为不同mcp-use dev遇到无效 Skill 只记录并跳过修复后恢复mcp-use build严格失败于无效目录并把验证通过的快照嵌入生产构建。高级特性按需启用以下特性仅在任务需要时使用确切选项与当前限制以已安装包为准。OpenAPI 生成工具MCPServer.fromOpenAPI()接收解析且捆绑bundled后的 OpenAPI 3.x 文档文档无可用 server URL 时提供baseUrl用tags与exclude限制暴露的操作。外部$ref目标须在创建服务器前捆绑。生成的输入覆盖路径、查询、头部与 JSON 兼容请求体cookie 参数与非 JSON 请求体不暴露生成工具不会从响应定义推导outputSchema。代理 MCP 服务器server.proxy()依赖可选包mcp-use/client须在listen()或首个server.fetch请求前调用。配置映射的键为上游工具、静态资源与提示词做命名空间。Bearer 令牌或请求头须显式提供——代理启动不运行交互式 OAuth。配置创建的连接归服务器所有应用自行关闭显式提供的MCPConnection。不要假定所有能力都被转发设计前确认资源模板、补全、订阅与上游列表重新同步的当前支持情况。请求作用域通知仅在回调活跃期间发送状态await ctx.sendNotification(com.example/import-status, { status: started }); await ctx.reportProgress(50, 100, Halfway); await ctx.sendLog(info, { imported: 42 }, import-worker);返回前必须等待通知完成它不是响应后的广播通道。调用方未提供进度令牌时reportProgress()返回false。列表与资源失效只向有活跃订阅监听器的客户端发布跨请求失效await server.notifyToolsChanged(); await server.notifyPromptsChanged(); await server.notifyResourcesChanged(); await server.notifyResourceUpdated(config://settings);这些是非持久缓存失效保持资源或注册表为权威、让读取可重复、绝不依赖每条事件都被投递。Elicitation输入采集当有能力的客户端需要采集结构化输入或完成外部流程时用ctx.elicit(key, message, schemaOrUrl)。直接返回required.result并在回调重跑时处理accept、decline、cancelconst 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 }] }; }输入必需轮次中回调会重跑不可逆副作用只在输入被接受后执行每个问题使用不同的稳定 key校验任何裸输入响应当连续性影响授权或业务逻辑时使用已验证请求状态。绝不在表单 elicitation 中采集密码、API 密钥、支付信息或 OAuth 密钥。从旧模式迁移仅在项目包含已退役或兼容性模式时阅读迁移指南。迁移的是行为不只是名字且每个变更边界都要对照已安装类型验证。核心替换关系速查完整表格见 references/migration.md旧/兼容模式当前推荐从mcp-use/server导入服务器从mcp-use导入公共服务器 API工具schema工具inputSchema提示词参数仍用schema内联回调字段回调作为注册方法的第二参数链式server.tool(...).tool(...)分别注册tool()返回ToolRef嵌套资源模板配置顶层uriTemplate与complete字段响应辅助函数作为默认结果路径原始工具/资源/提示词协议封装resources/name/widget.tsxviews/name/view.tsx工具widget: { name }工具view: { name }widget({ props, output }){ content, structuredContent, _meta? }useWidget()/useWidgetProps()解构useToolContexttool-name()聚合 Provider 包装运行时引导 聚焦的 React hooks 与组件聚合 widget 状态与宿主方法useViewState、useHostContext、useDisplayMode等聚焦 hooks不要机械重命名每个schema——提示词刻意保留该字段资源与提示词回调签名需独立于工具确认。重建交互式 UI对每个渲染工具把入口移到views/name/view.tsx从服务器入口导出工具引用添加outputSchema与view: { name }模型可读文本放content、类型化渲染数据放structuredContent、仅 View 数据放_meta解构useToolContext()并先处理 pending/error/ready 再读toolOutput用聚焦 hooks 替换聚合 UI 方法把 CSP 移入view.csp公共资源经框架基址解析。移除传输与会话假设回调是请求作用域且可能并发用请求上下文或外部存储替换活跃会话注册表、会话亲和、内存用户身份与响应后客户端定位。ctx.client只用于自报能力ctx.auth用于已验证身份。MCP 端点路径用basePath外部可见公共源用MCP_URL——不要从 localhost 假设重建公共 URL。迁移检查清单在源码、测试、示例与项目文档中搜索上述退役标识符对照已安装包确认公共导入与注册签名先跑类型生成与类型检查再解读下游错误用真实客户端逐一演练每个工具、资源模板与提示词渲染每个迁移后的 View测试 pending/error/ready、交互、资源与 CSP 行为相关边界变化时通过受支持客户端测试认证、通知与 elicitation包导出或依赖变化时打包并从干净消费者导入验证。验证清单提交前必做验证原则先跑能证明所需行为的最小检查涉及生成类型、认证、Views、包边界或并发时再扩大范围。静态检查npx mcp-use typecheck npm run typecheck npm run build不要假设每个项目都定义了两个 typecheck 命令。mcp-use build负责打包与转译不能替代类型检查。新引入的类型、lint、包边界、生成注册表失败都应在交接前解决。服务器与能力检查启动真实开发服务器经公共 MCP 端点连接并驱动被改能力npm run dev npx mcp-use client connect dev http://localhost:3000/mcp npx mcp-use client dev tools list npx mcp-use client dev tools call lookup-inventory skuitem-1工具测试合法输入、schema 拒绝、预期失败与匹配的structuredContent资源读取静态与模板 URI 并演练补全提示词检查精确生成的消息与建议涉及授权与取消路径时一并演练。View 检查在 Inspector 中通过绑定工具渲染每个受影响的 View验证pending/ready/error 渲染View 到工具调用与宿主动作模型可见状态与临时 UI 状态的区别主题、尺寸、支持展示模式与可访问性公共资源、外部请求、CORS、运行时错误与 CSP。用截图命令而非tools call标志捕获真实 Viewnpx mcp-use screenshot --server dev --tool show-product iditem-1高级与打包检查Skills over MCP验证目录、获取 Skill、读取支持文件并跑严格生产构建通知保持监听器活跃确认非持久失效行为Elicitation测试 required/accept/decline/cancel、非法输入、回调重放与副作用顺序代理或 OpenAPI验证代表性生成能力与文档化的不支持边界导出/依赖/打包变化打包后在空的临时消费者中安装——工作区构建无法证明发布边界。最后不要仅为验证源码变更而部署。若用户未要求部署验证本地构建产物并如实说明未测试的外部边界。与仓库其他 Skill 的关系仓库skills/下还提供 mcp-builder专注服务器构建、chatgpt-app-builder 与 openapi-to-mcpOpenAPI 转 MCP等配套 Skill。mcp-apps-builder覆盖面最全——它同时涵盖 Server、Views、认证、Skills over MCP 与迁移验证是理解框架全貌的最佳入口其余 Skill 是面向特定场景的纵深补充。References 中多处注明以已安装包声明为准这正是整套 Skill 体系的统一方法论文档与示例只是向导类型声明才是最终裁判。参考与延伸阅读Skill 主文档skills/mcp-apps-builder/SKILL.md服务器参考references/server.mdViews 参考references/views.md认证参考references/auth.mdSkills over MCP 参考references/skills-over-mcp.md高级特性参考references/advanced-features.md迁移参考references/migration.md验证参考references/verification.md脚手架实现libraries/typescript/packages/create-mcp-use-app服务器源码libraries/typescript/packages/server/src客户端含 React hooks源码libraries/typescript/packages/client/src赞分享后端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点击查看免费下载相关推荐RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本 RedisInsight 是 Redis 官方出品的 GUI数据库客户端桌面应用后端前端数据可视化MCP Go SDK 实战指南使用官方 Go SDK 快速构建 MCP Server 与 ClientMCP Go SDK 实战指南使用官方 Go SDK 快速构建 MCP Server 与 Client 本篇技术指南围绕官方 Go SDKgithub.coMCP 服务AI Agent工具调用LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册 本文是 LightGBM 官方参数参考文档 docs/Parameters后端MCP 服务MCP ClientsAI Agent人工智能上一篇在 Kilo Code 中使用 TrustedRouter接入可证明路由与零数据留存 AI 网关下一篇Nautilus Trader 执行适配器测试规范基于 ExecTester 的订单生命周期与状态机验证矩阵创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考