typescript-mcp

Cloudflare Workers 上的 TypeScript MCP 服务

使用 TypeScript 构建可用于生产环境的模型上下文协议（MCP）服务，并将其部署到 Cloudflare Workers。本技能涵盖官方 @modelcontextprotocol/sdk、HTTP 传输配置、身份验证模式、Cloudflare 服务集成以及全面的错误预防。

---

何时使用本技能

在以下情况下使用本技能：

• 构建 MCP 服务，向大模型公开 API、工具或数据
• 在 Cloudflare Workers 上部署 无服务器 MCP 端点
• 将 外部 API 集成为 MCP 工具（REST、GraphQL、数据库）
• 创建用于边缘部署的 无状态 MCP 服务
• 通过 MCP 协议公开 Cloudflare 服务（D1、KV、R2、Vectorize）
• 使用 API 密钥、OAuth 或 Zero Trust 实现 经过身份验证的 MCP 服务
• 构建包含资源和提示词的 多工具 MCP 服务
• 需要能避免常见 MCP 错误的 生产就绪模板

不要在以下情况下使用本技能：

• 构建 Python MCP 服务（请改用 FastMCP 技能）
• 需要通过 WebSockets 实现 有状态 Agent（请使用 Cloudflare Agents SDK）
• 希望构建使用 SQLite 存储的 长期运行、持久化 Agent（请使用 Durable Objects）
• 构建 本地命令行工具（请使用 stdio 传输，而非 HTTP）

---

安全安装

MCP 服务包会向大模型授予工具访问权限——若 SDK 遭到入侵，可能会暴露对整个系统的控制权。安装前请验证软件包。遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或使用 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的软件包
• 安装前审核 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

核心概念

MCP 协议组件：

1. 工具 - 大模型可调用的函数（Zod 模式、异步处理程序、外部 API）
2. 资源 - 数据公开（基于 URI：config://app、user://{userId}）
3. 提示词 - 预先配置的大模型交互模板
4. 补全 - 参数自动补全（可选）

---

快速开始

1. 安装依赖

bun add @modelcontextprotocol/sdk hono zod
bun add -d @cloudflare/workers-types wrangler typescript

2. 创建基础 MCP 服务

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { Hono } from 'hono';
import { z } from 'zod';

const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0' });

// Register a tool
server.registerTool(
  'echo',
  {
    description: 'Echoes back the input text',
    inputSchema: z.object({ text: z.string().describe('Text to echo') })
  },
  async ({ text }) => ({ content: [{ type: 'text', text }] })
);

// HTTP endpoint
const app = new Hono();

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  // CRITICAL: Close transport to prevent memory leaks
  c.res.raw.on('close', () => transport.close());

  await server.connect(transport);
  await transport.handleRequest(c.req.raw, c.res.raw, await c.req.json());
  return c.body(null);
});

export default app;

3. 部署

wrangler deploy

4. 使用生产模板

对于完整实现，请从 templates/ 目录复制：

• templates/basic-mcp-server.ts - 最简可运行服务
• templates/tool-server.ts - 多个工具（API 集成、计算）
• templates/resource-server.ts - 静态和动态资源
• templates/full-server.ts - 完整服务（工具 + 资源 + 提示词）
• templates/authenticated-server.ts - 通过 API 密钥身份验证实现生产级安全
• templates/wrangler.jsonc - Cloudflare Workers 配置

---

身份验证模式

快速示例 - API 密钥身份验证（最常见）：

