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

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)

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

npm run build
npm start

4. Test

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

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.