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

cloudflare-mcp

部署与运维

查看项目

更新于 10-17 08:15

技能介绍

用途

cloudflare-mcp 用于在 Cloudflare Workers 上开发、迁移、加固和测试远程 MCP 服务器。它的核心判断标准是：每个客户端说哪个协议时代，以及由哪个 handler 来服务。

  • 旧版时代：2025-11-25 及更早，以 initialize 握手开始。
  • 现代时代：2026-07-28，无握手，按请求携带 _meta。

默认情况下，无状态 createMcpHandler(factory) 在同一个路由上同时服务这两个时代（资料称已实测验证）。SDK v1 服务器只服务旧版时代，现代客户端会收到 400 Unsupported protocol version: 2026-07-28。只有当 2025 时代客户端需要服务端到客户端请求（推送式 elicitation、sampling、roots）时，才需要使用有会话的旧版 handler。

主要能力

  1. 版本核对：agents 对 MCP SDK peer 采用精确锁定，而 npm 上的 SDK latest 往往领先于该锁定。资料要求先执行 pnpm view agents@latest version 与 pnpm view agents@latest peerDependencies --json，再按锁定版本写入 package.json（agents 与各 @modelcontextprotocol/* 包写精确版本，不带 ^；zod 写范围如 ^4.2.0），随后 pnpm install 并用 pnpm peers check 确认无未满足 peer。
  2. 无状态处理器脚手架：提供 assets/stateless-server/ 目录，含 src/index.ts、src/server.ts、wrangler.jsonc、tsconfig.json、test/mcp.test.mjs 与探测脚本；需 nodejs_compat 兼容标志，因 agents/mcp/server 引入 node:async_hooks；不需要 Durable Object 绑定或 migrations 块。
  3. 迁移指引：对照表覆盖 McpAgent + DO 迁移、serveSSE、server.tool(、OAuthProvider 旧写法等陈旧模式；迁移时保留已应用的 migrations 条目并追加 deleted_classes。
  4. 鉴权：使用 @cloudflare/workers-oauth-provider 1.x，构造时 resourceMetadata.resource 必须是覆盖 apiRoute 的绝对 https URL；工具内用 getMcpAuthContext()?.props 读取身份；在 apiHandler 包装层用 insufficientScope(ctx.auth, [...]) 做作用域校验；资料建议优先 CIMD 而非 DCR。
  5. 测试验证：运行 pnpm test，并在 wrangler dev 与部署后的 URL 上各跑一次双时代探测，要求工具在 legacy、auto、固定 2026-07-28 三种模式下都成功调用。

使用方式（要点）

  • 从 agents/mcp/server 导入 createMcpHandler，不要从 agents/mcp 导入。
  • 从 @modelcontextprotocol/server 导入 McpServer；不要用 SDK v1 的 @modelcontextprotocol/sdk/server/mcp.js。
  • 传入工厂函数而非 server 实例；在模块作用域只创建一次 handler；默认导出 { fetch } 对象，不要直接导出 handler 函数。
  • 用 import { env } from "cloudflare:workers" 读取绑定。
  • 用 registerTool(name, { description, inputSchema: z.object({...}) }, cb) 注册工具；读取 SDK v2 的回调上下文，而非 v1 的 extra。
  • 公共服务器保留默认 legacy: "stateless"；自定义域名需设为 allowedHostnames。
  • 现代请求中的 elicitation 用 inputRequired(...)，并为 2025 时代客户端提供非 elicitation 的回退方案。

适用场景

在 Cloudflare Workers 上新建远程 MCP 服务、把旧 McpAgent/SSE/SDK v1 项目迁移到无状态处理器、为 MCP 服务接入 OAuth 与作用域、以及为兼容不同协议时代的客户端做联调验证。

限制与说明

资料中的版本号与上游结论是 2026-09-28 的快照；刷新流程见 references/refresh.md。分类推断为部署与运维（面向 Cloudflare Workers 的远程服务部署与运行）。