# SosoAPI MCP 工具參考資料

標準 URL： https://sosoapi.ai/zh-tw/docs/social-media-mcp-tools

使用此參考查找工具並檢查所需欄位。涵蓋 sosoapi 0.5.9：core 設定在本機提供 28 個工具，透過 HTTP 提供 27 個；full 在本機提供 106 個，透過 HTTP 提供 105 個。日常任務選擇 core；還需管理功能則選擇 full。兩者權限相同。項目根據伺服器和能力目錄產生；請檢查已連結用戶端的 tools/list，瞭解其可用工具。

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

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

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

- [設定 Claude Code 或 Codex](https://sosoapi.ai/zh-tw/docs/claude-code-codex-social-publishing)

- [Threads 文字與圖片操作範例](https://sosoapi.ai/zh-tw/docs/threads-api-publishing)

- [平台能力對照表](https://sosoapi.ai/zh-tw/docs/publishing-capabilities)

- [下載確切 core 輸入 schema 和註解（JSON）](https://sosoapi.ai/mcp-tools.json)

## 如何理解此參考

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

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

- [npm 上的 sosoapi](https://www.npmjs.com/package/sosoapi)

- [官方 MCP Registry：ai.sosoapi/sosoapi（JSON）](https://registry.modelcontextprotocol.io/v0.1/servers/ai.sosoapi%2Fsosoapi/versions)

## sosoapi_bulk_create_scheduled_posts

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

- 傳輸方式：stdio、http。

- 所需授權：agent:publish。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string \| null | 否 |

| source_ref | object \| null | 否 |

| targets | array (object) | 是 |

## sosoapi_cancel_scheduled_post

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

- 傳輸方式：stdio、http。

- 所需授權：agent:publish。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

## sosoapi_create_comment

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

- 傳輸方式：stdio、http。

- 所需授權：agent:engage。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取平台確認的結果；已加入佇列的操作仍為待處理。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| social_account_id | string | 是 |

| target | object \| object | 是 |

| message | string | 是 |

| idempotency_key | string | 是 |

## 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。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string \| null | 否 |

| social_account_id | string | 是 |

| caption | string \| null | 否 |

| hashtags | array (string) | 否 |

| media | array (object) | 否 |

| link_url | string \| null | 否 |

| provider_payload | object \| object \| object \| object \| object | 是 |

| scheduled_at | string | 是 |

| display_timezone | string | 否 |

| local_scheduled_at | string | 否 |

| schedule_dst_disambiguation | "exact" \| "earlier" \| "later" | 否 |

| expires_at | string \| null | 否 |

| source_ref | object \| null | 否 |

| automatic_retry_enabled | boolean | 否 |

| idempotency_key | string | 是 |

## sosoapi_get_asset

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| id | integer \| string | 是 |

| include_version | boolean | 否 |

## 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。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| import_id | string | 是 |

| include_asset | boolean | 否 |

## 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。

- 如何檢查結果：讀取平台確認的結果；已加入佇列的操作仍為待處理。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| action_id | string | 是 |

## sosoapi_get_organization_context

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| organization_id | string | 否 |

## sosoapi_get_provider_insight_status

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取平台結果，或結果不可用的原因。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| request_id | string | 是 |

## sosoapi_get_scheduled_post

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

## 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。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| include_quota | boolean | 否 |

| targets | array (object) | 是 |

## sosoapi_get_workspace_context

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。

- 唯讀提示：false。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| include_version | boolean | 否 |

## 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。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| text | string | 否 |

## 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。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| source_url | string | 是 |

| idempotency_key | string | 是 |

| expected_kind | "image" \| "video" | 否 |

| title | string | 否 |

| description | string | 否 |

| tags | array (string) | 否 |

## sosoapi_job_status

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| job_id | string | 是 |

## sosoapi_list_connected_accounts

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：帳號資訊；無固定的 Workspace 角色。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| include_authorization_grant | boolean | 否 |

## sosoapi_list_monitored_posts

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| cursor | string | 否 |

| page_size | integer | 否 |

| filters | object | 否 |

| order | "provider_published_at_desc_social_post_id_desc" | 否 |

## sosoapi_list_post_comments

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| cursor | string | 否 |

| page_size | integer | 否 |

| filters | object | 否 |

| order | "observation_at_desc_comment_version_desc_comment_observation_id_desc" | 否 |

## sosoapi_list_publication_attentions

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| status | "open" \| "resolved" | 否 |

| scheduled_post_id | string | 否 |

| limit | integer | 否 |

| offset | integer | 否 |

## sosoapi_list_scheduled_posts

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string | 否 |

| status | "scheduled" \| "publishing" \| "published" \| "failed" \| "expired" \| "needs_reschedule" \| "cancelled" \| "deleted" | 否 |

| scheduled_from | string | 否 |

| scheduled_to | string | 否 |

| limit | integer | 否 |

| cursor | object | 否 |

## 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。讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| source_url | string | 是 |

| post | object | 是 |

| import_id | string | 否 |

## sosoapi_publish_scheduled_post_now

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

- 傳輸方式：stdio、http。

- 所需授權：agent:publish。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

## sosoapi_query_assets

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：true。冪等提示：true。外部世界提示：false。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| asset_type | "text" \| "image" \| "video" \| "audio" \| array ("text" \| "image" \| "video" \| "audio") | 否 |

| source | string | 否 |

| tag | string | 否 |

| limit | integer | 否 |

| offset | integer | 否 |

| include_version | boolean | 否 |

## sosoapi_request_provider_insights

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

- 傳輸方式：stdio、http。

- 必要授權：agent:operate。路由最低角色：viewer。

- 唯讀提示：false。冪等提示：false。外部世界提示：true。

- 如何檢查結果：讀取平台結果，或結果不可用的原因。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| social_account_id | string | 是 |

| resource_kind | "account" \| "post" | 是 |

| provider_resource_id | string | 否 |

| start_date | string | 否 |

| end_date | string | 否 |

| include_audience | boolean | 否 |

| refresh | boolean | 否 |

## sosoapi_retry_scheduled_post

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

- 傳輸方式：stdio、http。

- 所需授權：agent:publish。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

| scheduled_at | string | 否 |

## sosoapi_update_scheduled_post

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

- 傳輸方式：stdio、http。

- 所需授權：agent:publish。路由最低角色：editor。

- 唯讀提示：false。冪等提示：true。外部世界提示：true。

- 如何檢查結果：讀取終端發布結果；排程已接受後仍處於待處理狀態。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

| patch | object | 是 |

| provider_payload | object \| object \| object \| object \| object | 否 |

## 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。

- 如何檢查結果：讀取同步回應。

頂層輸入；巢狀規則和約束請參見 JSON

| 輸入 | 類型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| file_path | string | 是 |

| idempotency_key | string | 是 |

| content_type | string | 否 |

| title | string | 否 |

| description | string | 否 |

| tags | array (string) | 否 |

| metadata | object | 否 |