İçeriğe geç
Katalify Developers

Katalify MCP

Katalify MCP nedir?

Bölüm başlığı “Katalify MCP nedir?”

Katalify MCP, yapay zeka asistanlarının bir Katalify sitesini sizin adınıza yönetmesini sağlayan bir Model Context Protocol (MCP) sunucusudur. Claude Code, Claude Desktop, Cursor ve MCP destekleyen diğer istemciler bu sunucu üzerinden sayfaları okuyabilir, bölüm metinlerini taslak olarak güncelleyebilir, blog yazısı hazırlayabilir, görsel yükleyebilir, talepleri listeleyebilir, SEO ayarlarını okuyabilir ve A/B deneylerini okuyup yönetebilir.

Şu istemcilerle çalışır
  • Claude
  • ChatGPT
  • Claude Code, Cursor ve diğer MCP istemcileri

Claude ve ChatGPT ile bağlanın. claude.ai ve ChatGPT’de Katalify’ı bağlayıcı olarak eklersiniz; Studio hesabınızla giriş yapıp siteyi ve izinleri onaylamanız yeterlidir, anahtar kopyalamazsınız. Adım adım kurulum, Claude Code ve Cursor örnekleri ve sorun giderme için Claude ve ChatGPT’ye bağlama sayfasına bakın.

Her araç Public API v1’e tek bir çağrı yapar ve API anahtarınızın kapsamlarıyla sınırlıdır. İkinci bir yetki modeli yoktur: anahtarınızın yapamadığını asistan da yapamaz.

Önkoşullar

Bölüm başlığı “Önkoşullar”
  • Node.js 20 veya üstü
  • Bir Katalify API anahtarı (ks_live_...). Bkz. Hızlı başlangıç.
  • MCP destekleyen bir istemci (Claude Code, Claude Desktop, Cursor veya başka bir MCP istemcisi)

Kurulum

Bölüm başlığı “Kurulum”

Katalify MCP’yi iki şekilde kullanabilirsiniz: bilgisayarınızda çalışan yerel bir sunucu olarak (standart giriş/çıkış, stdio) veya kurulum gerektirmeyen uzak sunucu olarak (HTTP, bkz. Uzak bağlantı). İkisi aynı araçları, kaynakları ve prompt’ları sunar.

Paketi npm kayıt defteri olmadan, doğrudan bu sitedeki paket dosyasından kurun (sürüm 0.1.0):

Terminal window
npm install -g https://developers.katalify.com/mcp/katalify-mcp-0.1.0.tgz

Kurulumdan sonra katalify-mcp komutu kullanılabilir. --no seçeneği, npx’in paketi kayıt defterinden indirmesini engeller ve yalnızca bu kurulumu çalıştırır:

Terminal window
KATALIFY_API_KEY=ks_live_... npx --no katalify-mcp

Yalnızca bir proje için kurmak isterseniz -g olmadan proje klasöründe çalıştırın; bu durumda istemciyi de o klasörde başlatın.

Claude Code

Terminal window
claude mcp add katalify -e KATALIFY_API_KEY=ks_live_... -- npx --no katalify-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "katalify": {
      "command": "npx",
      "args": ["--no", "katalify-mcp"],
      "env": { "KATALIFY_API_KEY": "ks_live_..." }
    }
  }
}

Cursor (~/.cursor/mcp.json veya projede .cursor/mcp.json)

{
  "mcpServers": {
    "katalify": {
      "command": "npx",
      "args": ["--no", "katalify-mcp"],
      "env": { "KATALIFY_API_KEY": "ks_live_..." }
    }
  }
}

Windows’ta istemci npx komutunu bulamazsa "command": "cmd" ve "args": ["/c", "npx", "--no", "katalify-mcp"] kullanın.

Yapılandırma

Bölüm başlığı “Yapılandırma”

Aşağıdaki örneklerde /tam/yol/ yerine deponun bilgisayarınızdaki yolunu yazın (Windows’ta ör. C:/Users/ad/local-demos/mcp/dist/index.js).

