Compeller MCP Server

Compeller MCP 端點 (/api/mcp)

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

• 傳輸方式： 可串流的 HTTP（每個 HTTP POST 傳送單一 JSON-RPC 訊息）。
• URL： POST https://compeller.ai/api/mcp
• 協定版本： 2024-11-05
• 伺服器名稱 / 版本： compeller-mcp / 請參閱 initialize 結果。
• 工具合約： 下方的工具清單即為公開的整合合約。請使用 tools/list 來取得已部署伺服器上執行時期公告的集合。
• 目錄列表： Official MCP Registry · 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/* 使用的權杖相同）。代理可以透過以下兩種方式之一取得：

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

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 僅在非空時才會出現。

3. 或透過 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	列出每個工具及其 schema 與描述。	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。

工具

所有工具都會回傳單一 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（冪等 — 已取消的狀態會成功）；回傳 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，因此代理永遠不會建立無操作的訂閱。

傳遞為至少一次。 每個事件都會立即嘗試傳遞，如果您的端點無法連線或回傳非 2xx 狀態碼，則會以退避策略重試 — 總共最多嘗試 6 次（立即、1 分鐘後、5 分鐘後、30 分鐘後、2 小時後、6 小時後）。每次嘗試都帶有相同的 X-Compeller-Event-Id 和位元組完全相同的簽名主體，因此請根據該 ID 進行去重。如果所有嘗試都已用盡，則該事件將被丟棄；請透過 get_compel 進行調解。

register_webhook 會以工具錯誤拒絕指向內部基礎設施的目的地：迴路、RFC1918 私有範圍、鏈路本地（包括如 169.254.169.254 的雲端元數據 IP）、IPv6 ULA、CGNAT、多播、未指定位址，以及結尾為 .local / .internal / .localhost 的主機名稱。相同的檢查會在傳遞時針對每次嘗試的已解析 DNS 重新執行，因此註冊後重新綁定到被封鎖 IP 的主機名稱在該次嘗試中會被跳過（已記錄）；如果它持續被封鎖，則只會消耗其重試預算，然後被丟棄。

test_webhook_delivery 會發送一個合成的 webhook.test 事件，帶有 HMAC-SHA256 簽名，並同步等待端點的回應。它會忽略端點訂閱的 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 — 本身是一個帶有 webhook_id、secret 等的 JSON 文件。請立即儲存 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；除非明確要求生成測試音訊，否則不要合成音調。