chore(ekip): Rybbit MCP bağlantısı (salt okuma) ve ajan tanımları güncellemesi
- .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>
This commit is contained in:
bilalgursen
133
docs/ekip/RYBBIT-BAGLANTI.md
Normal file
133
docs/ekip/RYBBIT-BAGLANTI.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user