Compeller MCP Server

आधिकारिक

MCP के माध्यम से गानों से AI संगीत वीडियो और ऑडियो-रिएक्टिव विज़ुअल बनाएं।

दस्तावेज़

Compeller MCP एंडपॉइंट (`/api/mcp`)

Compeller MCP एंडपॉइंट मौजूदा v1 REST API पर एक पतली JSON-RPC 2.0 रैपर के रूप में मॉडल कॉन्टेक्स्ट प्रोटोकॉल लागू करता है। यह एजेंट इंटीग्रेटर्स (Claude Desktop, Cursor, कस्टम MCP क्लाइंट, DigiRAMP) के लिए है जो कच्चे HTTP के बजाय मूल रूप से MCP बोलते हैं।

ट्रांसपोर्ट: स्ट्रीमेबल HTTP (प्रति HTTP POST एक JSON-RPC संदेश)।
URL: POST https://compeller.ai/api/mcp
प्रोटोकॉल संस्करण: 2024-11-05
सर्वर नाम / संस्करण: compeller-mcp / initialize परिणाम देखें।
टूल अनुबंध: नीचे दी गई टूल सूची सार्वजनिक एकीकरण अनुबंध है। तैनात सर्वर पर रनटाइम-विज्ञापित सेट के लिए tools/list का उपयोग करें।
निर्देशिका सूची: आधिकारिक MCP रजिस्ट्री · Smithery · Glama

प्रमाणीकरण

अनाम (खोज) विधियाँ: initialize, tools/list, ping, notifications/initialized, साथ ही अनाम टूल get_capabilities, get_pricing, list_styles।

हर दूसरे टूल के लिए HTTP अनुरोध पर ही एक Compeller API टोकन पास करना आवश्यक है, JSON-RPC बॉडी के अंदर नहीं। कोई भी हेडर काम करता है:

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

