# mcp-gemini-worker

MCP server (Node.js/TypeScript) yang mengekspos tool `judge_document`,
`summarize_document`, dan `health_check`, dengan Gemini 3.1 Flash Lite sebagai
mesin di baliknya. Dirancang untuk dipanggil Claude (sebagai orchestrator)
lewat Custom Connector di claude.ai / Claude API.

Lihat `spec_mcp_server_gemini_flash_lite.md` untuk detail desain lengkap.

## 1. Setup

```bash
npm install
cp .env.example .env
```

Buka `.env` dan isi minimal 2 variabel wajib:

```
GEMINI_API_KEY=isi_dengan_api_key_gemini_anda
MCP_SERVER_API_KEY=isi_dengan_string_acak_panjang_buatan_anda_sendiri
```

`GEMINI_API_KEY` didapat dari Google AI Studio / Google Cloud Console.
`MCP_SERVER_API_KEY` bebas Anda buat sendiri (mis. `openssl rand -hex 32`) —
ini yang dipakai untuk otentikasi Bearer saat Claude memanggil server ini.

Server **tidak akan menyala** kalau salah satu dari dua variabel ini kosong
(lihat `src/config.ts` — fail-fast by design, supaya tidak diam-diam jalan
tanpa kredensial).

## 2. Jalankan lokal (development)

```bash
npm run dev
```

Server akan listen di `http://localhost:8787` (atau sesuai `PORT` di `.env`).
Endpoint MCP ada di `POST /mcp`, endpoint health check tanpa auth di `GET /health`.

## 3. Build & jalankan produksi

```bash
npm run build
npm start
```

## 4. Test

```bash
npm test
```

Ini menjalankan unit test untuk `verifyQuote` (pagar anti-halusinasi) dan
`truncateDocument`. Untuk regression test dengan dokumen nyata (lihat spec
§11 poin 3), tambahkan test terpisah yang memakai teks jurnal yang sudah
diverifikasi manual sebelumnya sebagai ground truth.

## 5. Deploy supaya bisa dipanggil Claude

Server ini **wajib reachable dari internet publik** (Anthropic connect dari
cloud-nya, bukan dari device Anda). Opsi hosting:
- Cloudflare Workers (autoscaling + OAuth bawaan, direkomendasikan di spec)
- Fly.io / Railway / VPS biasa dengan reverse proxy HTTPS

Setelah deploy, daftarkan sebagai Custom Connector:
1. claude.ai → Customize → Connectors → tombol "+" → **Add custom connector**
2. Masukkan URL: `https://domain-anda.com/mcp`
3. Kalau pakai Bearer auth sederhana (bukan OAuth penuh), sesuaikan dengan
   opsi autentikasi yang tersedia di UI Custom Connector saat itu — cek
   dokumentasi terbaru Anthropic karena UI ini bisa berubah.
4. Klik Connect.

## 6. Mengecek server hidup tanpa lewat Claude

```bash
curl -X POST http://localhost:8787/mcp \
  -H "Authorization: Bearer $MCP_SERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Kalau setup benar, respons berisi daftar 3 tool: `judge_document`,
`summarize_document`, `health_check`.

## Catatan penting

- Versi `@modelcontextprotocol/sdk` berkembang cepat — cek API `McpServer` /
  `StreamableHTTPServerTransport` terkini di dokumentasi resmi sebelum deploy,
  karena signature method bisa berubah antar versi major.
- `MAX_DOCUMENT_CHARS`, `MAX_CONCURRENT_GEMINI_CALLS`, dan `DAILY_TOKEN_BUDGET`
  di `.env` adalah kontrol biaya — sesuaikan dengan volume nyata Anda, jangan
  dibiarkan default kalau traffic sudah signifikan.