MCP 文件 API 文件

MCP 文件

讓任何 AI Agent 用自然語言剪片、客製效果模組。MCP 能做的與 Web UI 完全一致。

連線

URL: https://ivideo.run/mcp

不需要金鑰。伺服器支援 OAuth 2.1（動態註冊 + PKCE）：支援 OAuth 的 client 第一次連線會自動開啟瀏覽器 → 登入 iVideo 帳號 → 完成授權，之後 client 自己記住憑證（90 天效期）。

Claude Code

claude mcp add --transport http hsvm https://ivideo.run/mcp

加入後輸入 /mcp 選 hsvm 觸發登入，瀏覽器自動開啟授權頁。

Codex CLI

codex mcp add hsvm --url https://ivideo.run/mcp

Codex 會自動偵測 OAuth 並提示登入。CI／自動化情境改用權杖：先到 ivideo.run/token 登入領取，然後：

export HSVM_TOKEN=<權杖>
codex mcp add hsvm --url https://ivideo.run/mcp --bearer-token-env-var HSVM_TOKEN
設定檔寫法（~/.codex/config.toml）：bearer_token_env_var 填的是環境變數名稱，不是權杖本身——權杖不要貼進設定檔，避免被 commit 進版控。

其他 stdio-only 的 MCP client

npx mcp-remote https://ivideo.run/mcp --header "Authorization: Bearer <權杖>"

工具總覽

剪輯流程

工具用途
list_projects / create_project專案列表／建立
get_timeline讀完整專案 JSON（含 docVersion）
update_timeline整份貼回修改後的 JSON（帶 baseVersion），回差異摘要
add_segment加片段（素材 in–out 秒數區間）
split_segment指定秒數下刀
reorder_segments重排片段順序
apply_module片段套用模組（params 覆寫預設值）
create_asset / complete_asset素材上傳（signed URL → PUT 檔案 → 標記就緒）

模組創作

工具用途
get_module_spec先呼叫這個：規格精華 + recipes（GIF 循環/定格/隱藏、參數綁定、字幕動畫、ducking）
validate_module驗證 manifest（不儲存），錯誤帶 path 可迭代修正
create_module建立／更新模組（同版本 409 → 遞增 version）
get_module / list_modules讀取／列表
publish_module發佈到市集（作者頭貼自動帶入）

建議工作流（給 Agent）

  1. 客製效果：get_module_spec → 依 recipe 撰寫 manifest → validate_module（照 path 修錯）→ create_module → apply_module
  2. 剪輯：get_timeline 了解現狀 → 小改動用單點工具（split_segment 等）；大規模重排直接改 JSON 用 update_timeline 貼回
  3. 衝突處理：update_timeline 回 409 = 使用者同時在 UI 上動了專案——重新 get_timeline 再套用修改
  4. 錯誤都是機器可讀的：{path, error} 逐條修正即可，不必猜

設計保證