Compeller MCP Server

Compeller MCP uç noktası (/api/mcp)

Compeller MCP uç noktası, mevcut v1 REST API'si üzerine ince bir JSON-RPC 2.0 sarmalayıcı olarak Model Context Protocol'ü uygular. Ham HTTP yerine MCP'yi doğal olarak konuşan ajan entegratörleri (Claude Desktop, Cursor, özel MCP istemcileri, DigiRAMP) için tasarlanmıştır.

• Taşıma: Akışkan HTTP (HTTP POST başına tek JSON-RPC mesajı).
• URL: POST https://compeller.ai/api/mcp
• Protokol sürümü: 2024-11-05
• Sunucu adı / sürümü: compeller-mcp / initialize sonucuna bakın.
• Araç sözleşmesi: Aşağıdaki araç listesi genel entegrasyon sözleşmesidir. Dağıtılan sunucuda çalışma zamanında duyurulan set için tools/list kullanın.
• Dizin listeleri: Resmi MCP Kaydı · Smithery · Glama

Kimlik Doğrulama

Anonim (keşif) yöntemler: initialize, tools/list, ping, notifications/initialized, artı anonim araçlar get_capabilities, get_pricing, list_styles.

Diğer tüm araçlar, JSON-RPC gövdesi içinde değil, HTTP isteğinin kendisinde iletilen bir Compeller API belirteci gerektirir. Her iki başlık da çalışır:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

