AI ajanları için MCP sunucusu
PinAppAI iteration döngünün tamamını Claude Code, Cursor veya MCP destekli her ajandan sür — kur, CR'ları çöz, kararları uygula, /changes/'i yeniden üret, kaldır — editöründen çıkmadan.
PinAppAI MCP sunucusu, projenize AI-native arayüzdür. Karar dökümlerini Claude Code’a yapıştırmak yerine ajanın /pinappai:apply-decisions (veya başka herhangi bir slash komutu) çalıştırır ve iteration döngünün tamamını uçtan uca yürütür — canlı durumu okur, kod düzenlemeleri önerir, bir sonraki yeniden-üretimin sınırını bilmesi için marker yazar ve commit’lemeden önce SORAR.
MCP sunucusu npm’de @pinappai/mcp olarak yayınlanmıştır ve ajanın yanında stdio sunucusu olarak çalışır.
Kurulum
İki komut — Claude Code, Cursor, Claude Desktop, Codex CLI, Continue dahil tüm AI client’lar için aynı:
npx @pinappai/mcp install # makinendeki her AI client config'ine MCP sunucu girişini yazar
npx @pinappai/mcp login # tarayıcıyı açar, makineye özel anahtarı üretir ve yerel olarak kaydederinstall makinendeki tüm AI client config’lerine MCP sunucu girişini yazar (~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml, ~/.continue/config.yaml, ~/Library/Application Support/Claude/claude_desktop_config.json). Bu adımda kimlik bilgisi yazılmaz.
login ise tarayıcı sign-in akışı çalıştırır: bir URL + kısa bir onay kodu yazdırır, tarayıcını açar, birden fazla workspace’in varsa seçtirir ve üretilen API anahtarını makinende yerel olarak kaydeder. MCP sunucusu bir sonraki başlangıçta bu anahtarı otomatik alır.
ppk_… API anahtarı widget’ın pk_* anahtarından ayrıdır — login’i onaylayan kullanıcının rolüne göre kapsamlandırılmış erişim verir.
Dört CLI subcommand:
| Komut | Amaç |
|---|---|
npx @pinappai/mcp install | MCP girişini her algılanan AI client config’ine yaz |
npx @pinappai/mcp login | Tarayıcı sign-in; makineye özel anahtarı üret + kaydet |
npx @pinappai/mcp logout | Yerel credentials dosyasını sil |
npx @pinappai/mcp uninstall | MCP girişini AI client config’lerinden kaldır |
Login + AI client restart’tan sonra herhangi bir slash komutuyla doğrula (/pinappai: yazınca menü açılmalı).
CI / headless kurulum
Tarayıcı tabanlı login interactive olmayan bağlamlara uygun değil. MCP’yi başlatan ortamda PINAPPAI_API_KEY=ppk_… env değişkenini ayarla — MCP sunucusu önce env’i, sonra credentials dosyasını okur. Anahtarı app.pinappai.com/api-keys’den üret; sonradan temiz revoke için makineye / pipeline’a göre adlandır.
Manuel kurulum
Tek bir client’ı elle bağlamak istersen — ya da belirli bir version’a pin’lemen gerekiyorsa — install’ın senin için yazdığı per-client config snippet’leri:
Claude Code
claude mcp add-json pinappai '{"type":"stdio","command":"npx","args":["-y","@pinappai/mcp"],"env":{"PINAPPAI_API_KEY":"ppk_..."}}'Cursor — ~/.cursor/mcp.json
{ "mcpServers": { "pinappai": { "command": "npx", "args": ["-y", "@pinappai/mcp"], "env": { "PINAPPAI_API_KEY": "ppk_..." } } } }Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{ "mcpServers": { "pinappai": { "command": "npx", "args": ["-y", "@pinappai/mcp"], "env": { "PINAPPAI_API_KEY": "ppk_..." } } } }Codex CLI — ~/.codex/config.toml
[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]
[mcp_servers.pinappai.env]
PINAPPAI_API_KEY = "ppk_..."Continue — ~/.continue/config.yaml
mcpServers:
- name: pinappai
command: npx
args: ["-y", "@pinappai/mcp"]
env:
PINAPPAI_API_KEY: ppk_...PINAPPAI_API_BASE opsiyoneldir; default değeri https://api.pinappai.com.
10 slash komutu
Slash komutlar MCP sunucusunun içinde gelir — ek kurulum yok. AI client’ında /pinappai: yaz, host menüyü gösterir. Tam liste:
| Komut | Amaç |
|---|---|
/pinappai:setup-project | Workspace + proje + widget snippet + reviewer’ları sıfırdan kur. İterasyon sınır marker’ını başlatır. |
/pinappai:fix-changes | Sıradaki değişiklik taleplerini triyaj et, kod düzeltmeleri öner, marker yaz, commit’lemeden önce SOR. |
/pinappai:apply-decisions | Onay kararlarını (geri al + değişiklik talepleri) tek seferde kaynak koda uygula — marker-aware. |
/pinappai:generate-changes-page | Son uygulanan batch’ten bu yana /changes/’i yeniden üret (marker tarafından kapsamlandırılır — sadece son apply’dan beri sürüklenmiş içerik). |
/pinappai:remove | Yayına çıkarken widget + /changes/ + yardımcıları temizle. .pinappai/’i tekrar kurulum için saklar. |
/pinappai:analyze | Mevcut CR yığını üzerinde sadece-okuma triyaj raporu — değişiklik yapılmaz. |
/pinappai:summarize | CR batch’inden PR açıklaması, changelog veya release notu üret. |
/pinappai:audit-review | Bir projenin denetim günlüğünü incele (Business katmanı; owner rolü). |
/pinappai:triage-and-resolve | CR’ları open → processing → done yaşam döngüsünden geçirmek için yardımcılar — editörden çıkmadan. |
/pinappai:auth-help | Bir tool 401 veya 403 dönerse API anahtarı / rol / kapsam sorunlarını tanıla. |
/tr/mcp/ sayfasında öne çıkan beşi — setup-project, fix-changes, apply-decisions, generate-changes-page, remove — iteration döngünün ana akışına eşleniyor. Diğer beşi daha az başvurduğun yardımcılar.
İteration döngüsü
Canlı sitende açık-uçlu Bir batch değişiklik için
geri bildirim istiyorsun açık onay istiyorsun
│ │
▼ ▼
Projeyi kur ve geri bildirim Değişikliklerini
widget'ını yerleştir kaynak kodunda yap
│ │
▼ │
Reviewer'lar canlı sitede │
sabitlenmiş geri bildirim bırakır │
(yorumlar, metin yeniden yazımları, │
ekran görüntüleri, ses notları) │
│ │
│ ┌────── (sonraki turlarda: reviewer'lar inceleme │
│ │ sayfasında da harekete geçer — her madde için │
│ │ Onayla / Reddet / Değişiklik İste — ve test │
│ │ sitesine yeni iğneler bırakabilir) ◄──────────────┐ │
│ │ │ │
▼ ▼ │ │
Dashboard'da triyaj edersin: │ │
ne aksiyonlanabilir, ne değil, │ │
hangileri zaten çözüldü │ │
│ │ │
▼ │ │
┌───────┴────────┐ │ │
▼ ▼ │ │
AI aksiyonlanabilir AI madde-bazlı │ │
geri bildirimi kararları uygular │ │
uygular (red için geri al, │ │
değişiklik istekleri için ince ayar) │ │
│ │ │ │
└───────┬────────┘ │ │
▼ │ │
AI inceleme sayfasını üretir / yeniden üretir ◄─────────────────────┼──┘
(her değişikliği önce / sonra olarak │
gösteren tek bir bağımsız sayfa, │
artı her madde için Onayla / Reddet / │
Değişiklik İste düğmeleri — kaynak │
düzenlemeleriyle aynı çalışma ağacına iner) │
│ │
▼ │
AI tam diff'i gösterir & │
nereye commit edileceğini sorar │
(yeni branch / mevcut branch / sadece │
stage / atla — asla otomatik commit │
veya force-push yapmaz) │
│ │
▼ │
İterasyon sınırı kaydedilir │
(bir sonraki inceleme sayfası │
yalnızca bu turdan beri sürüklenenleri gösterir) │
│ │
▼ │
Test URL'ine commit & deploy edersin │
(tek commit: kaynak değişiklikleri + │
yeni inceleme sayfası test'e birlikte │
gider; linki reviewer'larla paylaş) ────────────────────────────────┤
│ │
┌───────────┴───────────────────────┐ │
│ │ │
Her şey çözüldü mü? Daha geri bildirim │
(açık veya devam eden geliyor mu? │
madde kalmadı) └────────────────────────────┤
│ │
└──────────────────────────┐ │
┌──────────┴───────────┐ │
│ Devam eden proje mi? │ │
│ Widget'ı tut; yeni │ ────────────────────────┘
│ geri bildirim gelince│
│ tekrar döngüye gir │
└──────────────────────┘
│
Yeniden yazımı yayına mı çıkarıyorsun?
│
▼
Widget + inceleme sayfasını temizle
(proje config'in saklanır,
sonra tekrar kurarsan diye)
│
▼
Production'a yayına çık 🚀Üç şey dikkat çekiyor:
- Her tur, yenilenmiş bir inceleme sayfasıyla bir test URL’inde sonlanır. Reviewer’lar her zaman düzenlemelerin güncel haline bakar, asla eski bir snapshot’a değil — herkes onaylayana kadar tur tur geri bildirimlerini iyileştirebilirler.
- İnceleme sayfası yalnızca bu turdaki yeni içeriği gösterir. Bugüne kadar gönderdiğin her değişikliğin yeniden tartışılması değil — yalnızca son turdan beri sürüklenenleri içerir, böylece reviewer’lar dikkatlerini gerçekten değişen şeye verir.
- Döngüden çıkmanın iki yolu. Çoğu proje widget’ı yerinde tutar ve yeni geri bildirim geldikçe süresiz iterate eder. Tek seferlik yeniden yazım turları yayına çıkarken widget + inceleme sayfasını temizleyebilir — proje config’in her durumda saklanır, böylece sonra tekrar kurman aynı yerden devam eder.
.pinappai/ klasörü
Repo kökünde küçük bir klasör. Iteration döngüsü için load-bearing — commit’le, gitignore’a koyma.
| Dosya | Amaç |
|---|---|
.pinappai/last-applied.json | İterasyon sınır marker’ı. Her apply çalışmasının sonunda yazılan ISO zaman damgası. Bir sonraki /changes/ regen’i “git log —since=<bu zaman damgası>” şeklinde kapsamlandırır. |
.pinappai/context.json | Proje şekli önbelleği: tespit edilen stack (Astro / Next / Hugo / vb.), build / lint komutları, kaynak dizini, route konvansiyonu, lokalizasyon yapısı ve text_lives_in (pages-inline / component-props / i18n-files / content-files / mixed). Bir kez kaydedilir, sonra her prompt yeniden tespit yerine bunu okur. |
Her iki dosya da küçücüktür (birkaç yüz byte). Commit’lemek demek bir takım arkadaşının ilk MCP çalışmasının zaten projenin şeklini bildiği demek — makine başına ikinci tur “hangi stack’tesin?” sorusu yok.
.pinappai/ gitignore’lanmışsa veya çalışma ağacı salt-okunursa, prompt’lar bellek-içi tespite geri düşer — döngü hâlâ çalışır, sadece daha az verimli.
Landing-chooser — AI asla otomatik commit yapmaz
Kaynağa-uygulayan her slash komutu (setup-project, fix-changes, apply-decisions, remove) tam olarak bu blokla biter:
✅ <tek satırlık özet>
Etkilenen dosyalar: <.pinappai/last-applied.json dahil liste>
Bunu nasıl iniş yapmak istiyorsun? Birini seç:
(a) Yeni feature branch — önerilen ad: pinappai/<batch>-YYYY-MM-DD-HHMM
Mevcut HEAD'inden branch oluştururum, TÜM etkilenen dosyaları
commit'lerim, push da yaparım yapmam da — sen bilirsin.
(b) Mevcut branch'e commit — aynı commit, branch değişmez.
(c) Sadece stage et — diff'i önce inceleyebilesin diye commit etmem.
(d) Atla — git'e dokunma, sen halledersin.
Önerilen commit mesajı: <prefix>(<kapsam>): <özet>
Hangi seçeneği (a / b / c / d), commit'ten sonra remote'a push olup
olmayacağını ve commit mesajı düzenlemelerini söyle. Beklerim.Ajan orada durur, sen seçene kadar. Sözleşme bu — git add, git commit, git push hangi seçeneği seçtiğini söyleyene kadar yok. Branch koruma kuralları gözetilir; --no-verify asla kullanılmaz. “Sen bilirsin, yap gitsin” dersen, varsayılan (b) mevcut branch’e commit + push yok.
Ön-uçuş kontrolü de kapsanır: kaynağa-uygulayan her prompt düzenlemeden önce git status + git branch --show-current çalıştırır. Kirli çalışma ağacı → diff’i göstererek sorar, sessizce stash’lemez.
Sunucunun açtığı tool’lar
Read + write yüzeyleri arasında 37 tool. En sık dokunacağın 6 read tool şunlar:
| Tool | Ne döndürür |
|---|---|
list_projects | API anahtarının görebildiği tüm projeler |
list_change_requests | Son feedback satırları — iğneler, yorumlar, kararlar — duruma / türe / sayfaya göre filtreleme + cursor pagination |
get_change_request | Bir feedback satırının id’ye göre tam detayı: sayfa URL, seçici, before/after metni, eleştirmen, karar, ekran görüntüsü URL’i |
get_review_summary | Toplu sayılar — bekleyen vs karar verilen, approved/rejected/change-requested dağılımı, sayfa-başına döküm |
get_screenshot | Eklenen ekran görüntüsünün PNG byte’ları, ajana base64 olarak |
analyze_patterns | Kararlar arasında, eleştirmenlerin tutarlı şekilde reddettiği yazım kalıpları nelerdir? Örneklerle kümeler döndürür |
En yeni 5 tool (@pinappai/[email protected]’da eklendi) iterasyon-döngüsü primitif’lerini uçtan uca sürer:
| Tool | Ne yapar |
|---|---|
pinappai_open_iteration | Atomik — bu turda ele alınacak CR’lerin manifest’ini dondurur (açıkça cr_ids veya include_all_scheduled: true ile), reviewer rosterini dondurur, iterasyon satırını döner |
pinappai_mark_iteration_applied | AI ajanın değişiklikleri uyguladıktan sonra bu, manifest’teki her CR’yi scheduled → applied durumuna geçirir |
pinappai_acknowledge_change_request | CR başına accept (kapatır — terminal) veya reopen (scheduled’a geri döner, iterations_traversed artar); opsiyonel olarak kararı yönlendiren reviewer’ı atfet |
pinappai_get_iteration_coverage | Karara bağlanan item / manifest boyutu + reviewer başına sayılar + anlaşmazlık sayısı — “bu tur ne kadar tamamlandı?” özetleri için ideal |
pinappai_list_iterations | Geçmiş iterasyonların ve bundle özetlerinin sayfalı listesi — tüm review zaman çizelgesini bir bakışta göstermek için yararlı |
Geri kalan 26 tool yaşam döngüsünü kapsar (proje create/update/archive, workspace create/rename/delete, üye invite/rol/remove, reviewer invite/revoke, API-anahtar list/revoke/restore, audit log read, profil rename, GDPR Madde 15 export). Her yazma işlemi API-anahtar rolüne göre kapılıdır — editor CR güncelleyebilir ama üye davet edemez; admin kalıcı silme dışında her şeyi yapabilir (kalıcı silme tasarım gereği admin-UI-only kalır).
Auth modeli
API anahtarları proje başına kapsamlandırılmıştır, üretim sırasında bir rol atanır (viewer / editor / admin / owner). Rol, ajanın hangi tool’ları çağırabileceğini belirler: viewer anahtarı sadece read görür; admin anahtarı tam yaşam döngüsünü sürer.
Bir ajana farklı bir projeyi bağlamak için o projenin admin sayfasından yeni bir anahtar üret ve yeni bir sunucu adıyla claude mcp add-json’u çalıştır (örn. pinappai-staging). Birden fazla sunucu birlikte yaşayabilir; ajan doğal-dil bağlamına göre seçer.
Anahtarlar admin’den istenildiği zaman iptal edilebilir — o anahtardan gelen bir sonraki MCP çağrısı 401 döner. Ajan bunu “erişimimi kaybettim, lütfen yeni bir anahtar göster” olarak yorumlamalı.
Kaynak
Sunucu kaynağı ve changelog’u npm’de @pinappai/mcp adresinde. Hata raporları ve sorunlar projenin GitHub deposuna gider.