टोकन प्रति Compeller User जारी किए जाते हैं (वही टोकन जो /api/v1/* द्वारा उपयोग किए जाते हैं)। एजेंट दो तरीकों में से किसी एक से इसे प्राप्त कर सकते हैं:

उपयोगकर्ता को लॉग इन करने, खाता → API एक्सेस खोलने, टोकन प्रकट करने और इसे एजेंट के गुप्त भंडार में पेस्ट करने के लिए कहें।
मौजूदा लॉगिन एंडपॉइंट का उपयोग करें और access_token को बियरर टोकन के रूप में भेजें। किसी कुकी हेडर की आवश्यकता या अपेक्षा नहीं है:

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

सामान्य उपयोगकर्ताओं को username और access_token प्राप्त होते हैं। roles केवल उन खातों के लिए प्रकट होता है जिनकी भूमिकाएँ आधारभूत ROLE_COMPELLER से परे हैं; refresh_token और expires_in केवल तभी प्रकट होते हैं जब वे खाली न हों।

या v1 प्रमाणीकरण सहायक के माध्यम से क्रेडेंशियल्स का आदान-प्रदान करें, जो स्थायी API टोकन लौटाता है:

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

एक गुम या अमान्य टोकन टूल त्रुटि (isError: true) के रूप में "API token required." / "Invalid API token." संदेश के साथ सामने आता है, न कि JSON-RPC त्रुटि के रूप में, ताकि MCP क्लाइंट उपयोगकर्ता को क्रेडेंशियल्स के लिए संकेत दे सकें।

JSON-RPC विधियाँ

विधि	उद्देश्य	HTTP परिणाम
`initialize`	क्षमता हैंडशेक। `protocolVersion`, `serverInfo`, `capabilities` लौटाता है।	200 JSON-RPC परिणाम
`notifications/initialized`	क्लाइंट स्वीकृति। कोई प्रतिक्रिया बॉडी नहीं।	204
`tools/list`	स्कीमा + विवरण के साथ हर टूल सूचीबद्ध करें।	200 JSON-RPC परिणाम
`tools/call`	एक टूल आमंत्रित करें। `params = {name, arguments}`।	200 JSON-RPC परिणाम (टूल त्रुटियाँ `{isError: true, content: [...]}` के रूप में वापस आती हैं)
`ping`	नो-ऑप कीपअलाइव।	200 JSON-RPC `result: {}`

अज्ञात विधियाँ JSON-RPC त्रुटि -32601 Method not found लौटाती हैं। अज्ञात टूल नाम -32602 Unknown tool लौटाते हैं। एक विकृत JSON बॉडी -32700 Parse error लौटाती है। एक गुम / गलत jsonrpc या गुम method -32600 Invalid Request लौटाता है।

टूल

सभी टूल type: text की एक एकल content प्रविष्टि लौटाते हैं जिसका text फ़ील्ड JSON-स्वरूपित संरचित आउटपुट है। विफलता पर, वही प्रतिक्रिया आकार isError: true और content[0].text में एक मानव-पठनीय त्रुटि संदेश के साथ लौटाया जाता है — कभी भी JSON-RPC error के रूप में नहीं।

खोज (कोई प्रमाणीकरण नहीं)

टूल	इनपुट	लौटाता है
`get_capabilities`	—	`productName`, `version`, `capabilities[]`, `spec_url`, `enums` (`styles`, `target_platforms`, `aspect_ratios`), `auth`, `media_limits`, `rate_limits`
`get_pricing`	—	`plans[]` के साथ `id`, `name`, `monthlyUsd`, `features[]`
`list_styles`	—	`styles[]` के साथ `id`, `name` (`id` वह सटीक मान है जिसे `create_compel` / `create_compel_from_music` `style` के लिए स्वीकार करते हैं)

मीडिया और संगीत (प्रमाणीकरण आवश्यक जब तक उल्लेख न हो)

टूल	आवश्यक	वैकल्पिक	लौटाता है
`search_music`	`query`	`limit`	`create_compel_from_music` के लिए उपयुक्त सार्वजनिक संगीत खोज परिणाम। कोई प्रमाणीकरण आवश्यक नहीं।
`upload_media`	—	`name`, `mime_type`, `type`	`POST /api/v1/media` की ओर इशारा करते अपलोड निर्देश
`search_media`	—	`type` (`audio`/`image`/`video`/`text`), `limit` (≤100, डिफ़ॉल्ट 20), `offset`	`media[]`, `paging`

कम्पेल्स (प्रमाणीकरण आवश्यक)

टूल	आवश्यक	वैकल्पिक	लौटाता है
`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`	—	जब कम्पेल तैयार हो तब अंतिम रेंडरिंग शुरू करता है; स्थिति और अगली कार्रवाई लौटाता है।
`cancel_compel`	`compel_id`	—	एक प्रगतिरत कम्पेल रद्द करता है (इडेम्पोटेंट — पहले से रद्द सफल होता है); `compel_id`, `status: CANCELLED`, `stage` लौटाता है।
`list_compels`	—	`limit` (≤100), `offset`	`compels[]`, `paging`
`search_compels`	`query`	`limit`	`compels[]`, `count`

style, target_platform, और aspect_ratio टूल स्कीमा में enum द्वारा बाध्य हैं (get_capabilities.enums देखें); style मान सीधे list_styles से आते हैं।

खाता (प्रमाणीकरण आवश्यक)

टूल	इनपुट	लौटाता है
`get_account_credits`	—	`plan`, `minutes_remaining`, `free_minutes_remaining`, `paid_minutes_remaining`, `minutes_total`, `quota_exceeded`, `api_eligible`, `billing_url` — लागत-जागरूक निर्णय लेने के लिए किसी महंगी रेंडरिंग से पहले कॉल करें।

रेंडरिंग्स (प्रमाणीकरण आवश्यक)

टूल	आवश्यक	लौटाता है
`list_renderings`	`compel_id`	`compel_id`, `renderings[]` के साथ `rendering_id`, `status`, `download_url`
`get_rendering`	`rendering_id`	`rendering_id`, `compel_id`, `status`, `download_url`

download_url GET /api/v1/renderings/{id}/download की ओर इशारा करता है (HTTP रेंज का समर्थन करता है)। पूर्ण कम्पेल/रेंडरिंग प्रतिक्रियाओं में एक react हैंडऑफ भी शामिल है जिसमें मुफ्त REACT डाउनलोड (https://compeller.ai/download/desktop) और और-जानें URL (https://compeller.ai/react) है ताकि एजेंट उपयोगकर्ताओं को बता सकें कि कम्पेल को एक लाइव प्रदर्शन प्रणाली के रूप में कैसे अनुभव करें।

वेबहुक्स (प्रमाणीकरण आवश्यक)

Compeller के साथ एकीकृत होने वाले एजेंट get_compel को पोल करने के बजाय कम्पेल जीवनचक्र घटनाओं की हस्ताक्षरित पुश सूचनाओं के लिए स्व-पंजीकरण कर सकते हैं। compel.ready की सदस्यता लें ताकि बिना पोल किए उस क्षण जान सकें जब कोई कम्पेल रेंडर करने योग्य हो (फिर start_render कॉल करें); compel.completed / compel.failed अंतिम घटनाएँ हैं।

टूल	आवश्यक	वैकल्पिक	लौटाता है
`register_webhook`	`url` (HTTPS, ≤2048 वर्ण)	`events[]` — डिफ़ॉल्ट `[""]`; ज्ञात मान: ``, `compel.ready`, `compel.completed`, `compel.failed`	`webhook_id`, `url`, `events`, `secret` (ठीक एक बार लौटाया गया), `active`, `created_at`
`list_webhooks`	—	—	`webhooks[]` — `webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`। इस टूल द्वारा रहस्य कभी नहीं लौटाए जाते।
`update_webhook`	`webhook_id`	`url`, `events[]`, `active` — कम से कम एक	`webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`। रहस्य कभी नहीं लौटाए जाते; इसके लिए `rotate_webhook_secret` का उपयोग करें।
`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?`। तुल्यकालिक — टूल इंटीग्रेटर के एंडपॉइंट की प्रतिक्रिया की प्रतीक्षा करता है (अधिकतम 5 सेकंड)। रहस्य कभी नहीं लौटाए जाते।
`rotate_webhook_secret`	`webhook_id`	—	`webhook_id`, `url`, `events`, `active`, `secret` (नया — ठीक एक बार लौटाया गया), `created_at`, `updated_at`। पुराना रहस्य तुरंत अमान्य हो जाता है।

अज्ञात घटना नाम चुपचाप वाइल्डकार्ड * में समा जाते हैं; यह POST /api/v1/webhooks को दर्पण करता है ताकि कोई एजेंट कभी नो-ऑप सदस्यता न बनाए।

डिलीवरी कम-से-कम एक बार होती है। प्रत्येक घटना का तुरंत प्रयास किया जाता है और, यदि आपका एंडपॉइंट अनुपलब्ध है या गैर-2xx लौटाता है, तो बैकऑफ के साथ पुनः प्रयास किया जाता है — कुल 6 प्रयासों तक (तुरंत, फिर 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे बाद)। हर प्रयास में वही X-Compeller-Event-Id और एक बाइट-समान हस्ताक्षरित बॉडी होती है, इसलिए उस आईडी पर डीडुप करें। यदि सभी प्रयास समाप्त हो जाते हैं तो घटना छोड़ दी जाती है; get_compel के माध्यम से सामंजस्य करें।

register_webhook उन गंतव्यों को अस्वीकार करता है जो आंतरिक बुनियादी ढांचे की ओर इशारा करते हैं, एक टूल त्रुटि के साथ: लूपबैक, RFC1918 निजी श्रेणियाँ, लिंक-लोकल (169.254.169.254 जैसे क्लाउड मेटाडेटा आईपी सहित), IPv6 ULA, CGNAT, मल्टीकास्ट, अनिर्दिष्ट पता, और .local / .internal / .localhost में समाप्त होने वाले होस्टनाम। डिलीवरी के समय हर प्रयास पर हल किए गए DNS के विरुद्ध वही जाँच फिर से चलती है, इसलिए एक होस्टनाम जो पंजीकरण के बाद किसी अवरुद्ध आईपी पर रीबाइंड करता है, उस प्रयास के लिए छोड़ दिया जाता है (लॉग किया गया); यदि यह अवरुद्ध रहता है तो यह बस अपना पुनर्प्रयास बजट खपत करता है और फिर छोड़ दिया जाता है।

test_webhook_delivery एक HMAC-SHA256 हस्ताक्षर के साथ एक सिंथेटिक webhook.test घटना भेजता है और एंडपॉइंट की प्रतिक्रिया के लिए तुल्यकालिक रूप से प्रतीक्षा करता है। यह एंडपॉइंट की सब्सक्राइब्ड events को अनदेखा करता है (हमेशा डिलीवर किया जाता है) और वास्तविक डिलीवरी के समान URL सुरक्षा जाँच लागू करता है। एक गैर-2xx प्रतिक्रिया delivered: false के रूप में सामने आती है लेकिन MCP कॉल स्वयं फिर भी सफलतापूर्वक लौटती है — परिणाम पेलोड है।

update_webhook url, events, active (कम से कम एक) में से कोई भी स्वीकार करता है। URL सत्यापन register_webhook को दर्पण करता है। इस टूल द्वारा रहस्य कभी नहीं लौटाए जाते।

rotate_webhook_secret एक ताज़ा 64-वर्ण हेक्स हस्ताक्षर रहस्य बनाता है, इसे ठीक एक बार लौटाता है, और पिछले रहस्य को तुरंत अमान्य कर देता है। अगली वास्तविक डिलीवरी से पहले प्राप्ति पर नया रहस्य संग्रहीत करें।

हर डिलीवरी पर ठीक REST पथ की तरह हस्ताक्षर किए जाते हैं — पूर्ण लिफाफा और हेडर अनुबंध के लिए openapi.yaml का Webhooks अनुभाग देखें।

उदाहरण सत्र

# 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 की प्रतिक्रिया एक JSON-RPC result है जिसमें content[0].text शामिल है — स्वयं एक JSON दस्तावेज़ जिसमें webhook_id, secret, आदि हैं। secret को तुरंत संग्रहीत करें; सर्वर इसे फिर से नहीं लौटाएगा।

त्रुटि कोड

कोड	अर्थ	कारण
`-32700`	पार्स त्रुटि	बॉडी मान्य JSON नहीं है
`-32600`	अमान्य अनुरोध	गुम/गलत `jsonrpc`, गुम `method`, खाली बॉडी
`-32601`	विधि नहीं मिली	अज्ञात JSON-RPC विधि
`-32602`	अमान्य पैरामीटर	अज्ञात टूल, गुम टूल `name`, खराब `params` आकार
`-32603`	आंतरिक त्रुटि	अनहैंडल्ड अपवाद (सर्वर-साइड लॉग किया गया)

टूल-स्तरीय विफलताएँ (सत्यापन, प्रमाणीकरण, नहीं-मिला) एक सफल JSON-RPC प्रतिक्रिया के अंदर {result: {isError: true, content: [{type: "text", text: "..."}]}} के रूप में लौटाई जाती हैं। यह MCP परंपरा द्वारा है — यह LLM को विफलता को शब्दशः देखने और सतह पर लाने देता है। एजेंट ऑडियो निर्णय वृक्ष: यदि उपयोगकर्ता MP3/WAV/FLAC प्रदान करता है, तो upload_media फिर create_compel का उपयोग करें; यदि उपयोगकर्ता केवल गीत/कलाकार स्ट्रिंग प्रदान करता है, तो search_music फिर create_compel_from_music का उपयोग करें; जब तक स्पष्ट रूप से उत्पन्न परीक्षण ऑडियो के लिए न कहा जाए, तब तक कोई टोन संश्लेषित न करें।