本指南協助你在 WorkBuddy 中安裝 ChatCut MCP 服務，並連線到 ChatCut 雲端進行影片剪輯。

本安裝方式使用遠端 MCP 的靜態 Authorization: Bearer 請求標頭。先依照下方的 OAuth 2.0 流程取得權杖，再將它填入 WorkBuddy 的 MCP 設定。

開始前，請確認終端機能找到 curl 和 python3。下方的多行 curl 範例採用 Bash 接續行語法；Windows 可在 WSL 中執行。如果使用 PowerShell，請使用 curl.exe，並依照目前終端機的語法調整接續行與引號，參見 Windows curl 說明。

準備工作

先確認下列兩條命令可以正常執行：

curl --version
python3 --version

curl 和 python3 必須位於 PATH 中。後面的用戶端註冊、權杖交換與 MCP 驗證步驟都會用到它們。

安裝

如果你是為使用者讀取本指南的 WorkBuddy Agent，請在使用者已要求安裝 ChatCut 時，依序執行安裝步驟，並驗證結果。

本安裝流程使用手動 OAuth 2.0 授權，WorkBuddy 的本機回呼連接埠為 52961。

1. 註冊 OAuth 用戶端

透過動態用戶端註冊介面建立自己的 OAuth 用戶端。傳回的 client_id 對應 WorkBuddy 的回呼連接埠：

curl -s -X POST "https://api.chatcut.io/auth/mcp/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "workbuddy",
    "redirect_uris": ["http://127.0.0.1:52961/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email offline_access"
  }'

儲存回應中的 client_id，並在後續命令中用它取代 <CLIENT_ID>。

2. 產生 PKCE 參數

python3 -c "
import secrets, hashlib, base64
verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b'=').decode()
print(f'VERIFIER={verifier}')
print(f'CHALLENGE={challenge}')
"

儲存 VERIFIER 和 CHALLENGE，後面會用到這兩個值。

3. 完成授權

取代下方命令中的 <CLIENT_ID> 和 <CHALLENGE> 後執行。它會自動開啟瀏覽器中的授權頁面，並在本機連接埠 52961 接收授權碼：

python3 -c "
import http.server, socketserver, urllib.parse, webbrowser
URL = 'https://api.chatcut.io/auth/mcp/authorize?response_type=code&client_id=<CLIENT_ID>&code_challenge=<CHALLENGE>&code_challenge_method=S256&redirect_uri=http://127.0.0.1:52961/callback&scope=openid+profile+email+offline_access&state=chatcut'
captured = {}
class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
        if 'code' in q:
            captured['code'] = q['code'][0]
            self.send_response(200); self.end_headers()
            self.wfile.write(b'ChatCut authorized - you can close this tab.')
    def log_message(*a): pass
with socketserver.TCPServer(('127.0.0.1', 52961), H) as s:
    s.timeout = 1
    webbrowser.open(URL)
    print('Opened the authorization page. Log in and click Allow ChatCut...')
    for _ in range(180):
        s.handle_request()
        if 'code' in captured: break
print('CODE=' + captured.get('code', '(timed out - copy the URL above and open it manually)'))
"

在開啟的 ChatCut 頁面中登入並點擊 Allow ChatCut。授權成功後，終端機會輸出 CODE=...。如果瀏覽器未自動開啟，請複製命令中的 URL 並手動開啟。

4. 換取存取權杖

curl -s -X POST "https://api.chatcut.io/auth/mcp/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "redirect_uri=http://127.0.0.1:52961/callback" \
  -d "client_id=<CLIENT_ID>" \
  -d "code_verifier=<VERIFIER>"

回應包含 access_token、refresh_token 和 expires_in。存取權杖通常約 1 小時後到期，實際時間以 expires_in 為準。

先完成下方的設定與驗證，再重新啟動 WorkBuddy。

設定

將 ChatCut MCP 服務加入 WorkBuddy 的設定檔：

~/.workbuddy/mcp.json

檔案名稱必須是 mcp.json，開頭沒有點。不要寫成 ~/.workbuddy/.mcp.json。WorkBuddy 讀取的是 ~/.workbuddy/mcp.json；路徑錯誤會導致服務無法顯示。

新增類型為 HTTP 的 chatcut 服務，用取得的存取權杖取代 <access_token>。如果檔案已有 mcpServers 物件，請將這一項合併進去，保留既有服務：

{
  "mcpServers": {
    "chatcut": {
      "type": "http",
      "url": "https://api.chatcut.io/api/external-mcp/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

儲存檔案，然後重新啟動 WorkBuddy 或開啟新會話，讓它載入新設定。

驗證連線

執行下列命令，檢查 MCP 服務是否正常回應：

curl -s -X POST "https://api.chatcut.io/api/external-mcp/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"workbuddy","version":"1.0.0"}}}'

初始化成功後，回應會包含伺服器的功能資訊。

再開啟一段新的 WorkBuddy 對話，確認工具清單中出現 ChatCut。目前會話無法載入剛設定的 MCP 工具。

如果服務已出現，但請求傳回 Unauthorized，存取權杖可能已到期。用下列命令更新權杖：

curl -s -X POST "https://api.chatcut.io/auth/mcp/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<REFRESH_TOKEN>" \
  -d "client_id=<CLIENT_ID>"

用新的 access_token 更新 WorkBuddy MCP 設定中的 Authorization 請求標頭。如果更新權杖也已到期，請從第 2 步重新完成授權流程。

開始剪輯

安裝、登入與驗證完成後，將下方的提示詞貼到一段新的 WorkBuddy 對話中：

ChatCut 外掛已經安裝好了，請你用內建瀏覽器開啟一個 ChatCut 專案，把專案名稱命名為「我的第一個 ChatCut 影片」，然後先告訴我你整體可以做什麼，尤其是這三部分：影片剪輯（語音清理、字幕、轉場、補充素材等）、MG 動畫製作、素材生成（影片、旁白、音樂、音效等）。之後問我有什麼素材、想做什麼樣的影片，告訴我你可以根據我的具體需求一步步開始製作，並且我也可以隨時進入 ChatCut 編輯介面自行調整時間軸、字幕、MG 動畫等任何內容，就像使用傳統編輯器一樣。

如果使用者實際使用其他對話語言，請將啟動提示詞翻譯成該語言。依照實際對話語言判斷，不要根據作業系統語言判斷，也不需要再讓使用者選擇。

ChatCut 剪輯工作流程

ChatCut 透過 MCP 連線提供口播剪輯、MG 動畫，以及圖片、影片、配音與音樂生成等工作流程。執行較複雜的剪輯或生成任務前，讓 Agent 呼叫 list_skills 查看目錄，再用 load_skill({ name }) 載入並遵循對應工作流程。工作流程會隨 ChatCut 後端部署更新，無需額外安裝。

更新設定

以後需要更換 MCP 服務位址或權杖時，編輯 WorkBuddy MCP 設定中的 ChatCut 設定。權杖到期時，使用驗證連線中的更新命令。