Compeller

Compeller MCP 端點（/api/mcp）

Compeller MCP 端點將 Model Context Protocol 實作為現有 v1 REST API 之上的輕量 JSON-RPC 2.0 包裝層。它專為原生使用 MCP 而非原始 HTTP 的代理整合者（Claude Desktop、Cursor、自訂 MCP 用戶端、DigiRAMP）而設計。

• 傳輸方式： Streamable HTTP（每個 HTTP POST 攜帶單一 JSON-RPC 訊息）。
• URL： POST https://compeller.ai/api/mcp
• 協定版本： 2024-11-05
• 伺服器名稱／版本： compeller-mcp／請參閱 initialize 結果。
• 工具契約： 下列工具清單即為公開整合契約。請使用 tools/list 取得部署伺服器上由執行時期公告的工具集合。
• 目錄列表： 官方 MCP Registry · Smithery · Glama

驗證

匿名（探索）方法：initialize、tools/list、ping、notifications/initialized，以及匿名工具 get_capabilities、get_pricing、list_styles。

其他所有工具都需要在 HTTP 請求本身傳遞 Compeller API token，而非放在 JSON-RPC body 內。以下任一 header 皆可使用：

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

Token 是依每個 Compeller User 簽發（與 /api/v1/* 使用的 token 相同）。代理可透過以下兩種方式之一取得：

1. 要求使用者登入，開啟 Account → API Access，顯示 token，並將其貼入代理的密鑰儲存區。
2. 使用現有的登入端點，並將 access_token 作為 bearer token 傳送。不需要也不預期 Cookie header：

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"artist@example.com","password":"..."}'

一般使用者會收到 username 和 access_token。roles 僅在帳戶具備超越基準 ROLE_COMPELLER 的角色時出現；refresh_token 和 expires_in 僅在非空值時出現。

3. 或透過 v1 驗證輔助工具交換憑證，該工具會回傳持久性的 API token：

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

缺少或無效的 token 會以 工具錯誤（isError: true）的形式呈現，訊息為 "API token required."／"Invalid API token."，而非 JSON-RPC 錯誤，因此 MCP 用戶端可以提示使用者提供憑證。

JSON-RPC 方法

方法	用途	HTTP 結果
initialize	能力交握。回傳 protocolVersion、serverInfo、capabilities。	200 JSON-RPC 結果
notifications/initialized	用戶端確認。無回應 body。	204
tools/list	列出每個工具及其 schema 與描述。	200 JSON-RPC 結果
tools/call	呼叫工具。params = {name, arguments}。	200 JSON-RPC 結果（工具錯誤會以 {isError: true, content: [...]} 形式回傳）
ping	無操作 keepalive。	200 JSON-RPC result: {}

未知方法會回傳 JSON-RPC 錯誤 -32601 Method not found。未知工具名稱會回傳 -32602 Unknown tool。格式錯誤的 JSON body 會回傳 -32700 Parse error。缺少或錯誤的 jsonrpc 或缺少 method 會回傳 -32600 Invalid Request。

工具

所有工具皆回傳單一 content 條目，其型別為 type: text，其中 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

Compels（需驗證）

工具	必填	選填	回傳
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	—	當 compel 就緒時開始最終渲染；回傳狀態與下一步動作。
cancel_compel	compel_id	—	取消進行中的 compel（冪等——已 CANCELLED 者仍會成功）；回傳 compel_id、status: CANCELLED、stage。
list_compels	—	limit（≤100）、offset	compels[]、paging
search_compels	query	limit	compels[]、count

style、target_platform 和 aspect_ratio 受工具 schema 中的 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 Range）。已完成的 compel／渲染回應也包含 react 交接，提供免費的 REACT 下載（https://compeller.ai/download/desktop）和了解更多 URL（https://compeller.ai/react），讓代理可以告知使用者如何將 compel 體驗為現場表演系統。

Webhooks（需驗證）

與 Compeller 整合的代理可以自行註冊以接收 compel 生命週期事件的簽章推送通知，而無需輪詢 get_compel。訂閱 compel.ready 以在 compel 可渲染時立即得知（然後呼叫 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 一致，因此代理永遠不會建立無效的訂閱。

傳遞為至少一次（at-least-once）。 每個事件會立即嘗試傳遞，若您的端點無法連線或回傳非 2xx 狀態碼，則會以退避方式重試——最多總共 6 次嘗試（立即，然後在 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時後）。每次嘗試都攜帶相同的 X-Compeller-Event-Id 和位元組完全相同的簽章 body，因此請以該 id 進行去重。若所有嘗試皆耗盡，事件會被丟棄；請透過 get_compel 進行對帳。

register_webhook 會以工具錯誤拒絕指向內部基礎設施的目的地：loopback、RFC1918 私有範圍、link-local（包括雲端 metadata IP，如 169.254.169.254）、IPv6 ULA、CGNAT、multicast、未指定位址，以及以 .local／.internal／.localhost 結尾的主機名稱。相同的檢查會在每次嘗試的傳遞時間對解析後的 DNS 重新執行，因此若主機名稱在註冊後重新綁定至被封鎖的 IP，該次嘗試會被跳過（記錄）；若持續被封鎖，則僅消耗其重試預算，之後被丟棄。

test_webhook_delivery 會傳送一個合成的 webhook.test 事件，帶有 HMAC-SHA256 簽章，並同步等待端點的回應。它會忽略端點已訂閱的 events（一律傳遞），並套用與真實傳遞相同的 URL 安全檢查。非 2xx 回應會以 delivered: false 形式呈現，但 MCP 呼叫本身仍會成功回傳——結果即為 payload。

update_webhook 接受 url、events、active 中的任一項（至少一個）。URL 驗證與 register_webhook 一致。此工具絕不回傳密鑰。

rotate_webhook_secret 會產生一個全新的 64 字元十六進位簽章密鑰，僅回傳一次，並立即使先前的密鑰失效。請在收到新密鑰後、下一次真實傳遞前立即儲存。

每次傳遞的簽章方式與 REST 路徑完全相同——請參閱 openapi.yaml 的 Webhooks 章節以了解完整的 envelope 與 header 契約。

範例工作階段

# 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	解析錯誤	Body 不是有效的 JSON
-32600	無效請求	缺少／錯誤的 jsonrpc、缺少 method、空 body
-32601	找不到方法	未知的 JSON-RPC 方法
-32602	無效參數	未知工具、缺少工具 name、params 形狀錯誤
-32603	內部錯誤	未處理的例外（伺服器端記錄）

工具層級的失敗（驗證、驗證、找不到）會在成功的 JSON-RPC 回應內以 {result: {isError: true, content: [{type: "text", text: "..."}]}} 形式回傳。這是 MCP 的慣例——讓 LLM 能逐字看到並呈現失敗訊息。 Agent 音訊決策樹：如果使用者提供 MP3/WAV/FLAC，請先使用 upload_media，再使用 create_compel；如果使用者僅提供歌曲/藝人字串，請先使用 search_music，再使用 create_compel_from_music；除非明確要求產生測試音訊，否則不要合成音調。