# TAP Insights MCP

Aplikasi penghubung akun TikTok ke Claude. Setelah tersambung, Claude bisa
membaca dan menganalisis data akunmu untuk pengembangan branding dan affiliate
keranjang kuning.

Tiga modul:

1. **Metrik branding** - statistik akun (follower, likes, jumlah video) dan metrik
   per video (views, like, komen, share, engagement rate). Sumber: TikTok Display API.
2. **Keranjang kuning** - GMV, jumlah order, estimasi komisi, produk terlaris,
   creator penyumbang terbesar. Sumber: TikTok Shop Affiliate API.
3. **Kompetitor & tren** - profil akun kompetitor + topik/hashtag yang sedang naik.

Aplikasi ini berbentuk **MCP server**: Claude tinggal disambungkan ke server ini,
lalu bisa memanggil tool-tool di atas lewat bahasa biasa
("bandingkan engagement akun branding minggu ini", "produk apa paling laris bulan ini").

---

## Penting dibaca dulu (jujur)

- Aplikasi sudah jadi dan **bisa langsung dicoba dalam MODE MOCK** (data contoh).
  Ini supaya tim bisa menguji alur kerja bareng Claude sebelum kredensial TikTok siap.
- Untuk **data ASLI**, ada syarat dari TikTok yang hanya bisa kamu/tim selesaikan:
  - Daftar app di TikTok Developers + **review app (±3-7 hari)**.
  - Kredensial TikTok Shop dari **Partner Center** (akun MCN TAP kamu).
  - **Setiap akun branding harus diotorisasi satu per satu** (login OAuth). Token
    otomatis di-refresh, tapi proses login awal tetap manual per akun.
- **Akun personal** dapat akses API jauh lebih sedikit dari **Business/Creator**.
  Ubah akun branding ke Business/Creator dulu sebelum otorisasi.

---

## 1. Coba sekarang (mode mock, tanpa kredensial)

```bash
cd tap-insights-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # biarkan TIKTOK_MOCK=1
python selftest.py          # cek semua modul mengembalikan data contoh
```

Kalau `selftest.py` jalan tanpa error, server siap. Lanjut sambungkan ke Claude.

---

## 2. Sambungkan ke Claude (Claude Desktop)

Buka file konfigurasi Claude Desktop:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Tambahkan (ganti `/path/lengkap/...` dengan path folder ini, dan pakai python dari `.venv`):

```json
{
  "mcpServers": {
    "tap-insights": {
      "command": "/path/lengkap/tap-insights-mcp/.venv/bin/python",
      "args": ["/path/lengkap/tap-insights-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop. Sekarang Claude punya tool: `status`, `branding_metrik_akun`,
`branding_metrik_video`, `shop_ringkasan`, `shop_produk_terlaris`,
`shop_creator_teratas`, `kompetitor_profil`, `tren_konten`, dll.

Coba tanya Claude: *"Panggil status"* lalu *"tampilkan metrik video akun alkahfi.official"*.

---

## 3. Aktifkan data ASLI

### 3a. Metrik branding (TikTok Display API)

1. Buka https://developers.tiktok.com -> buat app.
2. Aktifkan **Login Kit** dan **Display API**.
3. Tambahkan scope: `user.info.basic`, `user.info.profile`, `user.info.stats`, `video.list`.
4. Daftarkan **Redirect URI** persis: `http://localhost:8080/callback`.
5. Isi di `.env`: `TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET`, lalu set `TIKTOK_MOCK=0`.
6. Otorisasi tiap akun (jalankan ulang untuk tiap akun, login pakai akun berbeda):

   ```bash
   python authorize.py
   ```

   Tip: pakai profil browser terpisah per akun supaya sesi login tidak tercampur.

### 3b. Keranjang kuning (TikTok Shop Affiliate API)

1. Masuk **TikTok Shop Partner Center** (https://partner.tiktokshop.com) dengan akun MCN TAP.
2. Buat app affiliate, ambil `app_key`, `app_secret`, dan `access_token`.
3. Isi di `.env`: `TTS_APP_KEY`, `TTS_APP_SECRET`, `TTS_ACCESS_TOKEN`,
   `TTS_SHOP_CIPHER` (jika diperlukan), dan `TTS_BASE_URL` sesuai region.
4. **Samakan path endpoint** di `tiktok_shop.py` (konstanta `AFFILIATE_*`) dengan
   dokumen resmi Partner Center versi/region kamu. Algoritma signing sudah siap;
   yang perlu dipastikan hanya nama path & parameter.

### 3c. Kompetitor & tren

Isi `COMPETITOR_PROVIDER`, `COMPETITOR_API_KEY`, `COMPETITOR_BASE_URL` di `.env`
sesuai penyedia data yang dipakai (mis. Creator Search Insights API atau provider
berlisensi), lalu sesuaikan `_provider_get()` di `competitor.py`.

> Jangan scraping manual. Melanggar aturan TikTok dan berisiko akun diblokir.

---

## Struktur file

```
tap-insights-mcp/
├── server.py          # MCP server: daftar semua tool untuk Claude
├── config.py          # baca kredensial dari .env + deteksi mode mock
├── storage.py         # simpan token tiap akun (SQLite) + refresh
├── authorize.py       # otorisasi akun branding via OAuth (jalankan per akun)
├── tiktok_display.py  # modul metrik branding (Display API)
├── tiktok_shop.py     # modul keranjang kuning (Shop Affiliate API + signing)
├── competitor.py      # modul kompetitor & tren
├── mock_data.py       # data contoh untuk mode mock
├── selftest.py        # uji cepat semua modul tanpa Claude
├── requirements.txt
├── .env.example
└── .gitignore
```

---

## Keamanan

- **Jangan commit `.env`** dan file `*.db` ke Git (sudah masuk `.gitignore`).
- Token akun = akses ke akun TikTok. Simpan database di tempat aman, batasi
  siapa yang bisa akses server.
- Kalau pakai connector/MCP pihak ketiga di luar ini, ingat: memberi login TikTok
  ke pihak ketiga = memberi mereka akses. Pilih yang tepercaya.

---

## Status modul saat dijalankan

Panggil tool `status` dari Claude kapan saja untuk melihat tiap modul sedang
`LIVE` (pakai data asli) atau `MOCK` (data contoh).