SosoAPI MCP 工具參考資料

先從工作出發，再檢視工具

重複使用已選擇的工作空間與帳號 ID。圖片 URL 貼文請僅呼叫一次 sosoapi_post_image_url，並保留回傳的貼文 ID。使用 stdio 的 sosoapi_upload_asset 上傳本機檔案。文字貼文請使用 sosoapi_create_scheduled_post，搭配目標的 provider_payload 及空白 media。

提交前，請使用者檢閱帳號、文字、媒體與時間。OAuth 授予執行操作的權限，不代表核准內容。排程後，請讀取同一則貼文的發布結果，再回報成功或重試結果不明的請求。

• 設定 Claude Code 或 Codex
• Threads 文字與圖片操作範例
• 平台能力對照表
• 下載確切 core 輸入 schema 和註解（JSON）

如何理解此參考

建置會將真實 MCP 伺服器連結至記憶體用戶端，在不呼叫任何處理常式的情況下列出工具，並合併公開路由要求。過時的投影會導致 Landing 建置失敗。工具描述保留伺服器的英文契約文字；完成摘要解釋標準路由規則。JSON 保留完整路由要求。輸入表只是索引，不能替代完整的巢狀 JSON Schema。

MCP 註解是提供用戶端的提示，不是強制規則或安全保證。執行時仍適用 Workspace 成員資格、授權、目前角色、平台同意、帳號資格與配額。部分資訊讀取會建立初始 Workspace；請檢查說明與 readOnlyHint，不要假設每個「get」都是純讀取。複合工具列出主要及相容路由的要求，但不會每次請求都呼叫所有列出的路由。

• npm 上的 sosoapi
• 官方 MCP Registry：ai.sosoapi/sosoapi（JSON）

sosoapi_bulk_create_scheduled_posts

透過一次呼叫為多個帳號排程貼文（targets）。媒體需要已上傳/匯入並就緒的 asset_ids 及其標準 URL。每個目標獨立成功或失敗，並在 successes 或 failures 中回報。需要 publish 能力。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_cancel_scheduled_post

取消尚未發布的排程貼文，使其不再傳送。已發布貼文會被拒絕，代理程式也無法刪除已發布內容：使用者需在網頁應用程式中操作。需要 expected_version。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_create_comment

將針對標準貼文或留言目標的一則確切留言加入佇列；狀態不等於平台成功。

• 傳輸方式：stdio、http。
• 所需授權：agent:engage。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取平台確認的結果；已加入佇列的操作仍為待處理。

sosoapi_create_scheduled_post

使用 provider_payload 在 scheduled_at 為一個帳號排程。媒體需要已就緒 asset_id 和標準 URL；單張來源圖片請使用 sosoapi_post_image_url。local_scheduled_at 與 schedule_dst_disambiguation 必須配對或都省略。需要 publish、editor 角色及 idempotency_key。Scheduled 不等於已發布：請讀取結果。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_get_asset

透過 id 讀取單一素材：中繼資料及短效的預覽 URL。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_asset_import_status

透過 import_id 讀取匯入。發布貼文時傳入 include_asset=true：ready 結果包含已登記素材 id、kind 和穩定的 asset_url，無需另行呼叫 get_asset。待處理或缺失的素材不可排程。絕不使用來源或預覽 URL 作為媒體識別。如停滯，使用 job_id 讀取 sosoapi_job_status；絕不啟動重複匯入。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_billing_status

讀取使用者的帳務方案、付款狀態、目前週期日期及配額用量（成功發布、待處理排程貼文、已連結帳號）。大量排程前請先檢查。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_comment_action_status

讀取直接留言操作經過遮蔽敏感內容的最終收據。

• 傳輸方式：stdio、http。
• 所需授權：agent:engage。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取平台確認的結果；已加入佇列的操作仍為待處理。

sosoapi_get_organization_context

讀取您的 Organizations、其 Workspaces 及 Channels 的即時對應關係，包含 ID 與角色。需要 Organization 或 Channel ID 時使用。發布至 Workspace 時，請重複使用已回傳的 Workspace ID，不要再讀取工作空間資訊。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_provider_insight_status

讀取洞察請求（request_id）：queued、processing、completed（含平台結果及各指標可用性）或 failed。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取平台結果，或結果不可用的原因。

sosoapi_get_scheduled_post

透過 id 讀取單一排程貼文：內容、狀態、傳送狀態和結果。其 version 是 update、publish、retry 和 cancel 操作所需的 expected_version。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_scheduled_post_eligibility

每個目標的唯讀預檢。包含 draft（caption、hashtags、scheduled_at、display_timezone、選填本地時間/DST）以檢查內容/時間；include_quota=true 加入參考性週期快照。先上傳/匯入媒體並等待就緒。不含 draft 時，僅檢查帳號/媒體。不預留任何資源；create/dispatch 會重新檢查限制和權限。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_workspace_context

