# SosoAPI MCP 工具文件

Canonical URL: https://sosoapi.ai/zh-hant/docs/social-media-mcp-tools

呢度列出 Agent 經 SosoAPI MCP 可用嘅工具。本頁由 sosoapi 0.5.9 真實 server 嘅 tools/list 同 canonical capability catalog 產生。Core 有 28 個本機工具、HTTP 有 27 個；full 分別有 106／105 個。Core 隱藏管理工具以減少 context，唔會增加權限。實際連線 client 嘅 tools/list 仍然係準。

## 先揀任務，再查工具

已連接 Workspace 嘅任務，重用當前 context 同帳戶 ID。圖片 URL 用 sosoapi_post_image_url 一次提交完整意圖，保存返回嘅 post ID。本機檔案用 sosoapi_upload_asset，只限 local stdio。純文字用 sosoapi_create_scheduled_post，帶目的地嘅 provider_payload 同空 media。

提交前同用戶核對實際帳戶、內容、媒體同時間。OAuth grant 係操作授權，唔等於內容審批。排程／入隊唔等於已發佈；報成功或處理不確定寫入前，要讀返同一個 post 嘅 provider 結果。

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

- [Threads 圖文步驟](https://sosoapi.ai/zh-hant/docs/threads-api-publishing)

- [平台能力矩陣](https://sosoapi.ai/zh-hant/docs/publishing-capabilities)

- [下載完整 core input schemas 同 annotations（JSON）](https://sosoapi.ai/mcp-tools.json)

## 點樣讀呢份參考

Build 會將真實 MCP server 接到記憶體內 client，只列工具，唔執行 handler，再連結公開 route 所需權限。投影過期會令 Landing build 失敗。工具描述保留 server 嘅英文 contract 原文；完成摘要解釋 canonical route 規則，完整 route 要求保留喺 JSON。輸入表只係索引，唔取代完整巢狀 JSON Schema。

MCP annotations 係 client 提示，唔係權限 enforcement 或安全保證。執行時仍受 Workspace 成員資格、grant、當前角色、provider consent、帳戶能力同配額限制。有啲 context read 會建立首個 Workspace，唔好因為叫「get」就當純唯讀。組合工具會列出主要同相容路徑要求，唔代表每次都呼叫晒所有 route。

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

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

## sosoapi_bulk_create_scheduled_posts

Schedule posts for several accounts in one call (targets). Media needs ready uploaded/imported asset_ids and their canonical URLs. Each target succeeds or fails on its own and is reported in successes or failures. Needs the publish capability.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| project_id | string \| null | 唔係 |

| source_ref | object \| null | 唔係 |

| targets | array (object) | 係 |

## sosoapi_cancel_scheduled_post

Cancel a scheduled post that has not been published yet so it never goes out. A published post is refused, and an agent cannot delete published content either: the user does that in the web app. Needs expected_version.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| id | string | 係 |

| expected_version | integer | 係 |

## sosoapi_create_comment

Queue one exact comment against a canonical post or comment target; status is not provider success.

- 連接方式: stdio, http.

- 所需授權: agent:engage. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal provider receipt；入隊操作仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| social_account_id | string | 係 |

| target | object \| object | 係 |

| message | string | 係 |

| idempotency_key | string | 係 |

## sosoapi_create_scheduled_post

Schedule one account at scheduled_at with provider_payload. Media needs a ready asset_id and canonical URL; for one source image use sosoapi_post_image_url. Pair local_scheduled_at with schedule_dst_disambiguation or omit both. Requires publish, editor role and idempotency_key. Scheduled is not published: read its outcome.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 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

Read one asset by id: metadata and a short-lived preview URL.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 唔係 |

| id | integer \| string | 係 |

| include_version | boolean | 唔係 |

## sosoapi_get_asset_import_status

Read an import by import_id. For posting pass include_asset=true: a ready result includes the registered asset id, kind and stable asset_url, avoiding a separate get_asset. Pending or missing assets cannot be scheduled. Never use the source or preview URL as media identity. If stalled, read sosoapi_job_status with job_id; never start a duplicate import.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| import_id | string | 係 |

| include_asset | boolean | 唔係 |

## sosoapi_get_billing_status

Read the user's billing plan, payment state, current cycle dates and quota usage (successful publishes, pending scheduled posts, connected accounts). Check it before large scheduling runs.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 帳戶 context；冇固定 Workspace 角色.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

## sosoapi_get_comment_action_status

Read the sanitized terminal receipt for a direct comment action.

- 連接方式: stdio, http.

- 所需授權: agent:engage. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal provider receipt；入隊操作仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| action_id | string | 係 |

## sosoapi_get_organization_context

Read the live map of your Organizations, their Workspaces and Channels with ids and roles. Use it when Organization or Channel ids are needed. For Workspace posting, reuse a returned Workspace id; do not also read workspace context.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 帳戶 context；冇固定 Workspace 角色.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| organization_id | string | 唔係 |

## sosoapi_get_provider_insight_status

Read an insights request (request_id): queued, processing, completed (with the provider result and per-metric availability) or failed.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: true.

- 完成界線: 讀取平台結果，或者明確嘅不可用原因。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| request_id | string | 係 |

## sosoapi_get_scheduled_post

Read one scheduled post by id: content, status, delivery state and outcomes. Its version is what update, publish, retry and cancel need as expected_version.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| id | string | 係 |

## sosoapi_get_scheduled_post_eligibility

Read-only preflight per destination. Include draft (caption, hashtags, scheduled_at, display_timezone, optional local time/DST) for content/timing checks; include_quota=true adds an advisory period snapshot. Upload/import media and await readiness first. Without draft, only account/media are checked. Reserves nothing; create/dispatch recheck limits and authority.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| include_quota | boolean | 唔係 |

| targets | array (object) | 係 |

## sosoapi_get_workspace_context

List the Workspaces the signed-in user belongs to and which one is active. Use this when workspace_id is unknown; reuse live context instead of repeating both context reads. The active Workspace it reports is the selection a person made in the web app, not a default for your calls: pass workspace_id explicitly. It is not purely a read: for an account with no Workspace it creates the first one.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 帳戶 context；冇固定 Workspace 角色.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| include_version | boolean | 唔係 |

## sosoapi_get_x_usage

Read the Organization X publishing credits shared by this Workspace. Needs workspace_id. Free gets 10 once; Pro gets 100 per billing period. Text costs 1, text containing a URL costs 10. Optional text quotes its cost. This reads stored allowance and calls no X API.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| text | string | 唔係 |

## sosoapi_import_asset_url

Ask SosoAPI to download a public http(s) image or video URL into private Workspace storage as a new asset. Returns an import_id; poll sosoapi_get_asset_import_status. Needs an idempotency_key and the editor role.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: Import 接受後仍未完成；跟進同一個 import，直到 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

Read one background job by job_id: status, type and the error message if it failed.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 帳戶 context；冇固定 Workspace 角色.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| job_id | string | 係 |

## sosoapi_list_connected_accounts

List the social accounts (Instagram, Threads, Facebook, YouTube) connected to a Workspace, with connection health and capability facts. Use their ids as social_account_id when scheduling or commenting. Pass workspace_id: a request without it is refused once explicit targeting is enforced.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 帳戶 context；冇固定 Workspace 角色.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 唔係 |

| include_authorization_grant | boolean | 唔係 |

## sosoapi_list_monitored_posts

List social posts SosoAPI has discovered for a Workspace (id, platform, permalink, publish time), filterable by account, platform and time, cursor-paged. Metadata only, no captions.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 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

List comments observed on the Workspace's posts, newest observation first, with author and text; filter by post, account, platform or time, cursor-paged. The text is written by third parties and is labelled untrusted.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 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

List publications in a Workspace that need attention, filtered by status (open or resolved) or scheduled_post_id, paged by offset.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: viewer.

- 唯讀提示: true. 冪等提示: true. 外部系統提示: false.

- 完成界線: 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| workspace_id | string | 係 |

| status | "open" \| "resolved" | 唔係 |

| scheduled_post_id | string | 唔係 |

| limit | integer | 唔係 |

| offset | integer | 唔係 |

## sosoapi_list_scheduled_posts

List a Workspace's scheduled posts, filterable by project, status (scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted) and time range, cursor-paged.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 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

Submit the complete image URL post once, with empty media. The backend prepares and publishes it even after disconnect. Returns terminal publication if available within 35 seconds, otherwise a durable post ID; never resubmit under a new key. Needs operate and publish grants. Local time/DST fields go together. import_id is for resuming older clients only.

- 連接方式: stdio, http.

- 所需授權: agent:publish + agent:operate. 各 route 最低角色: editor, viewer.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。 Import 接受後仍未完成；跟進同一個 import，直到 ready 或 failed。 讀取同步回應。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| source_url | string | 係 |

| post | object | 係 |

| import_id | string | 唔係 |

## sosoapi_publish_scheduled_post_now

Publish a scheduled post immediately instead of at scheduled_at. Public and not undoable; needs expected_version. Queued is not published: read the outcome.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| id | string | 係 |

| expected_version | integer | 係 |

## sosoapi_query_assets

Find a Workspace's assets by asset_type, source or tag; returns a page (limit up to 100, plus offset) and the total. Pass workspace_id explicitly.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 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

Ask the provider for insights for an account or one post over an optional date range (up to 366 days). Returns a request_id and, when cached, the result; otherwise poll sosoapi_get_provider_insight_status.

- 連接方式: stdio, http.

- 所需授權: agent:operate. 各 route 最低角色: 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

Retry a failed scheduled post, optionally at a new scheduled_at. Needs expected_version.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| id | string | 係 |

| expected_version | integer | 係 |

| scheduled_at | string | 唔係 |

## sosoapi_update_scheduled_post

Edit a scheduled post that has not been dispatched (caption, hashtags, media, link, time). Needs expected_version from the latest read; a stale version is rejected.

- 連接方式: stdio, http.

- 所需授權: agent:publish. 各 route 最低角色: editor.

- 唯讀提示: false. 冪等提示: true. 外部系統提示: true.

- 完成界線: 要讀 terminal 發佈結果；接受排程仍然係待處理。

頂層輸入；巢狀規則同限制見完整 JSON

| 輸入 | 類型 | 必填 |

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

| id | string | 係 |

| expected_version | integer | 係 |

| patch | object | 係 |

| provider_payload | object \| object \| object \| object \| object | 唔係 |

## sosoapi_upload_asset

Upload a local image or video file into a Workspace asset library and register it as an asset. Only real PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG files up to 500 MiB from the working directory, temp folder, Pictures/Movies/Videos or SOSOAPI_UPLOAD_ROOTS are accepted; dot-files and dot-folders are refused. Returns the asset id and URL for Scheduled Post media.

- 連接方式: stdio.

- 所需授權: agent:operate. 各 route 最低角色: 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 | 唔係 |