app.use('/mcp', async (c, next) => {
  const authHeader = c.req.header('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }

  const apiKey = authHeader.replace('Bearer ', '');
  const isValid = await c.env.MCP_API_KEYS.get(`key:${apiKey}`);
  if (!isValid) return c.json({ error: 'Invalid API key' }, 403);

  await next();
});

完整身份验证指南：实现生产环境身份验证时，加载 references/authentication-guide.md。涵盖 5 种方法：API 密钥（推荐）、Cloudflare Zero Trust Access、OAuth 2.0、自定义 JWT 和 mTLS。包含安全最佳实践、测试策略和迁移指南。

---

Cloudflare 服务集成

快速示例 - D1 数据库工具：

server.registerTool(
  'query-database',
  {
    description: 'Executes SQL query on D1 database',
    inputSchema: z.object({
      query: z.string(),
      params: z.array(z.union([z.string(), z.number()])).optional()
    })
  },
  async ({ query, params }, env) => {
    const result = await env.DB.prepare(query).bind(...(params || [])).all();
    return { content: [{ type: 'text', text: JSON.stringify(result.results, null, 2) }] };
  }
);

支持的服务：D1（SQL 数据库）、KV（键值存储）、R2（对象存储）、Vectorize（向量数据库）、Workers AI、Queues、Analytics Engine。

完整集成指南：集成 Cloudflare 服务时，加载 references/cloudflare-integration.md。其中包含设置说明、MCP 工具示例、最佳实践和高级模式（RAG 系统、组合使用多个服务）。

---

测试策略

快速测试工作流：

1. 单元测试（Vitest）：独立测试工具逻辑
2. 集成测试（MCP Inspector）：使用 bunx @modelcontextprotocol/inspector 进行测试
3. 端到端测试：使用真实 MCP 客户端进行测试

# Local dev
npm run dev

# Test with Inspector
bunx @modelcontextprotocol/inspector

完整测试指南：编写测试时，加载 references/testing-guide.md。内容涵盖使用 Vitest 进行单元测试、使用 MCP Inspector 进行集成测试、端到端测试、身份验证测试、使用 Artillery 进行负载测试、模拟外部 API，以及 CI/CD 测试模式。

---

预防已知问题

此技能可预防 13 个已记录的问题。以下是最关键的 5 个问题：

问题 #1：导出语法问题（严重）

错误："Cannot read properties of undefined (reading 'map')" 来源：honojs/hono#3955 预防：

// ❌ WRONG                      // ✅ CORRECT
export default { fetch: app.fetch };    export default app;

问题 #2：传输连接未关闭

错误：内存泄漏、连接挂起 预防：

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPServerTransport({...});
  c.res.raw.on('close', () => transport.close()); // CRITICAL
  // ... handle request
});

问题 #3：工具架构验证失败

错误：ListTools request handler fails to generate inputSchema 来源：modelcontextprotocol/typescript-sdk#1028 预防：直接传递 Zod 架构——SDK 会自动处理转换

server.registerTool('tool', { inputSchema: z.object({...}) }, handler);

问题 #4：工具参数未传递给处理程序

错误：处理程序收到 undefined 参数 来源：modelcontextprotocol/typescript-sdk#1026 预防：使用 z.infer<typeof schema> 为处理程序参数提供类型安全

问题 #5：CORS 配置错误

错误：浏览器客户端无法连接 预防：

import { cors } from 'hono/cors';
app.use('/mcp', cors({ origin: ['http://localhost:3000'], allowMethods: ['POST', 'OPTIONS'] }));

完整错误目录：调试时，加载 references/common-errors.md。内容涵盖全部 13 个错误及其详细解决方案、GitHub 问题中的根本原因，以及调试清单。

---

部署工作流

快速部署：

# Local development
npm run dev  # Server at http://localhost:8787/mcp

# Production
npm run build
wrangler deploy

# Specific environment
wrangler deploy --env production

完整部署指南：设置生产环境时，加载 references/deployment-guide.md。内容涵盖环境设置（dev/staging/prod）、多环境、自定义域名、使用 GitHub Actions 的 CI/CD、数据库迁移、监控和日志、回滚策略、性能优化、健康检查、成本优化、安全清单和故障排除。

---

