# Rybbit MCP bağlantısı

Rybbit artık **projenin kendi ayarında** tanımlı; her oturumda/bilgisayarda yeniden
bağlanmaya gerek yok. Tek makineye özel parça API anahtarının kendisi — o da
commit'lenmeyen tek bir dosyada durur.

## Ne nerede

| Dosya | Ne yapar | Commit'lenir mi |
|---|---|---|
| `.mcp.json` | `rybbit` sunucusunu tanımlar (HTTP, `https://rybbit.kolaytercih.com/api/mcp`), anahtarı `${RYBBIT_API_KEY}` olarak okur | **Evet** |
| `.claude/settings.json` | Sunucuyu otomatik etkinleştirir (`enabledMcpjsonServers`) + 16 yazma aracını `deny` eder | **Evet** |
| `.claude/settings.local.json` | `RYBBIT_API_KEY` değerini tutar | **Hayır** (`.gitignore`'da) |

Sunucu, Rybbit kurulumunun **kendi içinde gelen** resmî MCP ucudur — ayrı bir npm
paketi kurulmaz, sürümü panelin sürümüyle her zaman aynıdır. Kimlik doğrulama
`Authorization: Bearer <anahtar>` başlığıyla; OAuth akışı gerekmez (OAuth'lu bağlantı
tam da makineye/oturuma bağlı kalan, istemediğimiz biçimdi).

## Durum: kurulu ve doğrulandı (22 Eylül 2026)

`claude-code-readonly` adlı kişisel anahtar oluşturuldu, **9 kaynakta yalnız read**
yetkisiyle: Analytics, Sessions, Events, Users, Goals, Funnels, Sites, Search Console,
Custom SQL. Hiçbirinde write yok; Organization, Session replay (kayıtlı ekran
kayıtları) ve Event ingestion hiç verilmedi.

Sonuç uçtan uca doğrulandı:

- `initialize` → 200, sunucu `rybbit` **v0.3.0**.
- `tools/list` → **21 araç, hepsi okuma**. Yazma araçları anahtarın kapsamı yüzünden
  **sunucu tarafında listeye hiç girmiyor** — yani `.claude/settings.json` içindeki
  `deny` listesi artık ikinci katman, tek savunma değil.
- `list_sites` → `Kolay Tercih` / `kolaytercih.com`, **site_id = 1**.
- `get_overview` (15–22 Eylül) → 151 oturum, 109 kullanıcı, 427 sayfa görüntüleme.

Anahtar `.claude/settings.local.json` içinde; değeri panodan doğrudan dosyaya
yazıldı, hiçbir rapora/loga düşmedi.

### Yeni bir bilgisayarda

`.claude/settings.local.json` git'e girmediği için yeni makineye **taşınmaz** — orada
o dosya hiç yoktur (ya da o makinenin kendi izin onaylarıyla dolu, içinde `env` bloğu
olmayan bir hâli vardır). Bu yüzden repoda boş bir şablon duruyor; yeni makinede:

```sh
cp .claude/settings.local.example.json .claude/settings.local.json
```

Sonra `RYBBIT_API_KEY` alanına değeri yapıştır. (Dosya zaten varsa üzerine yazma —
içine sadece `env` bloğunu ekle.) Değer olarak ya aynı anahtarı kullan ya da yenisini
üret: Rybbit → **Settings → Account →
Personal API Keys** → adı yaz → **Restrict permissions**'ı aç → yukarıdaki 9 kaynakta
yalnız *read* işaretle (write, read'i kapsadığı için bir tanesi bile salt-okuma
güvencesini bozar) → **Create** → anahtar bir kez gösterilir → dosyaya yapıştır →
Claude Code'u yeniden başlat.

Anahtar okunmazsa belirti: her çağrı `Unauthorized: send a Rybbit API key…` (401).
Çözüm sırası: (a) değer dosyada mı, (b) yeniden başlatıldı mı, (c) hâlâ olmuyorsa
aynı değişkeni kabuk ortamına da ver (`export RYBBIT_API_KEY=…`) — `.mcp.json`
genişletmesi kabuk ortamını da okur.

### Sonradan gerekirse

`list_segments` / `apply_segment` / `get_annotations` bu anahtarda **yok** (Dashboards
kaynağı verilmedi). İç trafiği kayıtlı bir segmentle filtrelemek istersek yeni bir
anahtar üretip Dashboards *read* eklemek gerekir.

## Site kimliği tuzağı

İki ayrı kimlik var, birbirinin yerine geçmez:

- **Sayısal site kimliği `1`** — MCP araçlarının ve istatistik API'sinin istediği (`siteId`).
- `RYBBIT_SITE_ID` env'indeki `f2cb…` — tarayıcıdaki script'in kullandığı genel kimlik.

## Kim erişebilir

`analitik` (asıl sahip), `guvenlik-uyum` (kişisel veri denetimi), `seo-geo`
(organik iniş sayfası kırılımı). `qa-muhendisi`, `veri-muhendisi`,
`yapay-zeka-muhendisi`, `yazilimci` ajanlarında araç `disallowedTools` ile kapatıldı;
`ceo`, `cto`, `urun-yoneticisi`, `marka`, `tasarimci`, `rehber-*` zaten dar bir
`tools` listesiyle çalıştığı için erişemez. Gerekçe: rakamı tek yerin üretmesi
(bkz. `PROTOKOL.md` md.4).

## Eski anahtar — silindi

21 Eylül 2026'da açılmış tam yetkili `claude` adlı kişisel anahtar **22 Eylül 2026'da
silindi** (Bilal'in kararı; canlı sitenin ona bağlı olmadığı teyit edildikten sonra).
Silme sonrası `claude-code-readonly` ile yapılan çağrı 200 döndü — bağlantı etkilenmedi.
Panelde artık yalnızca salt-okuma anahtarı var.

## İç trafik dışlaması (22 Eylül 2026, panelden kuruldu)

`analitik` ajanı 16–22 Eylül penceresinde oturumun 69'dan 147'ye çıktığını ölçtü ama
artışın ne kadarının gerçek ziyaretçi olduğu söylenemedi: gece vardiyası, QA ve
Bilal'in kendi gezinmesi aynı havuza düşüyordu. Panelde **Site Settings → Exclusions**
altına iki dışlama yazıldı:

| Alan | Değer | Ne yapar |
|---|---|---|
| IP Exclusions | `94.54.157.194` | Bilal'in ev/ofis çıkış IP'si — bu adresten gelen her şey sayılmaz |
| Query Param Exclusions | `rybbit=off` | Adresine `?rybbit=off` eklenen her sayfa sayılmaz |

İkisi de kaydedildi ve sayfa yenilendikten sonra yerinde durduğu görüldü.

**IP kalıcı değil.** Bu bir ev aboneliğinin dinamik adresi; modem yenilenince ya da
başka ağdan (mobil veri, kafe, VPN) girilince dışlama sessizce devre dışı kalır —
hata vermez, sadece o oturumlar tekrar sayılmaya başlar. Bu yüzden `rybbit=off`
ikinci savunma olarak duruyor: ağ ne olursa olsun, adresin sonuna eklendiğinde o
sayfa gösterimi yutulur. Kendi sitende gezerken alışkanlık hâline getirilmeli;
QA ajanına verilen test adreslerine de eklenmeli.

Rybbit'in tarayıcı tarafında **cihaz bazlı bir kapatma anahtarı yok** (resmî `script`
belgesinde `localStorage` opt-out'u geçmiyor; yalnız `data-skip-patterns`,
`data-mask-patterns`, `data-debounce` var). Dolayısıyla elimizdeki iki mekanizma
bunlar. Kalıcı çözüm istenirse `data-skip-patterns` ile bir yol deseni ayrılabilir.

## Bilinen arıza: `get_goals` MCP çağrısı hata veriyor

```
MCP error -32602: Output validation error: Invalid structured content for tool get_goals:
[{"code":"invalid_type","expected":"number","received":"string","path":["meta","total"], …}]
```

Sunucu `meta.total`'ı string döndürüyor, MCP şeması number bekliyor — Rybbit'in kendi
hatası, bizim anahtarla/ayarla ilgisi yok. **Bugün pratik etkisi yok:** panele
bakıldı, `/1/goals` "No goals found" diyor — tanımlı hedef sıfır (`get_funnels` de
boş dönüyordu, kayıtlı huni de yok). Yani MCP'nin okuyamadığı bir bilgi şu an mevcut
değil. Hedef tanımlandığı gün bu çağrı yine patlayacak.

Panel **v2.8.0**, üstte "v2.9.1 available" bandı çıkıyor. GitHub sürüm notlarında
(v2.9.0, 12 Eylül) bu hatanın düzeltildiğine dair bir satır **yok** — yükseltme
muhtemel çözüm ama garanti değil. Yükseltme VPS'te docker imajı çekmek demek;
ajan kendiliğinden yapmaz, Bilal karar verir.