Komut satırından ekleyin:

Terminal window
claude mcp add katalify -e KATALIFY_API_KEY=ks_live_... -- node /tam/yol/local-demos/mcp/dist/index.js

npm paketiyle:

Terminal window
claude mcp add katalify -e KATALIFY_API_KEY=ks_live_... -- npx -y @katalify/mcp

Proje düzeyinde paylaşılan bir yapılandırma için projenin kökündeki .mcp.json dosyasını kullanabilirsiniz. Anahtarı dosyaya yazmayın, ortam değişkeninden okutun:

{
  "mcpServers": {
    "katalify": {
      "command": "node",
      "args": ["/tam/yol/local-demos/mcp/dist/index.js"],
      "env": { "KATALIFY_API_KEY": "${KATALIFY_API_KEY}" }
    }
  }
}

Bağlantıyı denetlemek için Claude Code içinde /mcp yazın.

Uzak bağlantı

Bölüm başlığı “Uzak bağlantı”

Uzak sunucu, yerel sunucuyla aynı araçları, kaynakları ve prompt’ları HTTP üzerinden sunar: 0.2.0 yayınıyla birlikte 26 araç (deney araçları dahil); bugünkü üretim sürümü 19 araç sunar. Bilgisayarınıza Node.js veya paket kurmanız gerekmez.
Adres https://mcp.katalify.com/
Aynı uç nokta, Studio üzerinde https://studio.katalify.com/mcp
Taşıma Streamable HTTP (durumsuz: oturum kimliği yok, yanıtlar JSON)
Kimlik doğrulama Authorization: Bearer ks_live_... başlığı veya OAuth (claude.ai, ChatGPT; bkz. claude.ai ve ChatGPT’den bağlanma)

Adresi tarayıcıda açarsanız (anahtarsız GET) sunucunun adını, sürümünü ve bu sayfanın bağlantısını içeren kısa bir JSON belgesi görürsünüz. Araç çağrıları için anahtar zorunludur: anahtar eksik, hatalı, iptal edilmiş veya süresi dolmuşsa sunucu 401 ve ne yapmanız gerektiğini söyleyen bir JSON yanıtı döndürür.

Terminal window
claude mcp add --transport http katalify https://mcp.katalify.com/ --header "Authorization: Bearer ks_live_..."

Proje düzeyinde .mcp.json ile, anahtarı dosyaya yazmadan ortam değişkeninden okutarak:

{
  "mcpServers": {
    "katalify": {
      "type": "http",
      "url": "https://mcp.katalify.com/",
      "headers": { "Authorization": "Bearer ${KATALIFY_API_KEY}" }
    }
  }
}

Bağlantıyı denetlemek için Claude Code içinde /mcp yazın.

Uzak sunucu araçları aynı Studio içinde API v1 üzerinden çalıştırır; anahtarınızın kapsamları, sitesi ve hız sınırı yerel sunucudakiyle aynen geçerlidir. Hız sınırında yalnızca araçların yaptığı API çağrıları sayılır; bağlantı ve araç listesi gibi MCP istekleri sayılmaz.

claude.ai ve ChatGPT’den bağlanma

Bölüm başlığı “claude.ai ve ChatGPT’den bağlanma”

claude.ai ve ChatGPT’deki bağlayıcılar (connectors) başlık gönderemez; API anahtarı yerine OAuth ile bağlanırlar. Anahtar kopyalamanız gerekmez: Katalify Studio hesabınızla giriş yapar, bağlanacak siteyi ve izinleri seçip onaylarsınız.

  1. claude.ai’de Settings › Connectors ekranını açın ve Add custom connector seçin.
  2. Ad olarak Katalify, sunucu adresi olarak https://mcp.katalify.com/ yazıp ekleyin.
  3. Bağlayıcının yanındaki Connect düğmesine basın. Katalify Studio giriş ekranı açılır; giriş yapın.
  4. Onay ekranında siteyi ve izinleri seçip İzin ver’e basın. Pencere kapanır ve bağlayıcı claude.ai’de “bağlı” görünür.