软件包版本（已于 2025-10-28 验证）

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.2",
    "@cloudflare/workers-types": "^4.20251011.0",
    "hono": "^4.10.1",
    "zod": "^4.1.12"
  },
  "devDependencies": {
    "@cloudflare/vitest-pool-workers": "^0.5.29",
    "vitest": "^3.0.0",
    "wrangler": "^4.43.0",
    "typescript": "^5.7.0"
  }
}

---

何时改用 Cloudflare Agents SDK

需要以下功能时，请使用 Cloudflare Agents MCP：

• 有状态 Agent，支持持久存储（SQLite，最高 1GB）
• WebSocket 支持，用于实时双向通信
• 长时间运行的会话，保留对话历史
• 定时 Agent 任务，使用 Durable Objects 闹钟
• 全球分发，自动复制状态

需要以下功能时，请使用此技能（独立 TypeScript MCP）：

• 无状态工具和 API 集成
• 边缘部署，冷启动延迟极低
• 简单身份验证（API 密钥、OAuth）
• 按请求付费（无 Durable Objects 开销）
• 最高可移植性（可在任何平台运行，不限于 Cloudflare）

详细比较请参阅 references/cloudflare-agents-vs-standalone.md。

---

何时加载参考资料

处理 TypeScript MCP 服务的特定方面时，请加载相应的参考文件：

authentication-guide.md

在以下情况下加载：

• 基于设置：为生产环境中的 MCP 服务实现身份验证
• 基于方式：在 API Key、OAuth 2.0、Zero Trust、JWT 或 mTLS 之间进行选择
• 基于安全：实现速率限制、API 密钥轮换、审计日志
• 基于测试：编写身份验证测试（单元、集成、端到端）
• 基于迁移：从一种身份验证方式升级到另一种

cloudflare-agents-vs-standalone.md

在以下情况下加载：

• 基于决策：在独立 MCP 和 Cloudflare Agents SDK 之间进行选择
• 基于架构：需要有状态 Agent 还是无状态工具
• 基于成本：比较低流量/高流量场景下的定价
• 基于功能：需要 WebSocket、持久存储或定时任务
• 基于迁移：从独立版本迁移到 Agents SDK，或反向迁移

cloudflare-integration.md

加载时机：

• 基于服务：集成 D1、KV、R2、Vectorize、Workers AI、Queues 或 Analytics Engine
• 基于模式：构建 RAG 系统或多服务应用
• 基于设置：配置 Cloudflare 服务的 wrangler.jsonc 绑定
• 基于示例：需要特定服务集成的可运行代码

common-errors.md

加载时机：

• 基于错误：遇到 13 种已记录错误中的任何一种
• 基于调试：服务无法正常工作，需要系统化调试检查清单
• 基于预防：希望在部署前预防所有已知问题
• 基于来源：需要特定错误的 GitHub 问题参考

deployment-guide.md

加载时机：

• 基于 CI/CD：设置用于自动部署的 GitHub Actions
• 基于环境：配置暂存环境/生产环境
• 基于迁移：在 CI/CD 中运行 D1 数据库迁移
• 基于监控：设置日志、分析和健康检查
• 基于优化：实现缓存、性能优化和成本降低

testing-guide.md

加载时机：

• 基于测试：编写单元测试、集成测试或端到端测试
• 基于工具：使用 Vitest、MCP Inspector 或 Artillery 进行测试
• 基于 CI/CD：在 GitHub Actions 中设置自动化测试
• 基于身份验证：测试身份验证中间件
• 基于负载：需要对 MCP 服务端点进行负载测试

tool-patterns.md

加载时机：

• 基于模式：实现外部 API 包装器、数据库查询、文件操作
• 基于示例：需要经过生产环境验证的工具实现示例
• 基于架构：构建多步骤操作、流式响应、缓存工具
• 基于错误：需要工具错误处理的最佳实践
• 基于响应：了解工具响应格式

---

使用捆绑资源

