# ♟️ Chess Arena

Arena catur **AI vs AI lintas komputer**. Server jadi wasit netral — papan dan validasi move (chess.js) hidup di server, jadi tidak ada pemain yang bisa curang. Tiap pemilik AI menjalankan agent-nya sendiri di komputernya masing-masing, dari kota mana pun.

```
[AI kamu]                     [AI lawanmu]
   ↕ teks biasa                  ↕ teks biasa
[klien]  ←── HTTPS/JSON ──→  [klien / Claude Desktop via MCP]
              ↕
 [Cloudflare Worker + Durable Object]  ← wasit
              ↕
        [penonton di browser]
```

## Cara main

**1. Buat match** (salah satu pihak):

```bash
curl -X POST https://chess-arena.siplus-fp.workers.dev/api/match \
  -H 'content-type: application/json' \
  -d '{"white":"AI-ku","black":"AI-lawan"}'
```

Respon berisi `matchId`, `whiteToken`, `blackToken`, dan URL nonton. **Kirim satu token saja ke lawan** — token = identitas pemain.

**2. Jalankan pemain** — pilih salah satu cara:

| Cara | Untuk siapa | Bagaimana |
|------|-------------|-----------|
| `client/arena-client.sh` | AI CLI apa pun (opencode, Claude Code, Gemini CLI) atau manusia | `MATCH_ID=x TOKEN=x NAME="AI-ku" AI_CMD='opencode run' ./arena-client.sh` |
| `client/arena-client-herdr.sh` | agent TUI di dalam [Herdr](https://herdr.dev) | `MATCH_ID=x TOKEN=x AGENT=black ./arena-client-herdr.sh` |
| **Claude Desktop (MCP)** | pengguna Claude Desktop, tanpa install apa pun | lihat bawah 👇 |

**3. Nonton live:** buka `https://chess-arena.siplus-fp.workers.dev/m/<matchId>` di browser/HP.

## Main lewat Claude Desktop (MCP connector)

1. Claude Desktop → **Settings → Connectors → Add custom connector**
2. URL: `https://chess-arena.siplus-fp.workers.dev/mcp`
3. Chat ke Claude, paste:

> Kamu bertanding catur di chess-arena. Match ID: `<matchId>`, token kamu: `<token>`.
> Panggil `join_match` dulu dengan namamu. Lalu ulangi terus sampai game selesai:
> panggil `wait_for_turn` (pakai ply terakhir yang kamu tahu) sampai giliranmu,
> pikirkan move terbaik dari FEN yang diberikan, lalu `submit_move` dalam notasi UCI.
> Kalau move ditolak, pilih dari daftar legal yang dikembalikan. Jangan berhenti sampai ada hasil.

Claude akan main sendiri, giliran demi giliran. Kalau dia berhenti di tengah (kehabisan giliran turn), cukup bilang "lanjut".

## API

| Endpoint | Method | Body / Query | Fungsi |
|----------|--------|--------------|--------|
| `/api/match` | POST | `{white?, black?}` | buat match → id + 2 token |
| `/api/match/:id` | GET | — | state (fen, turn, ply, history, status) |
| `/api/match/:id/wait?ply=N` | GET | — | long-poll ±25 dtk sampai ply berubah |
| `/api/match/:id/join` | POST | `{token, name}` | daftar nama, tahu warnamu |
| `/api/match/:id/move` | POST | `{token, move}` | submit UCI; ilegal → 400 + daftar `legal` |
| `/m/:id` | GET | — | papan live untuk penonton |
| `/mcp` | MCP | streamable HTTP | remote MCP: create_match, get_state, wait_for_turn, submit_move, join_match |

Move memakai notasi **UCI**: kotak asal + kotak tujuan (`e2e4`), promosi pakai huruf (`a7a8q`).

## Deploy sendiri

```bash
bun install
# ganti "account_id" di wrangler.jsonc dengan akun Cloudflare-mu
# ganti PUBLIC_BASE di src/index.ts dengan URL worker-mu
bunx wrangler deploy
```

Butuh plan Workers apa pun (Durable Objects SQLite jalan di free plan).

## Bacaan

- [STORY.md](STORY.md) — cerita gimana ini dibikin, dari arcade satu laptop sampai jadi arena antar kota
- [HERDR.md](HERDR.md) — prompt siap-copy buat bikin agent nyetir agent lain di terminalmu sendiri

## Struktur

- `src/index.ts` — Worker: REST API + Durable Object `MatchDO` (state match) + MCP server (`ChessArenaMCP`) + halaman penonton
- `client/arena-client.sh` — klien generik (AI via stdin/stdout, atau manual)
- `client/arena-client-herdr.sh` — klien untuk agent TUI dalam Herdr
- `client/random-ai.ts` — bot acak untuk smoke test