AI导哈

MCP服务器模板

将任何REST API桥接到模型上下文协议（MCP）的模板，部署在Cloudflare Workers边缘网络上。

  • by PCWProps
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 PCWProps/mcp-server-template

使用说明

MCP Server Template

Bridge any REST API to the Model Context Protocol — deployed on the Cloudflare Workers Edge.

任务

此模板为您提供了公开所需的一切 任何REST API 作为一套 模型上下文协议（MCP） 工具、资源和提示--在 Cloudflare Workers边缘 零冷启动、亚毫秒级延迟和自动缩放。

在几分钟内将Claude Desktop、Cursor、Continue.dev或任何兼容MCP的AI客户端连接到您的API。

目录

建筑

sequenceDiagram
    participant Client as MCP Client<br/>(Claude / Cursor)
    participant Worker as Cloudflare Worker<br/>(Hono + MCP SDK)
    participant API as External REST API

    Client->>Worker: GET /mcp (Authorization: Bearer <key>)
    Worker-->>Client: SSE stream established (mcp-session-id header)

    Client->>Worker: POST /mcp (mcp-session-id header)
    Note over Worker: Routes to McpServer<br/>for this session

    Worker->>API: GET /search?q=... (Bearer token)
    API-->>Worker: JSON response

    Worker-->>Client: SSE: tool result (markdown)

关键设计决策：

  • 可流式HTTP传输 --使用MCP SDK WebStandardStreamableHTTPServerTransport 使用本机Cloudflare Workers Web Streams API
  • 每会话隔离 --每个 GET /mcp 创建一个独立 McpServer 例子
  • 身份验证中间件 --定时安全承载令牌检查保护所有MCP端点
  • 重试+超时 — ApiClient 自动处理429/5xx的指数回退

快速入门

先决条件

工具 版本
Node.js >=18.x
pnpm >=8.x
牧马人 >=3.x

1.克隆和安装

# Use this template (GitHub)
gh repo create my-mcp-server --template PCWProps/mcp-server-template --private
cd my-mcp-server

# Install dependencies
pnpm install

2.配置环境

# Copy the example vars file
cp .dev.vars.example .dev.vars

编辑 .dev.vars:

TARGET_API_BASE_URL=https://api.example.com
TARGET_API_KEY=your-api-key-here
MCP_AUTH_KEY=your-mcp-auth-key-here

生成安全的MCP_AUTH_KEY：

openssl rand -hex 32

3.启动开发服务器

pnpm dev
# Wrangler starts at http://localhost:8787

4.测试MCP连接

# Health check
curl http://localhost:8787/health

# Connect to MCP streamable HTTP endpoint (SSE stream)
curl -N \
  -H "Authorization: Bearer your-mcp-auth-key" \
  http://localhost:8787/mcp

5.连接MCP客户端

添加到您的 克劳德桌面版 claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-auth-key"
      }
    }
  }
}

项目结构

mcp-server-template/
├── src/
│   ├── index.ts              # Hono app + SSE/message routing
│   ├── mcp/server.ts         # McpServer factory
│   ├── tools/                # MCP tool implementations
│   ├── resources/            # MCP resource implementations
│   ├── prompts/              # MCP prompt templates
│   ├── api/client.ts         # Type-safe HTTP client with retry
│   ├── middleware/auth.ts    # Bearer token auth middleware
│   └── types/env.d.ts        # Cloudflare Worker env bindings
├── scripts/
│   └── ingest-openapi.ts     # OpenAPI → MCP tool generator
├── .github/                  # GitHub workflows, templates, policies
├── .devcontainer/            # VS Code Dev Container config
├── wrangler.toml             # Cloudflare Workers config
└── package.json

添加MCP功能

新刀具

// src/tools/my-tool.ts
import { z } from 'zod';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import type { ApiClient } from '../api/client.js';

export function registerMyTool(server: McpServer, client: ApiClient): void {
  server.tool(
    'my_tool',
    'Description for the AI',
    { query: z.string().describe('Search query') },
    async ({ query }) => {
      const result = await client.get('/endpoint', { q: query });
      return { content: [{ type: 'text', text: `Result: ${JSON.stringify(result)}` }] };
    },
  );
}

然后注册 src/tools/index.ts。参见 贡献.md 完整的演练。

获取API文档（OpenAPI脚本）

有OpenAPI 3.x规范吗？在几秒钟内自动生成工具骨架：

# Place your spec in the project root
cp /path/to/openapi.json ./openapi.json

# Run the ingestion script
pnpm ingest-openapi

# Review and customize generated files in src/tools/
# Then register them in src/tools/index.ts

脚本生成：

  • A. Zod模式 从OpenAPI参数
  • A打字 ApiClient调用 存根
  • Markdown格式的响应模板
  • 满的 JSDoc文件

配置

环境变量

变量 描述 必填
TARGET_API_BASE_URL 外部API的基本URL ✅
TARGET_API_KEY 外部API的API密钥 ✅
MCP_AUTH_KEY MCP客户端必须提供的密钥 ✅

设置生产秘密：

wrangler secret put TARGET_API_KEY
wrangler secret put MCP_AUTH_KEY

部署

部署到Cloudflare Workers

# One-command deploy
pnpm deploy

# Deploy to staging environment
pnpm deploy:staging

CI/CD（GitHub操作）

所包含的工作流自动化了：

  • 持续集成 --对每次推送/PR（节点18、20、22）进行皮棉、类型检查和测试
  • 部署 --每次推送时自动部署到Cloudflare main
  • 发布 --基于变更集的变更日志和GitHub发布

将这些秘密添加到您的GitHub存储库中：

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

路线图

  • [x] Cloudflare员工的SSE传输
  • [x] 承载令牌认证中间件
  • [x] 带重试/超时的类型安全的ApiClient
  • [x] OpenAPI摄取脚本
  • [x] 示例工具、资源和提示
  • []持久对象支持多实例会话状态
  • []OAuth 2.0/API密钥轮换支持
  • []限速中间件
  • []流媒体工具响应（分块SSE）
  • []通过KV缓存工具结果
  • []多租户支持（每个用户API密钥）
  • []牧马人AI（工人AI）集成示例
  • []指标和可观察性仪表板

赞助

如果此模板为您节省了时间，请考虑支持继续开发：

您的赞助资金：

  • 保持依赖关系最新
  • 编写教程和文档
  • 构建新的示例集成
  • 快速响应问题

贡献

欢迎投稿！请阅读 贡献指南 在提交PR之前。

许可证

麻省理工学院 © PCWProps

相关 MCP