SosoAPI MCP 工具文件

先揀任務，再查工具

已連接 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
• Threads 圖文步驟
• 平台能力矩陣
• 下載完整 core input schemas 同 annotations（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
• Official MCP Registry: ai.sosoapi/sosoapi (JSON)

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 發佈結果；接受排程仍然係待處理。

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 發佈結果；接受排程仍然係待處理。

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；入隊操作仍然係待處理。

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 發佈結果；接受排程仍然係待處理。

sosoapi_get_asset

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

• 連接方式: stdio, http.
• 所需授權: agent:operate. 各 route 最低角色: viewer.
• 唯讀提示: true. 冪等提示: true. 外部系統提示: false.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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；入隊操作仍然係待處理。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取平台結果，或者明確嘅不可用原因。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取同步回應。

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

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 發佈結果；接受排程仍然係待處理。

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.
• 完成界線: 讀取同步回應。

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.
• 完成界線: 讀取平台結果，或者明確嘅不可用原因。

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 發佈結果；接受排程仍然係待處理。

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 發佈結果；接受排程仍然係待處理。

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.
• 完成界線: 讀取同步回應。