Onay ekranı. Ekranda bağlanmak isteyen uygulamanın adı (“… şu siteyi yönetmek istiyor”), giriş yaptığınız hesap ve uygulamanın dönüş adresi görünür. Buradan:

  • Siteyi seçersiniz. Her bağlantı tek bir siteye bağlanır; listede yalnızca yönettiğiniz siteler görünür. İkinci bir site için bağlayıcıyı ikinci kez ekleyin.
  • İzinleri seçersiniz. Okuma her zaman açıktır; yazma, yayınlama, talepler ve medya yükleme isteğe bağlıdır. Kapsamlar API anahtarlarındakiyle aynıdır, bkz. Kimlik doğrulama. Asistan yalnızca seçtiğiniz izinlerle siteyi okuyabilir ve değiştirebilir.

Bağlayıcıları yalnızca site sahibi ve Katalify ekibi bağlayabilir; site editörü hesapları onay ekranında bir uyarı görür. Bağlantı 90 gün geçerlidir; süre dolunca bağlayıcıyı yeniden bağlarsınız.

İptal. Studio › Ayarlar › API anahtarları ekranında her bağlantı Bağlayıcı etiketiyle ve uygulamanın adıyla listelenir. İptal et dediğinizde uygulamanın erişimi hemen biter; bağlayıcıyı claude.ai veya ChatGPT’den kaldırmanız da yeterlidir.

Kimlik doğrulama

Bölüm başlığı “Kimlik doğrulama”

Sunucu, KATALIFY_API_KEY değerini her API isteğine Authorization: Bearer başlığı olarak ekler. Anahtarın kapsamları, asistanın hangi araçları başarıyla kullanabileceğini belirler:

Asistandan beklediğiniz Gereken kapsamlar
Yalnızca okuma ve inceleme read
Taslak metin hazırlama, önizleme read, write
Taslağı sizin onayınızla yayınlama read, write, publish
Görsel yükleme media (ve okumak için read)
Talepleri listeleme ve durum güncelleme leads
Deney sonuçlarını okuma; taslak deney; başlatma, duraklatma ve bitirme read; taslak için ayrıca write; başlatma, duraklatma ve bitirme için ayrıca publish. Bkz. MCP araçları: deneyler

Kapsamı eksik bir araç çağrıldığında sunucu insufficient_scope hatasını ve hangi kapsamın gerektiğini söyleyen bir ipucu döndürür. Anahtar geçersiz, iptal edilmiş veya süresi dolmuşsa ipucu, Studio’dan yeni bir anahtar oluşturup KATALIFY_API_KEY değerini güncellemenizi söyler.

Çoklu site

Bölüm başlığı “Çoklu site”

Site gerektiren her araç isteğe bağlı bir slug parametresi alır (yazı araçlarında siteSlug, çünkü orada slug yazının kendi adresidir). Site şu sırayla belirlenir:

  1. Araca verilen slug (veya siteSlug)
  2. KATALIFY_SITE ortam değişkeni (uzak sunucuda X-Katalify-Site başlığı)
  3. Anahtar tam olarak bir site görüyorsa o site (site anahtarlarında her zaman böyledir)

Platform anahtarı birden fazla site gördüğü için ya araçlara slug verin ya da KATALIFY_SITE (uzak sunucuda X-Katalify-Site) ayarlayın; aksi hâlde araç slug_required hatası döndürür. Asistan list_sites ile erişilebilen siteleri görebilir.

Kullanılabilir araçlar

Bölüm başlığı “Kullanılabilir araçlar”

Sunucu 26 araç sunar. Araç adları sabittir.

