Antarestar Live — MCP Server (buat Hermes)

MCP read-only yang ngasih Hermes (AI agent) akses ke data Antarestar Live Dashboard. Narik dari Google Sheet yang sama dengan dashboard, pakai mapping kolom yang identik — jadi angka yang dibaca Hermes = angka yang tampil di dashboard.

Tools yang tersedia

Tool	Fungsi
list_stores	Daftar store/akun (Shopee & TikTok)
list_hosts	Daftar host
overall_performance	GMV/order/CVR/AOV/views/live-hours per store per hari (+ total, + per platform). Filter: from, to, platform, store
host_performance	Leaderboard host + detail sesi. Filter: from, to, host
executive_summary	Ringkasan periode: total, kontribusi platform, top store, top host. Param: period (YYYY-MM) atau from/to

Semua tanggal format YYYY-MM-DD. Read-only — Hermes nggak bisa ngubah data.

---

1. Setup lokal & tes

npm install
npm run smoke      # tes lapisan data ke sheet live (harus keluar angka)
npm run typecheck  # cek TypeScript

Tes sebagai MCP stdio (buat Hermes lokal / MCP Inspector):

npx @modelcontextprotocol/inspector npx tsx src/stdio.ts

2. Deploy ke Vercel (remote HTTP — buat Hermes cloud)

npm i -g vercel      # kalau belum
vercel               # deploy (ikutin promptnya)
vercel --prod        # deploy production

Lalu di Vercel → Project → Settings → Environment Variables, set:

• MCP_API_KEY = kunci rahasia panjang (Hermes wajib kirim ini)
• (opsional) SHEET_ID kalau mau override spreadsheet

Endpoint MCP-nya:

https://<project>.vercel.app/api/mcp      (atau /mcp)

3. Sambungin Hermes

Hermes (klien MCP) connect via Streamable HTTP ke URL di atas, dengan header:

x-api-key: <MCP_API_KEY>

Contoh config MCP (format umum klien MCP):

{
  "mcpServers": {
    "antarestar-live": {
      "url": "https://<project>.vercel.app/api/mcp",
      "headers": { "x-api-key": "<MCP_API_KEY>" }
    }
  }
}

Cek cepat endpoint hidup (GET):

curl -H "x-api-key: <MCP_API_KEY>" https://<project>.vercel.app/api/mcp

---

Arsitektur

Hermes (AI) ──MCP/HTTP──► api/mcp.ts ──► src/tools.ts ──► src/sheet.ts ──CSV──► Google Sheet
                          (Vercel)        (5 tools)      (parse + calcO)        (RAW Shopee/Tiktok, Data)

• src/csv.ts — parser & konversi angka/tanggal (diport dari dashboard).
• src/sheet.ts — fetch + parse + agregasi (cache 60 detik per-instance).
• src/tools.ts — definisi 5 tool MCP.
• api/mcp.ts — endpoint Streamable HTTP + auth API key (Vercel).
• src/stdio.ts — mode lokal (stdio).

Catatan

• Read-only: nggak ada tool tulis. Aman.
• Data ikut sheet — begitu dashboard/importer nambah data, MCP otomatis ikut fresh (cache 60s).
• Mau nambah tool (mis. checkpoint_daily_live, daily_report_host)? Tinggal tambah di src/tools.ts + parser tab-nya di src/sheet.ts.