a8c75ce4a7
- .mcp.json: rybbit sunucusu, anahtar ${RYBBIT_API_KEY} ortam değişkeninden
- .claude/settings.json: rybbit yazma araçları deny listesinde
- .gitignore: .claude/settings.local.json (anahtar burada) commit'lenmez
- docs/ekip/RYBBIT-BAGLANTI.md + settings.local.example.json: kurulum
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
134 lines
6.9 KiB
Markdown
134 lines
6.9 KiB
Markdown
# 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.
|