Belirteçler Compeller User başına verilir (/api/v1/* tarafından kullanılan belirteçlerle aynı). Ajanlar bir belirteci iki yoldan biriyle edinebilir:

1. Kullanıcıdan oturum açmasını, Hesap → API Erişimi'ni açmasını, belirteci göstermesini ve ajanın gizli deposuna yapıştırmasını isteyin.
2. Mevcut oturum açma uç noktasını kullanın ve access_token'i taşıyıcı belirteç olarak gönderin. Cookie başlığına gerek yoktur veya beklenmez:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"..."}'

Normal kullanıcılar username ve access_token alır. roles yalnızca temel ROLE_COMPELLER ötesinde rollere sahip hesaplar için görünür; refresh_token ve expires_in yalnızca boş olmadığında görünür.

3. Veya kalıcı API belirtecini döndüren v1 kimlik doğrulama yardımcısı aracılığıyla kimlik bilgilerini değiştirin:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}'

Eksik veya geçersiz bir belirteç, MCP istemcilerinin kullanıcıdan kimlik bilgilerini isteyebilmesi için bir JSON-RPC hatası olarak değil, "API token required." / "Invalid API token." mesajıyla bir araç hatası (isError: true) olarak yüzeye çıkar.

JSON-RPC yöntemleri

Yöntem	Amaç	HTTP sonucu
initialize	Yetenek el sıkışması. protocolVersion, serverInfo, capabilities döndürür.	200 JSON-RPC sonucu
notifications/initialized	İstemci onayı. Yanıt gövdesi yok.	204
tools/list	Her aracı şema + açıklama ile listeler.	200 JSON-RPC sonucu
tools/call	Bir aracı çağırır. params = {name, arguments}.	200 JSON-RPC sonucu (araç hataları {isError: true, content: [...]} olarak geri döner)
ping	İşlem yapmayan canlı tutma.	200 JSON-RPC result: {}

Bilinmeyen yöntemler JSON-RPC hatası -32601 Method not found döndürür. Bilinmeyen araç adları -32602 Unknown tool döndürür. Hatalı biçimlendirilmiş bir JSON gövdesi -32700 Parse error döndürür. Eksik / yanlış jsonrpc veya eksik method, -32600 Invalid Request döndürür.

Araçlar

Tüm araçlar, text alanı JSON biçimli yapılandırılmış çıktı olan type: text türünde tek bir content girişi döndürür. Başarısızlık durumunda, aynı yanıt şekli isError: true ve content[0].text içinde insan tarafından okunabilir bir hata mesajıyla döndürülür — asla bir JSON-RPC error olarak değil.

Keşif (kimlik doğrulama yok)

Araç	Girdiler	Döndürdükleri
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	id, name, monthlyUsd, features[] ile plans[]
list_styles	—	id, name ile styles[] (id, create_compel / create_compel_from_music'ün style için kabul ettiği tam değerdir)

Medya ve müzik (aksi belirtilmedikçe kimlik doğrulama gerekli)

Araç	Gerekli	İsteğe bağlı	Döndürdükleri
search_music	query	limit	create_compel_from_music için uygun genel müzik arama sonuçları. Kimlik doğrulama gerekmez.
upload_media	—	name, mime_type, type	POST /api/v1/media'ü işaret eden yükleme talimatları
search_media	—	type (audio/image/video/text), limit (≤100, varsayılan 20), offset	media[], paging

Zorlamalar (kimlik doğrulama gerekli)

Araç	Gerekli	İsteğe bağlı	Döndürdükleri
create_compel_from_music	track_id	title, style, target_platform, aspect_ratio, artist_context	compel_id, status, next_action
create_compel	title, primary_media_id	style, target_platform, aspect_ratio, artist_context	compel_id, status: QUEUED
get_compel	compel_id	—	compel_id, title, status, progress_percent, stage, rendering_id, created_at, human_url, next_action
start_render	compel_id	—	Zorlama hazır olduğunda son işlemeyi başlatır; durumu ve sonraki eylemi döndürür.
cancel_compel	compel_id	—	Devam eden bir zorlamayı iptal eder (idempotent — zaten İPTAL EDİLDİ başarılı olur); compel_id, status: CANCELLED, stage döndürür.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform ve aspect_ratio, araç şemalarındaki enum ile kısıtlanmıştır (bkz. get_capabilities.enums); style değerleri doğrudan list_styles'den gelir.

Hesap (kimlik doğrulama gerekli)

Araç	Girdiler	Döndürdükleri
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — maliyet bilincine sahip kararlar vermek için pahalı bir işlemeden önce çağırın.

İşlemeler (kimlik doğrulama gerekli)

Araç	Gerekli	Döndürdükleri
list_renderings	compel_id	compel_id, rendering_id, status, download_url ile renderings[]
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url, GET /api/v1/renderings/{id}/download'i işaret eder (HTTP Range'i destekler). Tamamlanan zorlama/işleme yanıtları ayrıca, ajanların kullanıcılara zorlamayı canlı bir performans sistemi olarak nasıl deneyimleyeceklerini söyleyebilmesi için ücretsiz REACT indirmesi (https://compeller.ai/download/desktop) ve daha fazla bilgi URL'si (https://compeller.ai/react) içeren bir react devri içerir.

Web kancaları (kimlik doğrulama gerekli)

Compeller ile entegre olan ajanlar, get_compel'i yoklamak yerine zorlama yaşam döngüsü olaylarının imzalı anlık bildirimleri için kendi kendine kaydolabilir. Bir zorlamanın işlenebilir olduğu anı öğrenmek (ardından start_render'i çağırın) için compel.ready'e abone olun; compel.completed / compel.failed terminal olaylardır.

Araç	Gerekli	İsteğe bağlı	Döndürdükleri
register_webhook	url (HTTPS, ≤2048 karakter)	events[] — varsayılan ["*"]; bilinen değerler: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (tam olarak bir kez döndürülür), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Sırlar bu araç tarafından asla döndürülmez.
update_webhook	webhook_id	url, events[], active — en az biri	webhook_id, url, events, active, created_at, updated_at. Sırlar asla döndürülmez; bunun için rotate_webhook_secret kullanın.
delete_webhook	webhook_id	—	webhook_id, deleted: true
test_webhook_delivery	webhook_id	—	webhook_id, event_id, event_type: "webhook.test", delivered, response_status?, response_body_preview?, latency_ms, error?. Senkron — araç, entegratörün uç noktasının yanıt vermesini bekler (maks 5sn). Sırlar asla döndürülmez.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (yeni — tam olarak bir kez döndürülür), created_at, updated_at. Eski sır hemen geçersiz kılınır.

Bilinmeyen olay adları sessizce * joker karakterine daraltılır; bu, POST /api/v1/webhooks'i yansıtır, böylece bir ajan asla işlem yapmayan bir abonelik oluşturmaz.

Teslimat en az bir kezdir. Her olay hemen denenir ve uç noktanız erişilemezse veya 2xx olmayan bir yanıt döndürürse, geri çekilme ile yeniden denenir — toplamda 6 denemeye kadar (hemen, ardından 1dk, 5dk, 30dk, 2s, 6s sonra). Her deneme aynı X-Compeller-Event-Id ve bayt olarak aynı imzalı gövdeyi taşır, bu nedenle bu kimlik üzerinde tekilleştirme yapın. Tüm denemeler tükenirse olay düşürülür; get_compel aracılığıyla mutabakat sağlayın.

register_webhook, dahili altyapıyı işaret eden hedefleri bir araç hatasıyla reddeder: geri döngü, RFC1918 özel aralıkları, bağlantı yerel (169.254.169.254 gibi bulut meta veri IP'leri dahil), IPv6 ULA, CGNAT, çok noktaya yayın, belirtilmemiş adres ve .local / .internal / .localhost ile biten ana bilgisayar adları. Aynı kontrol, teslimat sırasında her denemede çözümlenen DNS'e karşı yeniden çalıştırılır, bu nedenle kayıttan sonra engellenen bir IP'ye yeniden bağlanan bir ana bilgisayar adı o deneme için atlanır (günlüğe kaydedilir); engellenmeye devam ederse yeniden deneme bütçesini tüketir ve ardından düşürülür.

test_webhook_delivery, bir HMAC-SHA256 imzasıyla sentetik bir webhook.test olayı gönderir ve uç noktanın yanıtını senkron olarak bekler. Uç noktanın abone olunan events'ini yok sayar (her zaman teslim edilir) ve gerçek teslimatlarla aynı URL güvenlik kontrolünü uygular. 2xx olmayan bir yanıt delivered: false olarak yüzeye çıkar ancak MCP çağrısının kendisi yine de başarıyla döner — sonuç yüktür.

update_webhook, url, events, active'ten herhangi birini kabul eder (en az biri). URL doğrulaması register_webhook'ü yansıtır. Sırlar bu araç tarafından asla döndürülmez.

rotate_webhook_secret, yeni bir 64 karakterlik onaltılık imzalama sırrı oluşturur, tam olarak bir kez döndürür ve önceki sırrı hemen geçersiz kılar. Bir sonraki gerçek teslimattan önce alındığında yeni sırrı saklayın.

Her teslimat, REST yoluyla tam olarak aynı şekilde imzalanır — tam zarf ve başlık sözleşmesi için openapi.yaml'nın Webhooks bölümüne bakın.

Örnek oturum

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

3. adıma verilen yanıt, webhook_id, secret vb. içeren bir JSON belgesi olan content[0].text'ü içeren bir JSON-RPC result'dir. secret'i hemen saklayın; sunucu onu bir daha döndürmez.

Hata kodları

Kod	Anlamı	Nedeni
-32700	Ayrıştırma hatası	Gövde geçerli JSON değil
-32600	Geçersiz İstek	Eksik/yanlış jsonrpc, eksik method, boş gövde
-32601	Yöntem bulunamadı	Bilinmeyen JSON-RPC yöntemi
-32602	Geçersiz parametreler	Bilinmeyen araç, eksik araç name, hatalı params şekli
-32603	Dahili hata	İşlenmeyen istisna (sunucu tarafında günlüğe kaydedilir)

Araç düzeyindeki hatalar (doğrulama, kimlik doğrulama, bulunamadı), başarılı bir JSON-RPC yanıtı içinde {result: {isError: true, content: [{type: "text", text: "..."}]}} olarak döndürülür. Bu MCP kuralı gereğidir — LLM'nin hatayı olduğu gibi görmesini ve yüzeye çıkarmasını sağlar. Ajan ses karar ağacı: kullanıcı MP3/WAV/FLAC sağlarsa, upload_media ardından create_compel kullanın; kullanıcı yalnızca bir şarkı/sanatçı dizesi sağlarsa, search_music ardından create_compel_from_music kullanın; açıkça oluşturulmuş test sesi istenmedikçe bir ton sentezlemeyin.