Araç Kapsam Etki Ne yapar
list_sites read okuma Anahtarın açabildiği siteleri listeler
get_site read okuma Bir sitenin kimliği, adı, durumu, sektörü, teması ve alan adları
list_pages read okuma Sitenin sayfaları (en güncel sürüm, taslak durumu dahil)
get_page read okuma Bir sayfa ve bölümleri (id, type, props, blocks); version: published ziyaretçilerin gördüğünü verir
update_section write taslak Bir bölümün props alanlarını birleştirir ve taslak kaydeder; önizleme bağlantısı döndürür
publish_page publish canlı Sayfanın en güncel sürümünü yayınlar
list_posts read okuma Blog yazıları, isteğe bağlı olarak taslak veya yayında olanlar
get_post read okuma Bir blog yazısı, Lexical gövdesiyle
create_post write (yayın için ayrıca publish) taslak Blog yazısı oluşturur, varsayılan taslak
update_post write (yayın için ayrıca publish) taslak Blog yazısını günceller; status: "published" gönderilmezse taslak
list_media read okuma Medya kütüphanesi (id, url, alt, boyut)
upload_media media kütüphaneye ekler Herkese açık bir https adresinden görsel yükler (en fazla 20 MB)
list_leads leads okuma (kişisel veri) Talepler; status ve source ile süzülebilir
update_lead_status leads yalnızca Studio’da görünür Talep durumunu yeni, arandi veya kapandi yapar
get_seo read okuma Site geneli SEO ayarları
update_seo write canlı SEO ayarlarını günceller, hemen geçerli olur
list_looks read okuma Canlı tema ve görünüm, sektör için sunulan paketler ve görünümler
set_look write canlı Canlı temanın görünümünü (stil) değiştirir
preview_url write okuma Siteyi taslaklarıyla gösteren bir saatlik imzalı bağlantı
list_experiments read okuma Sitenin A/B deneyleri, en yeni önce; status ile süzülebilir
get_experiment read okuma Bir deney: tür, durum, hedefler, varyantlar, zamanlama, kazanan
get_experiment_stats read okuma Deney sonuçları: ziyaretçi, dönüşüm, oran, güven aralığı, kazanma olasılığı, güven katmanı, yeterli veri
create_experiment write taslak page, content ya da look türünde taslak deney oluşturur
start_experiment publish canlı Deneyi başlatır; ziyaretçiler varyantlara bölüştürülür
pause_experiment publish canlı Deneyi duraklatır; herkes kontrol sürümünü görür
finish_experiment publish canlı Deneyi bitirir; kazanan verilirse canlı siteye uygulanır

Deney araçlarının ayrıntısı ve örnek istekler: MCP araçları: deneyler.

Araçlar istemcilere MCP ipuçlarıyla birlikte bildirilir: okuma araçları readOnlyHint, ziyaretçilerin hemen göreceği değişiklikleri yapan araçlar (publish_page, update_seo, set_look, update_lead_status, start_experiment, pause_experiment, finish_experiment) destructiveHint taşır. Pek çok istemci bu ipuçlarına göre çağrıdan önce onay ister.

Araç sonuçları

Bölüm başlığı “Araç sonuçları”

Bir araç başarılı olduğunda sonuç, API yanıtının data alanıdır. Listelerde ayrıca “Sayfa 1/3, toplam 57 kayıt.” gibi bir satır gelir. Sayfaya veya siteye yazan araçlar (update_section, publish_page, update_seo, set_look) sonuca bir önizleme bağlantısı ve kısa bir not ekler. Örneğin update_section sonrası not: “Taslak kaydedildi, yayınlamak için publish_page”.

Hatalar API’den geldiği gibi, HTTP durumu eklenerek iletilir: { "error": { "code", "message", "status" } }. 429 hatasında retryAfter (saniye) de bulunur. Ardından bir ipucu satırı gelir.

Kaynaklar ve prompt’lar

Bölüm başlığı “Kaynaklar ve prompt’lar”

Kaynaklar

Bölüm başlığı “Kaynaklar”
URI İçerik
katalify://sites Anahtarın açabildiği siteler (JSON)
katalify://sites/{slug}/pages Bir sitenin sayfaları, en güncel sürüm (JSON)

Hazır prompt’lar

