AI ajanları için MCP sunucusu

PinAppAI MCP sunucusu, projene AI-native arayüzdür. Karar dökümlerini editörüne yapıştırmak yerine ajanın apply workflow’unu çalıştırır ve iteration döngüsü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ınlanır ve ajanın yanında bir stdio sunucusu olarak çalışır. Kurulum gerektirmeyen, barındırılan bir HTTP endpoint’i olarak da erişilebilir.

Bağlanmanın iki yolu

Yol	Ne gerekir	En uygun
Barındırılan bağlayıcı	Bir URL, sonra tarayıcından giriş yap (veya bir API anahtarı yapıştır)	HTTP üzerinden MCP konuşan her client, sıfır kurulum
npm paketi	İki komut: npx @pinappai/mcp install, sonra login	CI/headless kurulumlar, belirli bir sürüme pin’leme, offline çalışma

İkisi de aynı sunucuya bağlanır: aynı 38 tool, aynı 10 workflow. Hiçbiri daraltılmış bir yüzey değil.

Üç yüzey ve kimin kullandığı

Karıştırılması kolay olduğu için baştan netleştirelim:

Yüzey	Kim kullanır	Örnek
10 workflow	Sen çalıştırırsın	apply workflow’u. Nasıl çalıştırdığın client’ına bağlı, bkz. Workflow nasıl çalıştırılır.
38 tool	Ajanın protokol üzerinden çağırır	list_projects. Bunları asla yazmazsın.
6 CLI komutu	Sen, terminalde	npx @pinappai/mcp login

Kaçınılması gereken tek hata: workflow bir shell komutu değildir. Terminale pinappai-mcp apply yazmak çalışmaz. Workflow’lar AI client’ının içinde çalıştırılır.

Barındırılan bağlayıcı

MCP’yi HTTP üzerinden konuşan client’lar için, npx @pinappai/mcp’yi yerelde çalıştırmak yerine doğrudan barındırılan bir endpoint’e bağlanabilirsin.

Endpoint: https://mcp.pinappai.com/mcp (Streamable HTTP).

Kimlik doğrulamanın iki yolu var:

• Tarayıcıdan giriş, yapıştırılacak anahtar yok. Client’ın MCP tarayıcı girişini destekliyorsa (Claude Code destekliyor), endpoint’i hiçbir kimlik bilgisi olmadan ekle. Client’ın tarayıcını açar, erişimi onaylarsın ve ajanın çalışacağı workspace’i seçersin, sonra bağlanır. Elle kopyalanacak ya da saklanacak bir şey yok.
• API anahtarı. Statik bir header ile kimlik doğrulayan client’lar için bir bearer anahtarı geç: Authorization: Bearer ppk_.... Anahtarı app.pinappai.com/api-keys’den üret (bir ppk_ anahtarının neyi kapsadığı için aşağıdaki npm paketi bölümüne bak).

Her iki durumda da kimlik bilgisi olmayan bir client sunucuyu yine keşfedebilir: tool’ları listeler, workflow’ları okur. Kimlik doğrulama gerektiren kısım bir tool’u çalıştırmaktır.

Claude Code, tarayıcıdan giriş

claude mcp add --transport http pinappai https://mcp.pinappai.com/mcp

Komutta anahtar yok. Client’ın ilk kullanımda, erişimi onaylaman için tarayıcıyı açar.

Claude Code, API anahtarı

claude mcp add --transport http pinappai https://mcp.pinappai.com/mcp --header "Authorization: Bearer ppk_SENIN_ANAHTARIN"

JSON config’i olan her client (Cursor ve benzerleri)

{ "url": "https://mcp.pinappai.com/mcp", "headers": { "Authorization": "Bearer ppk_SENIN_ANAHTARIN" } }

npm paketi (npx @pinappai/mcp) tam desteklenmeye devam ediyor: CI/headless kurulumlar, belirli bir sürüme pin’leme veya offline çalışmak için doğru seçim. Barındırılan endpoint ikinci bir bağlanma yolu, yerine geçen değil.

npm paketi

