# Gemini Spark MCP — GitHub & Vercel

MCP server yang bisa kamu deploy sendiri ke Vercel, lalu disambungkan ke **Gemini Spark**
(atau Claude, atau MCP client lain) sebagai *remote MCP server*. Begitu tersambung, agen
bisa: buat repo GitHub, push kode (satu commit untuk banyak file), deploy ke Vercel
(langsung dari file atau dari repo GitHub), atur environment variable, dan alur gabungan
"buat repo → push → deploy" dalam satu perintah.

Saat pengguna menambahkan URL server ini di Gemini Spark, akan muncul **layar izin
(consent) untuk akun GitHub dan Vercel** secara otomatis — persis seperti menyambungkan
connector lain. Setelah keduanya diizinkan, server siap dipakai.

## Isi proyek

```
app/api/mcp/route.ts              endpoint MCP utama (yang ditempel di Gemini Spark)
app/connect/                      halaman izin (consent) GitHub + Vercel
app/api/oauth/                    authorization server sederhana (register/authorize/token/finish)
app/.well-known/                  metadata OAuth (dibaca otomatis oleh MCP client)
lib/mcp-tools.ts                  daftar semua tool (github_*, vercel_*, deploy_project)
lib/github.ts, lib/vercel.ts      pemanggil REST API GitHub & Vercel
lib/kv.ts                         penyimpanan sesi (Upstash Redis)
```

## 1. Deploy ke Vercel

```bash
npm install -g vercel   # kalau belum ada
cd gemini-spark-mcp
vercel                  # ikuti prompt, deploy dulu draft-nya
```

Atau upload folder ini sebagai project baru lewat dashboard Vercel (New Project → drag &
drop folder ini, atau push dulu ke GitHub lalu Import).

## 2. Siapkan penyimpanan sesi (WAJIB)

Server ini butuh tempat menyimpan token OAuth antar-request (serverless function tidak
punya memori yang bertahan). Paling gampang: **Vercel Marketplace → Storage → Upstash →
Redis** (ada tier gratis), tinggal klik "Connect to Project" — env var
`UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` (atau `KV_REST_API_URL` /
`KV_REST_API_TOKEN`) otomatis terisi. Atau daftar manual di https://console.upstash.com.

## 3. Pilih mode untuk GitHub & Vercel

Server ini mendukung dua mode secara independen untuk tiap provider — campur boleh
(misal GitHub pakai OAuth asli, Vercel pakai token statis).

### Mode A — OAuth asli (sesuai yang diminta: layar izin akun muncul)

**GitHub:**
1. Buka https://github.com/settings/developers → **New OAuth App**
2. Homepage URL = domain Vercel-mu (mis. `https://gemini-spark-mcp.vercel.app`)
3. Authorization callback URL = `https://<domain-mu>/api/oauth/github/callback`
4. Salin **Client ID** & **Client Secret** → set sebagai `GITHUB_CLIENT_ID` /
   `GITHUB_CLIENT_SECRET` di Vercel Project Settings → Environment Variables.

**Vercel:**
1. Buka https://vercel.com/dashboard/integrations/console → **Create**
2. Redirect URL = `https://<domain-mu>/api/oauth/vercel/callback`
3. Catat **slug** integrasinya (terlihat di URL console), Client ID, dan Client Secret
4. Set `VERCEL_CLIENT_ID`, `VERCEL_CLIENT_SECRET`, `VERCEL_INTEGRATION_SLUG` di Vercel
   Project Settings.

### Mode B — Jalan pintas pribadi (tanpa layar izin, langsung pakai token)

Kalau server ini cuma buat kamu sendiri dan mau setup secepat mungkin:
- `GITHUB_TOKEN` — Personal Access Token dari GitHub Settings → Developer settings →
  Tokens (scope `repo`).
- `VERCEL_TOKEN` — dari https://vercel.com/account/tokens.
- `VERCEL_TEAM_ID` — isi kalau project-mu di bawah sebuah Team.

Kalau salah satu (atau keduanya) diisi, langkah "Hubungkan" untuk provider itu otomatis
dilewati di halaman `/connect` — dianggap sudah terhubung.

Set semua env var lewat `vercel env add <NAMA>` atau dashboard, lalu jangan lupa
`NEXT_PUBLIC_APP_URL` (lihat `.env.example`) — **harus persis** domain produksi karena
dipakai sebagai `redirect_uri` OAuth.

## 4. Deploy ulang setelah env var diisi

```bash
vercel --prod
```

## 5. Sambungkan ke Gemini Spark

Di Gemini Spark (atau Claude → Settings → Connectors → Add custom connector), masukkan:

```
https://<domain-mu>/api/mcp
```

Klik tersambung → server ini akan merespons dengan metadata OAuth → Gemini Spark
membuka halaman `/connect` di browser → tombol **Hubungkan GitHub**, lalu **Hubungkan
Vercel** (atau otomatis "Terhubung" kalau pakai Mode B) → tombol **Izinkan & lanjutkan**.
Setelah itu Gemini Spark mendapat token akses dan tool-tool di bawah langsung bisa dipakai.

## Daftar tool

| Tool | Fungsi |
|---|---|
| `github_whoami` | Info akun GitHub yang terhubung |
| `github_list_repos` | Daftar repo |
| `github_create_repo` | Buat repo baru |
| `github_delete_repo` | Hapus repo |
| `github_push_files` | Push banyak file dalam satu commit |
| `github_upsert_file` | Tambah/update satu file |
| `vercel_list_projects` | Daftar project Vercel |
| `vercel_list_deployments` | Daftar deployment |
| `vercel_get_deployment_status` | Cek status satu deployment |
| `vercel_deploy_files` | Deploy langsung dari kumpulan file |
| `vercel_deploy_from_github` | Deploy dari repo GitHub yang sudah ada |
| `vercel_set_env_vars` | Set environment variable project |
| `deploy_project` | **Alur gabungan**: buat repo → push file → deploy ke Vercel, satu panggilan |

## Catatan keamanan

Ini scaffold yang sudah jalan penuh (bukan mock), tapi beberapa hal masih sengaja
disederhanakan supaya mudah dipahami/dimodifikasi — kalau mau dipakai serius/lintas
banyak pengguna, pertimbangkan tambahan berikut sebelum go-live:
- Token sesi (`access_token` kita sendiri) saat ini tidak kedaluwarsa selama 30 hari dan
  tidak ada mekanisme refresh/revoke dari sisi pengguna — tambahkan halaman "disconnect"
  kalau perlu.
- Token GitHub/Vercel disimpan apa adanya di Upstash Redis (terenkripsi saat transit &
  saat disimpan oleh Upstash, tapi tidak dienkripsi tambahan oleh kode ini) — tambahkan
  enkripsi di lapisan aplikasi kalau datanya sensitif.
- `vercel_deploy_from_github` hanya berhasil kalau akun Vercel-mu sudah menautkan GitHub
  App-nya sendiri ke repo terkait; kalau belum, pakai `vercel_deploy_files` /
  `deploy_project` yang tidak butuh itu.