Bölüm başlığı “Hazır prompt’lar”
Prompt Argümanlar Ne yapar
sayfa_metni_yenile slug, pageSlug, sector Sayfanın yalnızca metin alanlarını sektöre uygun biçimde yeniden yazdırır; görsel, bağlantı, telefon, adres ve düzen alanlarına dokunmaz, uydurma bilgi eklemez, değişiklikleri taslak kaydeder, önizleme ve eski/yeni metin listesini gösterir ve açık onay olmadan yayınlamaz.
seo_doldur slug Yalnızca boş SEO alanlarını sitenin içeriğinden doldurur; adres, koordinat, çalışma saatleri ve doğrulama kodlarını tahmin etmez; update_seo hemen geçerli olduğu için önce eski ve yeni değerleri gösterip onay ister.

Sunucu ayrıca istemciye kısa bir kullanım talimatı verir: önce oku, taslak yaz, önizleme bağlantısını göster, onay gelirse yayınla; SEO ve görünüm değişikliklerini önce göster; talepleri yalnızca gerektiği kadar göster.

Veri gizliliği

Bölüm başlığı “Veri gizliliği”

Sunucunun yaptıkları:

  • Anahtarı yalnızca KATALIFY_API_KEY ortam değişkeninden okur ve yalnızca KATALIFY_API_URL adresine Authorization başlığında gönderir.
  • Yönlendirmeleri izlemez: API bir yönlendirme döndürürse istek hata verir, anahtar başka bir adrese taşınmaz.
  • https dışındaki adresleri (yerel localhost hariç) reddeder.
  • İstekleri User-Agent: katalify-mcp/0.2.0 ile ve 60 saniyelik zaman aşımıyla gönderir.

Sunucunun yapmadıkları:

  • Anahtarı, araç argümanlarını veya araç sonuçlarını kaydetmez. Standart hata çıkışına yalnızca başlangıç satırını (API adresinin kökeniyle) ve başlatma hatalarını yazar.
  • API dışında hiçbir adrese istek göndermez.

API tarafında anahtar, özeti veya başlığı kaydedilmez. Beklenmeyen hatalarda yalnızca uç noktanın adı ve hata mesajı sunucu kaydına yazılır; anahtarın son kullanım zamanı en fazla 10 dakikada bir güncellenir.

Güvenlik

Bölüm başlığı “Güvenlik”
  • Taslaklar hiçbir zaman ziyaretçilere görünmez. update_section ve taslak yazılar ancak publish_page (veya yazılarda status: "published") ile yayına çıkar ve bunun için anahtarda publish kapsamı olmalıdır.
  • Yalnızca taslak üzerinde çalışmasını istediğiniz bir asistana publish vermeyin. Böylece yayın her zaman sizin elinizde kalır.
  • update_seo ve set_look taslak değildir, kaydedildikleri anda canlı sitede geçerli olur. Asistandan önce değişikliği göstermesini isteyin.
  • Önizleme bağlantıları bir saat geçerlidir ve bağlantıya sahip herkes taslakları görebilir. Bağlantıyı yalnızca ilgili kişilerle paylaşın.
  • Site anahtarı yalnızca kendi sitesini görür; başka bir site 404 verir.
  • Yapılandırma dosyalarını git’e eklemeyin. Anahtar sızarsa Studio › Ayarlar › API anahtarları ekranından hemen iptal edin.
  • Bağlayıcılar (OAuth) aynı ekranda “Bağlayıcı” etiketiyle görünür; kullanmadığınız bağlantıları oradan iptal edin. Katalify jetonların yalnızca özetini saklar.
  • Hız sınırı MCP için de geçerlidir: anahtar başına 10 dakikada 600 istek. Bkz. Hız sınırı.

Destek

Bölüm başlığı “Destek”

Sorularınız ve hata bildirimleri için: studio@katalify.com. Bkz. Destek.

Claude, Anthropic PBC’nin; ChatGPT, OpenAI’nin tescilli markasıdır; Katalify bu şirketlerle bağlı değildir.

studio@katalify.com