Compeller

Compeller MCP 端点 (/api/mcp)

Compeller MCP 端点将 Model Context Protocol 实现为一个薄层的 JSON-RPC 2.0 封装，覆盖现有的 v1 REST API。它面向原生使用 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 私有地址范围、链路本地地址（包括云元数据 IP，如 169.254.169.254）、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 — 本身是一个 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；除非明确要求生成测试音频，否则不要合成音调。