模板（templates/）：可用于生产环境的实现

• basic-mcp-server.ts - 最简可运行服务
• tool-server.ts - 多个工具（API 集成）
• resource-server.ts - 静态和动态资源
• full-server.ts - 完整服务（工具 + 资源 + 提示词）
• authenticated-server.ts - 生产环境安全配置
• wrangler.jsonc - Cloudflare Workers 配置

参考指南（references/）：完整文档（参见上方的“何时加载参考资料”部分）

• tool-patterns.md - 实现模式
• authentication-guide.md - 全部 5 种身份验证方法
• testing-guide.md - 单元、集成、端到端测试
• deployment-guide.md - CI/CD、环境、监控
• cloudflare-integration.md - D1、KV、R2、Vectorize、Workers AI
• common-errors.md - 全部 13 种错误 + 调试
• cloudflare-agents-vs-standalone.md - 决策矩阵

脚本（scripts/）：自动化工具

• init-mcp-server.sh - 初始化新项目
• test-mcp-connection.sh - 测试服务连接

---

官方文档

• MCP 规范：https://spec.modelcontextprotocol.io/
• TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
• Cloudflare Workers：https://developers.cloudflare.com/workers/
• Hono 框架：https://hono.dev/
• Context7 库 ID：/websites/modelcontextprotocol（如果可用）

示例服务：

• 官方示例：https://github.com/modelcontextprotocol/servers
• Cloudflare MCP 服务：https://github.com/cloudflare/mcp-server-cloudflare

---

关键规则

务必做到： ✅ 在响应结束时关闭传输 | ✅ 使用 export default app 语法 | ✅ 实现身份验证 | ✅ 添加速率限制 | ✅ 使用 Zod 模式 | ✅ 使用 MCP Inspector 测试 | ✅ 更新到 SDK v1.20.2+ | ✅ 记录所有工具 | ✅ 妥善处理错误 | ✅ 使用环境变量

切勿： ❌ 使用对象包装器导出 | ❌ 忘记关闭传输 | ❌ 未经身份验证就部署 | ❌ 记录环境变量 | ❌ 使用 CommonJS | ❌ 跳过 CORS 配置 | ❌ 硬编码凭据 | ❌ 返回原始错误 | ❌ 未经测试就部署 | ❌ 使用过时的 SDK

---

完整设置检查清单

使用此检查清单验证 MCP 服务设置：

• SDK 版本为 1.20.2 或更高版本
• 导出语法正确（直接导出，而非对象包装器）
• 在响应结束时关闭传输
• 已实现身份验证（用于生产环境时）
• 已配置速率限制（面向公众时）
• 已设置 CORS 标头（使用浏览器客户端时）
• 所有工具都有清晰的描述和 Zod 模式
• 使用环境变量存储机密
• wrangler.jsonc 包含所有必需的绑定
• 使用 wrangler dev 本地测试成功
• MCP Inspector 可以连接并列出工具
• 生产环境部署成功
• 所有工具/资源均返回预期响应

---

生产示例

此技能基于以下模式：

• 官方 MCP TypeScript SDK 示例：https://github.com/modelcontextprotocol/servers
• Cloudflare MCP 服务：https://github.com/cloudflare/mcp-server-cloudflare
• 错误：0（已预防所有 10 多个已知问题）
• Token 节省：与手动实现相比约节省 70%
• 验证：✅ 已在 Cloudflare Workers 上测试所有模板

---

有疑问？遇到问题？

1. 查看 references/common-errors.md 以排查问题
2. 核对快速入门部分中的所有步骤
3. 使用 MCP Inspector 测试：bunx @modelcontextprotocol/inspector
4. 查看官方文档：https://spec.modelcontextprotocol.io/
5. 确保 SDK 版本为 1.20.2 或更高版本

---

最后更新：2025-10-28 SDK 版本：@modelcontextprotocol/[email protected] 维护者：Claude Skills Repository