# Cloudflare Workers 上的 TypeScript MCP 服务器使用 TypeScript 构建生产就绪的模型上下文协议 (MCP) 服务器并将其部署在 Cloudflare Workers 上。该技能涵盖官方“@modelcontextprotocol/sdk”、HTTP 传输设置、身份验证模式、Cloudflare 服务集成和全面的错误预防。 ** ** ## 何时使用此技能在以下情况下使用此技能： * 构建 **MCP 服务器** 以向 LLM 公开 API、工具或数据 * 在 Cloudflare Workers 上部署**无服务器 MCP 端点** * 集成 **外部 API** 作为 MCP 工具（REST、GraphQL、数据库） * 为边缘部署创建**无状态 MCP 服务器** * 通过 MCP 协议公开 **Cloudflare 服务**（D1、KV、R2、Vectorize） * 使用 API 密钥、OAuth 或零信任实施**经过身份验证的 MCP 服务器** * 使用资源和提示构建**多工具 MCP 服务器** * 需要**生产就绪模板**来防止常见的 MCP 错误 **当**时不要使用此技能： * 构建 **Python MCP 服务器**（改为使用 FastMCP 技能） * 需要带有 WebSockets 的 **有状态代理**（使用 Cloudflare Agents SDK） * 想要 **长期运行的持久代理** 与 SQLite 存储（使用持久对象） * 构建**本地 CLI 工具**（使用 stdio 传输，而不是 HTTP） ** ** ## 核心概念 ### MCP 协议组件 **1\.工具** \- LLM 可以调用的函数 * 使用 Zod 定义的输入/输出模式 * 异步处理程序返回结构化内容 * 可以调用外部API、数据库或计算 **2\.资源** \- 静态或动态数据暴露 * 基于 URI 的寻址（例如 `config://app/settings`） * 模板支持参数（例如，`user://{userId}`） * 返回文本、JSON或二进制数据 **3\.提示** \- 预配置的提示模板 * 提供可重复使用的对话开头 * 可以包含占位符和动态内容 * 帮助标准化法学硕士互动 **4\.完成**（可选）- 参数自动完成 * 建议工具参数的有效值 * 改善开发者体验 ** ** ## 快速入门 ### 1\.基本 MCP 服务器模板使用“basic-mcp-server.ts”模板作为最小工作服务器： // 请参阅模板/basic-mcp-server.ts 从 '@modelcontextprotocol/sdk/server/mcp.js' 导入 { McpServer }；从 '@modelcontextprotocol/sdk/server/streamableHttp.js' 导入 { StreamableHTTPServerTransport }；从'hono'导入{Hono}；从 'zod' 导入 { z }；常量服务器 = 新 McpServer({ 名称：“我的 mcp 服务器”，版本：'1.0.0' }); // 注册一个简单的工具服务器.注册工具( '回声', { 描述：'回显输入文本'，输入模式： z.object({ text: z.string().describe('要回显的文本') }) }, 异步（{文本}）=>（{ 内容：[{类型：'文本'，文本}] }) ）； // HTTP 端点设置 const app = new Hono(); app.post('/mcp', 异步 (c) => { const 传输 = 新 StreamableHTTPServerTransport({ sessionIdGenerator：未定义，启用JsonResponse：true }); // 关键：在响应端关闭传输以防止内存泄漏 c.res.raw.on('close', () => Transport.close()); 等待服务器.connect(传输); 等待 Transport.handleRequest(c.req.raw, c.res.raw, 等待 c.req.json()); 返回 c.body(null); }); 导出默认应用程序； **安装依赖项：** npm install @modelcontextprotocol/sdk hono zod npm install -D @cloudflare/workers-types 牧马人打字稿 **部署：** 牧马人部署 ** ** ### 2\.工具服务器模板使用“tool-server.ts”公开多个工具（API 集成、计算）： // 示例：天气 API 工具服务器.注册工具( '获取天气', { 描述：“获取城市的当前天气”，输入模式： z.object({ city: z.string().describe('城市名称'), 单位： z.enum(['公制', '英制']).default('公制') }) }, 异步（{城市，单位}，env）=> { 常量响应 = 等待获取（ `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units}&appid=${env.WEATHER_API_KEY}` ）； const data =等待response.json(); 返回{ 内容：[{ 类型：'文本'， text: `${city} 的温度: ${data.main.temp}°${units === 'metric' ? 'C' : 'F'}` }] }; } ）； ** ** ### 3\.资源服务器模板使用“resource-server.ts”来公开数据：从'@modelcontextprotocol/sdk/types.js'导入{ResourceTemplate}； // 静态资源服务器.注册资源( '配置', 新的 ResourceTemplate('config://app', { 列表: 未定义 }), { 描述: '应用程序配置' }, 异步（uri）=>（{ 内容：[{ uri：uri.href， mimeType: 'application/json', 文本: JSON.stringify({ 版本: '1.0.0', 功能: ['工具1', '工具2'] }) }] }) ）； // 带参数的动态资源服务器.注册资源( '用户个人资料', new ResourceTemplate('user://{userId}', { 列表: 未定义 }), { description: '用户个人资料数据' }, 异步 (uri, { userId }, env) => { const user = wait env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(); 返回{ 内容：[{ uri：uri.href， mimeType: 'application/json', 文本：JSON.stringify（用户） }] }; } ）； ** ** ### 4\.经过身份验证的服务器模板使用 `authenticated-server.ts` 来保证生产安全：从'hono'导入{Hono}； const app = new Hono(); // API Key认证中间件 app.use('/mcp', async (c, next) => { const authHeader = c.req.header('授权'); if (!authHeader || !authHeader.startsWith('Bearer ')) { return c.json({ error: '未经授权' }, 401); } const apiKey = authHeader.replace('承载', ''); const isValid =等待c.env.MCP_API_KEYS.get(`key:${apiKey}`); 如果（！isValid）{ return c.json({ error: '无效的 API 密钥' }, 403); } 等待下一个（）； }); app.post('/mcp', 异步 (c) => { // MCP 服务器逻辑（用户已通过身份验证） // ... 传输设置和处理 }); ** ** ## 身份验证模式 ### 模式 1：API 密钥（大多数情况下推荐） **设置：** 1.创建KV命名空间：`wrangler kv命名空间创建MCP_API_KEYS` 2. 添加到`wrangler.jsonc`： { “kv_命名空间”：[ {“绑定”：“MCP_API_KEYS”，“id”：“YOUR_NAMESPACE_ID”} ] } **实施：** 异步函数 verifyApiKey(key: string, env: Env): Promise { conststoredKey=awaitenv.MCP_API_KEYS.get(`key:${key}`); 返回storedKey !== null; } **管理密钥：** # 添加密钥牧马人 kv key put --binding=MCP_API_KEYS "key:abc123" "true" # 撤销密钥牧马人 kv 密钥删除 --binding=MCP_API_KEYS "key:abc123" ### 模式 2：Cloudflare 零信任访问从 '@cloudflare/workers-jwt' 导入 { verifyJWT }； const jwt = c.req.header('Cf-Access-Jwt-Assertion'); 如果（！jwt）{ return c.json({ error: '访问被拒绝' }, 403); } const 负载 = 等待 verifyJWT(jwt, c.env.CF_ACCESS_TEAM_DOMAIN); // 用户通过 Cloudflare Access 进行身份验证 ### 模式 3：OAuth 2.0 有关完整的 OAuth 实现，请参阅“references/authentication-guide.md”。 ** ** ## Cloudflare 服务集成 ### D1 数据库工具示例服务器.注册工具( '查询数据库', { 描述: '在 D1 数据库上执行 SQL 查询', 输入模式： z.object({ 查询：z.string(), 参数： z.array(z.union([z.string(), z.number()])).可选() }) }, 异步（{查询，参数}，env）=> { const result = wait env.DB.prepare(query).bind(...(params || [])).all(); 返回{ 内容：[{ 类型：'文本'，文本： JSON.stringify(result.results, null, 2) }] }; } ）； **牧马人配置：** { “d1_数据库”：[ {“绑定”：“DB”，“数据库名称”：“my-db”，“数据库ID”：“...”} ] } ### KV存储工具示例服务器.注册工具( '获取缓存', { 描述: '通过键检索缓存值', inputSchema: z.object({ key: z.string() }) }, 异步 ({ key }, env) => { const value = wait env.CACHE.get(key); 返回{ 内容：[{类型：'文本'，文本：值|| '找不到钥匙'}] }; } ）； ### R2 对象存储工具示例服务器.注册工具( '上传文件', { 描述: '将文件上传到 R2 存储桶', 输入模式： z.object({ 键：z.string(), 内容：z.string(), contentType: z.string().可选() }) }, async ({ key, content, contentType }, env) => { 等待 env.BUCKET.put(key, 内容, { httpMetadata: { 内容类型: 内容类型 || '文本/纯文本'} }); 返回{ 内容: [{ type: 'text', text: `上传的文件: ${key}` }] }; } ）； ### 矢量化搜索工具示例服务器.注册工具( '语义搜索', { 描述：'搜索矢量数据库'，输入模式： z.object({ 查询：z.string(), topK: z.number().default(5) }) }, 异步 ({ 查询, topK }, env) => { const 嵌入=等待env.AI.run('@cf/baai/bge-base-en-v1.5', { 文本：查询 }); const 结果 = 等待 env.VECTORIZE.query(embedding.data[0], { 顶部K, 返回元数据：true }); 返回{ 内容：[{ 类型：'文本'，文本： JSON.stringify(results.matches, null, 2) }] }; } ）； ** ** ## 测试策略 ### 1\.使用 Vitest 进行单元测试从 'vitest' 导入 { 描述、它、期望 }；从 '@modelcontextprotocol/sdk/server/mcp.js' 导入 { McpServer }；从 'zod' 导入 { z }；描述('计算器工具', () => { it('应该将两个数字相加', async () => { const server = new McpServer({ 名称: '测试', 版本: '1.0.0' }); 服务器.注册工具( '添加', { 描述：“两个数字相加”，输入模式： z.object({ a: z.number(), b: z.number() }) }, 异步 ({ a, b }) => ({ 内容：[{类型：'文本'，文本：字符串（a + b）}] }) ）； // 测试工具执行 const result = wait server.callTool('add', { a: 5, b: 3 }); Expect(result.content[0].text).toBe('8'); }); }); **安装：** npm install -D vitest @cloudflare/vitest-pool-workers **运行：** npx 维泰斯特 ### 2\.使用 MCP Inspector 进行集成测试 # 本地运行服务器 npm 运行开发 # 在另一个终端中 npx @modelcontextprotocol/inspector # 连接到：http://localhost:8787/mcp ### 3\.使用 Claude Agent SDK 进行端到端测试有关全面的测试模式，请参阅“references/testing-guide.md”。 ** ** ## 已知问题预防此技能可防止官方 MCP SDK 和 Cloudflare 存储库中记录的 10 多个生产问题： ### 问题#1：导出语法问题（关键） **错误**：`“无法读取未定义的属性（读取'地图'）”` **来源**：honojs/hono#3955，honojs/vite-plugins#237 **为什么会发生**：Vite构建的导出格式不正确会导致神秘错误**预防**： // ❌ 错误 - 导致神秘的构建错误导出默认值 { fetch: app.fetch }; // ✅ 正确 - 直接导出导出默认应用程序； ### 问题#2：未封闭的运输连接 **错误**：内存泄漏，挂起连接 **来源**：SDK 维护者的最佳实践 **为什么会发生**：在请求端未关闭 StreamableHTTPServerTransport **预防**： app.post('/mcp', 异步 (c) => { const Transport = new StreamableHTTPServerTransport(/*...*/); // 关键：始终在响应结束时关闭 c.res.raw.on('close', () => Transport.close()); // ... 处理请求 }); ### 问题 #3：工具架构验证失败 **错误**：`ListTools 请求处理程序无法生成 inputSchema` **来源**：GitHub modelcontextprotocol/typescript-sdk#1028 **为什么会发生**：Zod 架构未正确转换为 JSON 架构 **预防**： // ✅ 正确 - SDK 自动处理 Zod 架构转换服务器.注册工具( '工具名称', { inputSchema: z.object({ a: z.number() }) }, 处理程序）； // 除非自定义验证，否则不需要手动 zodToJsonSchema() ### 问题 #4：工具参数未传递给处理程序 **错误**：处理程序接收“未定义”参数 **来源**：GitHub modelcontextprotocol/typescript-sdk#1026 **为什么会发生**：注册和调用之间的架构类型不匹配 **预防**： const schema = z.object({ a: z.number(), b: z.number() }); 输入类型 = z.infer<模式类型>; 服务器.注册工具( '添加', { 输入架构：架构 }，异步（参数：输入）=> { // args.a 和 args.b 正确输入并传递 return { 内容: [{ 类型: '文本', 文本: String(args.a + args.b) }] }; } ）； ### 问题 #5：CORS 配置错误 **错误**：浏览器客户端无法连接到 MCP 服务器 **来源**：常见生产问题 **为什么会发生**：缺少 HTTP 传输的 CORS 标头 **预防**：从'hono/cors'导入{cors}； app.use('/mcp', cors({ 来源：['http://localhost:3000', 'https://your-app.com'], 允许方法：['POST'，'选项']， allowedHeaders: ['内容类型', '授权'] })); ### 问题 #6：缺少速率限制 **错误**：API 滥用、DDoS 漏洞 **来源**：生产安全最佳实践 **为什么会发生**：MCP 端点没有速率限制 **预防**： app.post('/mcp', 异步 (c) => { const ip = c.req.header('CF-Connecting-IP'); constrateLimitKey = `ratelimit:${ip}`; const count = 等待 c.env.CACHE.get(rateLimitKey); if (count && parseInt(count) > 100) { return c.json({ error: '超出速率限制' }, 429); } 等待 c.env.CACHE.put( 速率限制密钥， String((parseInt(count || '0') + 1)), { 过期时间：60 } ）； // 继续... }); ### 问题 #7：TypeScript 编译内存问题 **错误**：`tsc`构建期间`内存不足**来源**：GitHub modelcontextprotocol/typescript-sdk#985 **为什么会发生**：MCP SDK中的大型依赖树**预防**： # 添加到package.json脚本 "build": "NODE_OPTIONS='--max-old-space-size=4096' tsc && vite 构建" ### 问题 #8：UriTemplate ReDoS 漏洞 **错误**：服务器因恶意 URI 模式而挂起 **来源**：GitHub modelcontextprotocol/typescript-sdk#965（安全） **为什么会发生**：URI 模板解析中的正则表达式拒绝服务 **预防**：更新到 SDK v1.20.2 或更高版本（包括修复） ### 问题#9：身份验证绕过 **错误**：未经身份验证访问 MCP 工具 **来源**：生产安全最佳实践 **为什么会发生**：缺少或未正确实施身份验证 **预防**：始终对生产服务器实施身份验证（请参阅身份验证模式部分） ### 问题#10：环境变量泄漏 **错误**：错误消息或日志中暴露的秘密 **来源**：Cloudflare Workers 安全最佳实践 **为什么会发生**：响应中记录或返回的环境变量 **预防**： // ❌ 错误 - 暴露秘密 console.log('Env:', JSON.stringify(env)); // ✅ 正确 - 从不记录 env 对象尝试{ // ... 使用 env.SECRET_KEY } 捕获（错误）{ // 不要在错误上下文中包含 env console.error('操作失败：', error.message); } ** ** ## 部署工作流程 ### 本地发展 # 安装依赖项 npm 安装 # 使用 Wrangler 在本地运行 npm 运行开发 # 或牧马人开发者 # 服务器位于：http://localhost:8787/mcp ### 生产部署 # 构建 npm 运行构建 # 部署到 Cloudflare Workers 牧马人部署 # 部署到特定环境牧马人部署 --env 生产 ### CI/CD 与 GitHub Actions 名称：部署MCP服务器于：推：分支：[主要] 职位：部署：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v4 - 使用：actions/setup-node@v4 与：节点版本：'20' - 运行：npm ci - 运行：npm 测试 - 名称：部署到 Cloudflare Workers 使用：cloudflare/wrangler-action@v3 与： apiToken：${{secrets.CLOUDFLARE_API_TOKEN}} 帐户 ID：${{ Secrets.CLOUDFLARE_ACCOUNT_ID }} ** ** ## 软件包版本（2025-10-28 验证） { “依赖项”：{ "@modelcontextprotocol/sdk": "^1.20.2", "@cloudflare/workers-types": "^4.20251011.0", "荣誉": "^4.10.1", "zod": "^3.23.8", “zod-to-json-schema”：“^3.24.1” }, “开发依赖项”：{ "@cloudflare/vitest-pool-workers": "^0.5.29", "维斯特": "^3.0.0", "牧马人": "^4.43.0", “打字稿”：“^5.7.0” } } ** ** ## 何时使用 Cloudflare Agents SDK 当您需要时，请使用 **Cloudflare Agents MCP**： * **有状态代理** 具有持久存储（SQLite 高达 1GB） * **WebSocket 支持** 用于实时双向通信 * **长时间运行的会话** 以及对话历史记录 * **带有持久对象警报的计划代理任务** * **全球分布** 具有自动状态复制功能当您需要时，请使用**此技能（独立 TypeScript MCP）**： * **无状态工具**和 API 集成 * **边缘部署** 具有最小的冷启动延迟 * **简单身份验证**（API 密钥、OAuth） * **按请求付费**（无耐用对象开销） * **最大可移植性**（适用于任何平台，而不仅仅是 Cloudflare）有关详细比较，请参阅“references/cloudflare-agents-vs-standalone.md”。 ** ** ## 使用捆绑资源 ### 模板（模板/）所有模板均已投入生产并在 Cloudflare Workers 上进行了测试： * `templates/basic-mcp-server.ts` \- 最小工作服务器（echo 工具示例） * `templates/tool-server.ts` \- 多种工具实现（API 集成、计算） * `templates/resource-server.ts` \- 仅资源服务器（静态和动态资源） * `templates/full-server.ts` \- 完整服务器（工具+资源+提示） * `templates/authenticated-server.ts` \- 具有 API 密钥身份验证的生产服务器 * `templates/wrangler.jsonc` \- 具有所有绑定的 Cloudflare Workers 配置 **Claude 何时应使用这些**：创建新的 MCP 服务器时，根据用例复制适当的模板（仅工具、仅资源、经过身份验证或全功能）。 ### 参考指南 (references/) 高级主题的综合文档： * `references/tool-patterns.md` \- 常用工具实现模式（API 包装器、数据库查询、计算、文件操作） * `references/authentication-guide.md` \- 所有身份验证方法的详细信息（API 密钥、OAuth 2.0、零信任、JWT） * `references/testing-guide.md` \- 单元测试、使用 MCP Inspector 进行集成测试、使用 Claude Agent SDK 进行 E2E 测试 * `references/deployment-guide.md` \-Wrangler 工作流程、环境管理、带有 GitHub Actions 的 CI/CD * `references/cloudflare-integration.md` \- 使用 D1、KV、R2、Vectorize、Workers AI、队列、持久对象 * `references/common-errors.md` \- 所有 10 多个错误以及详细的解决方案、根本原因和预防策略 * `references/cloudflare-agents-vs-standalone.md` \- 用于在独立 MCP 和 Cloudflare Agents SDK 之间进行选择的决策矩阵 **当 Claude 应该加载这些**：当开发人员需要高级实现细节、调试帮助或架构指导时。 ### 脚本（脚本/）用于初始化和测试 MCP 服务器的自动化脚本： * `scripts/init-mcp-server.sh` \- 使用依赖项、牧马人配置和模板选择初始化新的 MCP 服务器项目 * `scripts/test-mcp-connection.sh` \- 测试 MCP 服务器连接并验证工具/资源端点 **克劳德何时应使用这些**：设置新项目或调试连接问题时。 ** ** ## 官方文档 * **MCP 规范** : * **TypeScript SDK**： * **Cloudflare Workers** ： * **Hono 框架** : * **Context7 库 ID**：`/websites/modelcontextprotocol` （如果可用） **示例服务器**： * 官方示例： * Cloudflare MCP 服务器： ** ** ## 关键规则 ### 总是这样做 ✅ 在响应端关闭传输以防止内存泄漏 ✅ 使用直接导出语法（“导出默认应用程序”）而不是对象包装器 ✅ 对生产服务器实施身份验证 ✅ 添加速率限制以防止 API 滥用 ✅ 使用 Zod 架构进行类型安全的工具定义 ✅ 在部署到生产之前使用 MCP Inspector 进行测试 ✅ 更新到 SDK v1.20.2+ 以进行安全修复 ✅ 记录所有工具并提供清晰的描述 ✅ 优雅地处理错误并返回有意义的消息 ✅ 使用环境变量作为机密（永远不要硬编码） ### 永远不要这样做 ❌ 使用对象包装器导出（`export default { fetch: app.fetch }`） ❌ 忘记关闭 StreamableHTTPServerTransport ❌ 在生产中无需身份验证即可部署 ❌ 记录环境变量或机密 ❌ 使用 CommonJS 格式（必须使用 ES 模块） ❌ 跳过浏览器客户端的 CORS 配置 ❌ 硬编码 API 密钥或凭证 ❌ 返回原始错误对象（可能泄漏敏感数据） ❌ 不进行部署本地测试工具/资源 ❌ 使用具有已知漏洞的过时 SDK 版本 ** ** ## 完整设置清单使用此清单来验证您的 MCP 服务器设置： * SDK版本为1.20.2或更高版本 * 导出语法正确（直接导出，不是对象包装器） * 响应结束时传输关闭 * 实施身份验证（如果生产） * 配置速率限制（如果面向公众） * 设置 CORS 标头（如果是浏览器客户端） * 所有工具都有清晰的描述和Zod模式 * 环境变量用于秘密 * wrangler.jsonc 包括所有必要的绑定 * 使用“wrangler dev”进行本地测试成功 * MCP Inspector可以连接并列出工具 * 生产部署成功 * 所有工具/资源返回预期响应 ** ** ## 制作示例该技能基于以下模式： * **官方 MCP TypeScript SDK 示例** : * **Cloudflare MCP 服务器**： * **错误**：0（已阻止所有 10 多个已知问题） * **节省代币**：与手动实施相比，约 70% * **验证**：✅ 所有模板均在 Cloudflare Workers 上测试 ** ** **有问题吗？有问题吗？** 1. 检查 `references/common-errors.md` 进行故障排除 2. 验证“快速入门”部分中的所有步骤 3. 使用 MCP Inspector 进行测试：`npx @modelcontextprotocol/inspector` 4.查看官方文档： 5.确保SDK版本为1.20.2或更高版本 ** ** **最后更新**：2025-10-28 **SDK 版本**：@modelcontextprotocol/sdk@1.20.2 **维护者**：Claude 技能存储库

打字稿MCP

包含技能