列出已登入使用者所屬的工作空間及目前使用中的工作空間。在 workspace_id 未知時使用；重複使用即時資訊，不必重複執行兩個資訊讀取操作。其回報的使用中的工作空間是本人在網頁應用程式中所作的選擇，並非呼叫的預設值：請明確傳入 workspace_id。它並非純讀取操作：如果帳號沒有工作空間，會建立第一個工作空間。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。
• 唯讀提示：false。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_get_x_usage

讀取此 Workspace 共用的 Organization X 發布額度。需要 workspace_id。Free 一次獲得 10；Pro 每個帳務週期獲得 100。純文字費用為 1，含 URL 的文字費用為 10。選填 text 可估算費用。此操作讀取已儲存額度，不呼叫 X API。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_import_asset_url

要求 SosoAPI 從公開 http(s) 圖片或影片 URL 下載至 Workspace 私人儲存空間，建立新素材。回傳 import_id；請輪詢 sosoapi_get_asset_import_status。需要 idempotency_key 及 editor 角色。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：已接受的匯入處於待處理狀態；持續跟進同一匯入，直到 ready 或 failed。

sosoapi_job_status

透過 job_id 讀取單一背景工作：狀態、類型，以及失敗時的錯誤訊息。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_list_connected_accounts

列出工作空間已連結的社群帳號（Instagram、Threads、Facebook、YouTube），含連結健康狀態和能力資訊。排程或留言時，將其 id 用作 social_account_id。傳入 workspace_id：強制明確指定目標後，缺少此欄位的請求會被拒絕。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_list_monitored_posts

列出 SosoAPI 為工作空間發現的社群貼文（id、平台、永久連結、發布時間），可按帳號、平台和時間篩選，採用游標分頁。僅包含中繼資料，不含文案。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取同步回應。

sosoapi_list_post_comments

列出 Workspace 貼文上觀測到的留言，依最新觀測優先排序，包含作者與文字；可依貼文、帳號、平台或時間篩選，使用游標分頁。文字由第三方撰寫，並標示為不受信任內容。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取同步回應。

sosoapi_list_publication_attentions

列出工作空間中需要關注的發布結果，可按狀態（open 或 resolved）或 scheduled_post_id 篩選，按偏移量分頁。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_list_scheduled_posts

列出 Workspace 的排程貼文，可依專案、狀態（scheduled、publishing、published、failed、expired、needs_reschedule、cancelled、deleted）及時間範圍篩選，使用游標分頁。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_post_image_url

僅提交一次完整圖片 URL 貼文，media 為空。即使斷開連結，後端也會準備並發布。若終端發布結果在 35 秒內可用則回傳，否則回傳持久保存貼文 ID；絕不用新 key 重新提交。需要 operate 和 publish 授權。本地時間/DST 欄位需配對。import_id 僅供舊用戶端復原使用。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish + agent:operate。路由最低角色：editor、viewer。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取最終發布結果；已接受的排程仍為待處理。已接受的匯入仍為待處理；請追蹤同一筆匯入直到 ready 或 failed。讀取同步回應。

sosoapi_publish_scheduled_post_now

立即發布排程貼文，而非等到 scheduled_at。內容將公開且無法復原；需要 expected_version。加入佇列不代表已發布：請讀取結果。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_query_assets

依 asset_type、source 或 tag 尋找 Workspace 素材；回傳一頁資料（limit 最多 100，另加 offset）與總數。請明確傳入 workspace_id。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：true。冪等提示：true。外部世界提示：false。
• 如何檢查結果：讀取同步回應。

sosoapi_request_provider_insights

請求平台提供某帳號或單則貼文的洞察，可指定日期範圍（最多 366 天）。回傳 request_id，命中快取時也回傳結果；否則輪詢 sosoapi_get_provider_insight_status。

• 傳輸方式：stdio、http。
• 必要授權：agent:operate。路由最低角色：viewer。
• 唯讀提示：false。冪等提示：false。外部世界提示：true。
• 如何檢查結果：讀取平台結果，或結果不可用的原因。

sosoapi_retry_scheduled_post

重試失敗的排程貼文，可選擇新的 scheduled_at。需要 expected_version。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_update_scheduled_post

編輯尚未派送的排程貼文（caption、hashtags、media、link、time）。需要最新讀取中的 expected_version；過期版本會被拒絕。

• 傳輸方式：stdio、http。
• 所需授權：agent:publish。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

sosoapi_upload_asset

將本機圖片或影片檔案上傳到工作空間素材庫並登記為素材。僅接受來自工作目錄、暫存目錄、Pictures/Movies/Videos 或 SOSOAPI_UPLOAD_ROOTS 的真實 PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG 檔案，最大 500 MiB；拒絕點開頭的檔案和資料夾。回傳供排程貼文媒體使用的素材 id 和 URL。

• 傳輸方式：stdio。
• 必要授權：agent:operate。路由最低角色：editor。
• 唯讀提示：false。冪等提示：true。外部世界提示：true。
• 如何檢查結果：讀取同步回應。