名称: typescript-mcp 描述: 使用@modelcontextprotocol/sdk在Cloudflare Workers上构建TypeScript MCP服务器。用于API集成、无状态工具、边缘部署，或遇到导出语法、模式验证、内存泄漏、CORS、认证错误。关键词: mcp, 模型上下文协议, typescript mcp, cloudflare workers mcp, mcp服务器, mcp工具, mcp资源, mcp sdk, @modelcontextprotocol/sdk, hono mcp, streamablehttpservertransport, mcp认证, mcp cloudflare, 边缘mcp服务器, 无服务器mcp, typescript mcp服务器, mcp api, llm工具, ai工具, cloudflare d1 mcp, cloudflare kv mcp, mcp测试, mcp部署, wrangler mcp, 导出语法错误, 模式验证错误, 内存泄漏mcp, cors mcp, 速率限制mcp 许可证: MIT 元数据: 版本: 2.0.0 最后更新: 2025-12-17 优化日期: 2025-12-17 令牌节省: ~55% sdk版本: “@modelcontextprotocol/sdk@1.22.0” 平台: cloudflare-workers 生产测试: true 错误预防: 13 允许工具: [Read, Write, Edit, Bash, Grep, Glob]

在Cloudflare Workers上构建TypeScript MCP服务器

使用TypeScript在Cloudflare Workers上构建生产就绪的模型上下文协议（MCP）服务器。本技能涵盖官方@modelcontextprotocol/sdk、HTTP传输设置、认证模式、Cloudflare服务集成和全面的错误预防。

何时使用此技能

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

构建MCP服务器，向LLM暴露API、工具或数据
在Cloudflare Workers上部署无服务器MCP端点
将外部API集成作为MCP工具（REST, GraphQL, 数据库）
创建无状态MCP服务器用于边缘部署
通过MCP协议暴露Cloudflare服务（D1, KV, R2, Vectorize）
实现认证MCP服务器，使用API密钥、OAuth或零信任
构建多工具MCP服务器，包含资源和提示
需要生产就绪模板以防止常见MCP错误

不要使用此技能当：

构建Python MCP服务器（使用FastMCP技能替代）
需要有状态代理与WebSockets（使用Cloudflare Agents SDK）
需要长时间运行的持久代理与SQLite存储（使用Durable Objects）
构建本地CLI工具（使用stdio传输，而非HTTP）

核心概念

MCP协议组件：

工具 - LLM可以调用的函数（Zod模式、异步处理器、外部API）
资源 - 数据暴露（基于URI：config://app, user://{userId}）
提示 - 预配置的LLM交互模板
补全 - 参数自动补全（可选）

快速开始

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' });

// 注册一个工具
server.registerTool(
  'echo',
  {
    description: '回显输入文本',
    inputSchema: z.object({ text: z.string().describe('要回显的文本') })
  },
  async ({ text }) => ({ content: [{ type: 'text', text }] })
);

// HTTP端点
const app = new Hono();

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

  // 关键：关闭传输以防止内存泄漏
  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: '未授权' }, 401);
  }

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

  await next();
});

完整认证指南：在实现生产认证时加载references/authentication-guide.md。涵盖5种方法：API密钥（推荐）、Cloudflare零信任访问、OAuth 2.0、JWT自定义和mTLS。包括安全最佳实践、测试策略和迁移指南。

Cloudflare服务集成

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

server.registerTool(
  'query-database',
  {
    description: '在D1数据库上执行SQL查询',
    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系统、组合服务）。

测试策略

快速测试工作流：

单元测试（Vitest）：隔离测试工具逻辑
集成测试（MCP Inspector）：使用bunx @modelcontextprotocol/inspector测试
端到端测试：使用真实MCP客户端测试

# 本地开发
npm run dev

# 使用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 预防：

// ❌ 错误                      // ✅ 正确
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()); // 关键
  // ... 处理请求
});

问题 #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问题的根本原因和调试清单。

部署工作流

快速部署：

# 本地开发
npm run dev  # 服务器在 http://localhost:8787/mcp

# 生产
npm run build
wrangler deploy

# 特定环境
wrangler deploy --env production

完整部署指南：在设置生产时加载references/deployment-guide.md。涵盖环境设置（开发/暂存/生产）、多环境、自定义域名、使用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"
  }
}