Cloudflare Workers Skeleton (TypeScript)

Một skeleton đầy đủ để bạn bắt đầu nhanh với Cloudflare Workers: routes, utils, services, bindings (KV/D1/R2), Durable Objects, cron.

Yêu cầu

• Node.js >= 18
• Wrangler CLI: npm i -g wrangler

Cách dùng

npm i
npm run dev
# hoặc
npm run deploy

CI/CD (GitHub Actions)

• Workflow: .github/workflows/deploy.yml
• pull_request -> main: chạy CI (npm ci, npm test)
• push -> main: chạy CI rồi auto deploy Worker
• workflow_dispatch: cho phép manual deploy từ GitHub UI
• Cần set secrets:
  • CF_API_TOKEN
  • CF_ACCOUNT_ID

MCP (Streamable HTTP)

• Endpoint: POST /mcp
• Nếu gửi header Accept: text/event-stream sẽ trả về SSE.
• Tools hiện có: hello, api.

MCP Tools Skeleton

• Registry: src/mcp-tools/registry.ts
• Scaffold tool: npm run tool:scaffold <tool-name> "Description here"
• Tool file output: src/mcp-tools/<tool-name>.ts

Ví dụ scaffold:

npm run tool:scaffold ping "Return pong"

Ví dụ initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "client", "version": "0.1.0" }
  }
}

List tools:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Call tool:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "hello", "arguments": { "name": "Kilo" } }
}

OpenAI-compatible Embeddings API

• Endpoints:
  • GET /v1/models
  • POST /v1/embeddings
• Alias route cũng hỗ trợ: /openai/v1/models, /openai/v1/embeddings
• Nếu đặt OPENAI_API_KEY, request phải gửi Authorization: Bearer <key>.
• encoding_format hỗ trợ: float (mặc định) và base64.

Ví dụ gọi embedding:

curl -X POST http://127.0.0.1:8787/v1/embeddings \
  -H "content-type: application/json" \
  -H "authorization: Bearer <OPENAI_API_KEY>" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["xin chao", "cloudflare workers"]
  }'

Ví dụ với OpenAI SDK:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "http://127.0.0.1:8787/v1",
});

const res = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "hello from workers",
});

console.log(res.data[0].embedding.length);

Bật các tích hợp (KV/D1/R2/DO/AI)

• KV: wrangler kv namespace create KV → cập nhật wrangler.toml với id trả về.
• D1: wrangler d1 create mydb → thêm binding trong wrangler.toml. Tạo bảng/migration: wrangler d1 execute mydb --file schema.sql.
• R2: Tạo bucket trong Dashboard, rồi thêm binding với bucket_name.
• Durable Objects: bật mục [durable_objects] và binding COUNTER.
• Workers AI: bật block [ai] với binding = "AI" để dùng /v1/embeddings.
• Cron: bỏ comment khối triggers.crons với lịch CRON mong muốn.

Routes vào domain riêng

Bật routes trong wrangler.toml và đảm bảo zone nằm trong Cloudflare.

Cấu trúc thư mục

src/
  index.ts
  mcp-tools/
    registry.ts
    hello.ts
    api.ts
  routes/
    hello.ts
    api.ts
    openai.ts
    kv.ts
    d1.ts
    r2.ts
    counter.ts
  utils/
    response.ts
    cors.ts
  services/
    db.ts
    storage.ts
  types/
    env.d.ts
  do/
    Counter.ts
tools/
  scaffold-tool.mjs
  template/
    tool.ts

Ghi chú

• Nếu chưa bật binding nào (KV/D1/R2/DO), hãy giữ nguyên comment trong wrangler.toml để deploy không lỗi.
• compatibility_date nên cập nhật định kỳ để dùng API mới.