İki komut (Claude Code, Codex CLI, Cursor, Claude Desktop, 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 kaydeder

install 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: workspace kapsamında bir makine kimliğidir ve yaptığı her çağrı, login’i onaylayan üyenin workspace rolüyle çalışır.

Altı CLI komutu:

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	Anahtarı sunucu tarafında iptal et ve yerel credentials dosyasını sil
npx @pinappai/mcp uninstall	MCP girişini AI client config’lerinden kaldır ve oturumu kapat (anahtarı iptal et + sil)
npx @pinappai/mcp --help	Bu sürümün açtığı tüm workflow ve tool’ları yazdır
npx @pinappai/mcp --version	Kurulu sürümü yazdır

--help canlı sunucuyu okur, yani her zaman elindeki sürümü anlatır. “Bu şey ne yapabiliyor?” sorusunun her client’ta ve her terminalde aynı çalışan tek cevabıdır.

Kurulumu doğrula

AI client’ını yeniden başlat, sonra ondan düz metinle iste:

pinappai projelerimi listele

Projelerinle cevap verirse sunucu bağlı ve kimlik doğrulaması tamam. Bu kontrol her client’ta çalışır, çünkü her client’ın uyguladığı tool’ları kullanır.

Doğrulamak için slash komutu yazma. Workflow’ların slash komutu olarak görünüp görünmediği tamamen client’ına bağlıdır; açılmayan bir slash komutu kurulumun çalışıp çalışmadığı hakkında hiçbir şey söylemez. Bkz. Workflow nasıl çalıştırılır.

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.

Workflow nasıl çalıştırılır

Workflow’lar MCP sunucusunun içinde gelir. Ek kurulum yok.

Nasıl çalıştırdığın client’ına bağlı. MCP spesifikasyonu bunu bilerek her client’a bırakır; yani her yerde çalışan tek bir sözdizimi yok. Kendi client’ını bul:

AI client’ın	apply workflow’unu çalıştır
Claude Code	/pinappai:apply yaz. /pinappai: yazınca menü açılır.
Codex	Şunu iste: “pinappai apply workflow’unu çalıştır”. Codex prosedürü çeker ve uygular.
Continue (VS Code / JetBrains, agent mode)	/apply yaz. Continue workflow’ları sunucu ön ekiyle listelemez.
Cursor	/ yaz ve menüden seç.
Claude Desktop	+ menüsü, sonra pinappai, sonra apply.
MCP bilen diğer her ajan	Codex gibi, düz metinle iste.

apply yerine aşağıdaki herhangi bir workflow adını koy.

Bilinmesi gereken iki not. Codex workflow’ları slash komutu olarak hiç göstermez: orada /pinappai: yazmak Unrecognized command cevabı verir. Düz metinle istemek desteklenen yoldur ve aynı prosedürü çalıştırır. Continue workflow’lara ön ek koymaz, yani bizimkiler /apply, /remove gibi gelir ve senin kendi prompt dosyalarınla aynı menüyü paylaşır. Continue ayrıca workflow’ları yalnızca editör eklentisinde ve agent mode’da gösterir, cn CLI’ında değil.

Client’ının neyi desteklediğinden emin değilsen düz metinle iste. O yol her yerde çalışır.

10 workflow

Workflow	Amaç
setup-project	Sıfırdan yeni proje kur: workspace, proje, widget snippet, reviewer’lar. Kurulumsuz review linkini teklif eder ve iterasyon sınır marker’ını başlatır.
embed-widget	Widget snippet’ini mevcut bir projenin sitesine göm ve marker’ı başlat: “AI için embed prompt’unu kopyala”nın MCP-native karşılığı.
apply	Döngünün motoru. Inbox’ı boşaltır: yeni uygulamalar, reddedilenler için geri almalar, değişiklik istenenler için yeni metinler, sonra turu tek atomik batch’te uygulandı olarak işaretler, yol üstünde /changes/’i yeniler.
generate-changes-page	Çok sayfalı bir toplu düzenleme için /changes/ inceleme sayfasını üret ve maddelerini kaydet: büyük bir rewrite’ın ilk sayfası için, ya da apply turu dışında sayfa istediğinde.
remove	Yayına çıkarken widget + /changes/ + yardımcıları temizle. .pinappai/’i tekrar kurulum için saklar; review linkini de kapatmayı teklif eder.
analyze	Mevcut CR yığını üzerinde sadece-okuma triyaj raporu (değişiklik yapılmaz).
summarize	Tamamlanan işten PR açıklaması, changelog veya müşteri e-postası üret, orijinal CR’lara atıfla.
audit-review	Workspace’in son denetim günlüğü etkinliğini özetle (Business katmanı; owner rolü).
auth-help	Bir tool 401 veya 403 dönerse API anahtarı / rol / kapsam sorunlarını tanıla.
reset-project	Bir projenin inceleme verisini sıfırla: sunucudaki CR’lar, kararlar, pin’ler, ekran görüntüleri; istersen repodaki /changes/ + marker da. Geri alınamaz; iki kez sorar.

/tr/mcp/ sayfasında öne çıkan beşi (setup-project, embed-widget, apply, generate-changes-page, remove) iteration döngüsünün ana akışına eşlenir: kur (ya da mevcut siteye göm), Inbox’ı uygula, inceleme sayfasını üret, yayına çıkarken kaldır. Diğer beşi daha az başvurduğun yardımcılar.

İteration döngüsü, tek bakışta

reviewer'lar canlı sitede değişiklik talebi pinler (#N atanır)
   │
   ▼
Inbox ──── apply workflow ────▶ InReview
  ▲                                 │
  │  Reject / Request change        ├── Approve → Closed
  └─────────────────────────────────┘

Her pin, dashboard Inbox’ına numaralı bir değişiklik talebi olarak düşer. Tek bir apply çalıştırması Inbox’ı boşaltır: ajan kaynağını düzenler, /changes/’i yeniden üretir ve turu kaydeder; uygulanan her CR InReview’a geçer. Reviewer kararları CR’ı ya kapatır ya da bir sonraki tur için Inbox’a geri gönderir: aynı CR, aynı #N. Ayrı bir triyaj töreni yoktur.

Tam durum modeli (alt durumlar, defer, reopen, first-action-wins) iterasyon döngüsü sayfasında.

.pinappai/ dizini

Repo kökünde küçük bir klasör. İterasyon döngüsü için taşıyıcıdır: commit’le, gitignore’a ekleme.

Dosya	Amaç
.pinappai/last-applied.json	İterasyon sınır marker’ı. Her apply çalıştırmasının sonunda yazılan ISO zaman damgası. Bir sonraki /changes/ regen “git log –since=” kapsamında çalışır.
.pinappai/context.json	Proje şekli önbelleği: algılanan stack (Astro / Next / Hugo / vb.), build / lint komutları, kaynak dizini, route düzeni, yerelleştirme şekli ve text_lives_in (pages-inline / component-props / i18n-files / content-files / mixed). Bir kez kaydedilir, sonra her prompt yeniden algılamak yerine bunu okur.

İki dosya da minicik (birkaç yüz bayt). Commit’lemek, bir takım arkadaşının ilk MCP çalıştırmasının projenin şeklini zaten bilmesi demek: makine başına ikinci bir “stack’in ne?” turu yok.

.pinappai/ gitignore’daysa ya da working tree salt-okunursa prompt’lar bellek-içi algılamaya düşer: döngü yine çalışır, sadece daha az verimli.

Landing-chooser: AI asla otomatik commit’lemez

Repona dokunan her workflow (setup-project, embed-widget, apply, remove, reset-project) şu blokla biter:

✅ <tek satır özet>
Etkilenen dosyalar: <.pinappai/last-applied.json dahil liste>

Bunu nasıl commit'leyelim? Birini seç:

  (a) Yeni feature branch — önerilen ad: pinappai/<batch>-YYYY-MM-DD-HHMM
      Mevcut HEAD'inden branch açarım, TÜM etkilenen dosyaları
      commit'lerim, push edip etmemek senin kararın.
  (b) Mevcut branch'e commit — aynı commit, branch değişikliği yok.
  (c) Sadece stage — commit'lemeden bırakırım, önce diff'i incelersin.
  (d) Atla — git'e dokunmam, sen halledersin.

Önerilen commit mesajı: <prefix>(<scope>): <özet>

Hangi seçenek (a / b / c / d), push edilsin mi ve commit mesajında
değişiklik var mı — söyle. Bekliyorum.

Ajan sen seçene kadar orada durur. Sözleşme bu: sen seçmeden git add yok, git commit yok, git push yok. Branch korumasına saygı duyulur; --no-verify asla kullanılmaz. “Sen karar ver, yap gitsin” dersen default (b): mevcut branch’e commit + push yok.

Ön kontrol de kapsanır: kaynağa dokunan her prompt düzenlemeden önce git status + git branch --show-current çalıştırır. Kirli working tree → sessizce stash’lemek yerine diff’i gösterip sorar.

Sunucunun sunduğu tool’lar

Okuma + yazma yüzeylerinde 38 tool. Ajanın bunları çağırır; sen asla yazmazsın. En sık dokunacağın 6 read tool:

Tool	Ne döner
list_projects	API anahtarının görebildiği tüm projeler
list_change_requests	Son geri bildirim satırları (pin’ler, yorumlar, kararlar) status / tür / sayfa filtreleri ve cursor sayfalamayla
get_change_request	Tek satırın tam detayı: sayfa URL’i, selector, önce/sonra metni, reviewer, karar, ekran görüntüsü URL’i
get_review_summary	Toplam sayılar: bekleyen vs karara bağlanan, approved/rejected/change-requested dağılımı, sayfa bazında döküm
get_screenshot	Ekli ekran görüntüsünün PNG baytları, ajan için base64
analyze_patterns	Kararlar genelinde reviewer’ların tutarlı reddettiği kalıplar (örnekli kümeler döner)

Workflow’ları taşıyan tek bir tool var:

Tool	Ne yapar
pinappai_get_workflow	Bir workflow’un tam prosedürünü metin olarak döndürür. Workflow’ları slash komutu olarak göstermeyen client’lar gerçek prosedürü böyle çalıştırır: ajan adından uydurmak yerine prosedürün kendisini çeker ve uygular. Codex’te “pinappai apply workflow’unu çalıştır” demeyi çalıştıran şey budur. Salt okunur.

Dört tool apply döngüsünü sürer (apply ve generate-changes-page workflow’larının perde arkasında çağırdıkları bunlar):

Tool	Ne yapar
pinappai_list_apply_inbox	Şu an Apply’a uygun her şey: yeni, reddedilen (geri alma gerek), değişiklik istenen (yeni metin gerek); ajanın kaynağı düzenlemesi için gereken alanlarla
pinappai_apply_change_requests	Atomik tur-sonu çağrısı: CR başına önce/sonra çiftlerini alır, tek iterasyon kaydeder, her CR’ı tek batch’te InReview’a taşır
pinappai_register_change_items	Yeni yazılmış bir /changes/ sayfasının maddelerini API’ye kaydeder: karar barları, sayfa-içi chip ve verdicts böyle canlanır
pinappai_reset_review_data	reset-project workflow’unun arkasındaki nükleer seçenek: projenin CR’larını, kararlarını, pin’lerini ve ekran görüntülerini siler

İki tool daha apply geçmişini açar: pinappai_list_iterations (geçmiş turlar, dondurulmuş manifest’leriyle) ve pinappai_get_iteration_coverage (bu tur ne kadar tamam: karara bağlanan vs bekleyen, reviewer bazında).

Kalan 25 tool tam admin yaşam döngüsünü kapsar. Bu tabloyla 38’in tamamı listelenmiş oluyor:

Alan	Tool’lar
Hesap & GDPR	get_me, update_me_profile, export_my_data (Md. 15 dışa aktarım)
API anahtarları	list_api_keys, get_api_key, revoke_api_key, restore_api_key
Workspace’ler	list_workspaces, get_workspace, create_workspace, update_workspace, delete_workspace
Projeler	get_project, create_project, update_project, archive_project, unarchive_project
Üyeler	list_members, invite_member, update_member_role, remove_member
Reviewer’lar	list_reviewers, invite_reviewer, revoke_reviewer
Denetim günlüğü	list_audit_events (Business planı)

Her yazma, çağıranın rolüne göre kapılıdır: editor apply döngüsünü sürebilir ve /changes/ maddesi kaydedebilir ama üye davet edemez; admin kalıcı-silme hariç her şeyi yapabilir (o tasarım gereği admin-UI’da kalır).

Auth modeli

ppk_ anahtarlar tek projeye değil workspace’e kapsamlıdır: bir anahtar workspace’teki her projeye erişir. Her anahtarı bir workspace üyesi üretir ve yapılan her çağrı o üyenin güncel rolüyle çalışır (viewer / editor / admin / owner): viewer anahtarı yalnız okur; admin anahtarı tüm yaşam döngüsünü sürer. Üyenin rolü değişirse anahtarın erişimi de değişir; üye çıkarılırsa anahtar çalışmayı durdurur.

Bir ajanı ikinci bir workspace’e bağlamak için orada bir anahtar üret ve sunucuyu farklı bir adla tekrar ekle (ör. pinappai-staging). Birden fazla sunucu bir arada yaşayabilir; ajan doğal-dil bağlamına göre seçer.

Anahtarlar admin’den her an revoke edilebilir. O anahtarın bir sonraki MCP çağrısı 401 döner. Ajan bunu “erişimi kaybettim, yeni anahtar gerekli” olarak ele almalı.

Kaynak

Sunucu kaynağı ve changelog npm’de @pinappai/mcp altında. Hata raporları ve issue’lar projenin GitHub reposuna.