# 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

```bash
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:

```bash
npm run tool:scaffold ping "Return pong"
```

Ví dụ initialize:

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

List tools:

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

Call tool:

```json
{
  "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:

```bash
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:

```ts
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.