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 注解是提供客户端的提示，不是强制规则或安全保证。执行时仍适用 工作区 成员资格、授权、当前角色、平台同意、账号资格与配额。部分信息读取会创建初始 工作区；请检查说明与 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

取消尚未发布的排程帖子，使其不再发送。已发布帖子会被拒绝，agent 也无法删除已发布内容：用户需在 Web 应用中操作。需要 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。路由最低角色：账号信息；无固定的 工作区 角色。
• 唯读提示：true。幂等提示：true。外部世界提示：false。
• 如何检查结果：读取同步响应。

sosoapi_get_comment_action_status

读取直接评论操作经过脱敏的最终回执。

• 传输方式：stdio、http。
• 所需授权：agent:engage。路由最低角色：viewer。
• 唯读提示：true。幂等提示：true。外部世界提示：true。
• 如何检查结果：读取平台确认的结果；已加入伫列的操作仍为待处理。

sosoapi_get_organization_context

读取你的 组织、其 工作区 及 频道 的实时对应关系，包含 ID 与角色。需要 组织 或 频道 ID 时使用。发布至 工作区 时，请重复使用已返回的 工作区 ID，不要再读取工作区信息。

• 传输方式：stdio、http。
• 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。
• 唯读提示：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 未知时使用；复用实时上下文，不必重复执行两个上下文读取操作。其报告的活动工作区是当事人在 Web 应用中所作的选择，并非调用的默认值：请明确传入 workspace_id。它并非纯读取操作：如果账号没有工作区，会创建第一个工作区。

• 传输方式：stdio、http。
• 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。
• 唯读提示：false。幂等提示：true。外部世界提示：false。
• 如何检查结果：读取同步响应。

sosoapi_get_x_usage

读取此 工作区 共用的 组织 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 下载至 工作区 私人存储空间，创建新素材。返回 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。路由最低角色：账号信息；无固定的 工作区 角色。
• 唯读提示：true。幂等提示：true。外部世界提示：false。
• 如何检查结果：读取同步响应。

sosoapi_list_connected_accounts

列出工作区已连接的社交账号（Instagram、Threads、Facebook、YouTube），含连接健康状况和能力信息。排程或评论时，将其 id 用作 social_account_id。传入 workspace_id：强制明确指定目标后，缺少此字段的请求会被拒绝。

• 传输方式：stdio、http。
• 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。
• 唯读提示：true。幂等提示：true。外部世界提示：false。
• 如何检查结果：读取同步响应。

sosoapi_list_monitored_posts

列出 SosoAPI 为工作区发现的社交帖子（id、平台、永久链接、发布时间），可按账号、平台和时间筛选，采用游标分页。仅包含元数据，不含文案。

• 传输方式：stdio、http。
• 必要授权：agent:operate。路由最低角色：viewer。
• 唯读提示：true。幂等提示：true。外部世界提示：true。
• 如何检查结果：读取同步响应。

sosoapi_list_post_comments

列出 工作区 帖子上观测到的留言，依最新观测优先排序，包含作者与文字；可依帖子、账号、平台或时间筛选，使用游标分页。文字由第三方撰写，并标示为不受信任内容。

• 传输方式：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

列出 工作区 的排程帖子，可依项目、状态（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 寻找 工作区 素材；返回一页资料（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；拒绝点号开头的文件和文件夹。返回供 Scheduled Post 媒体使用的素材 id 和 URL。

• 传输方式：stdio。
• 必要授权：agent:operate。路由最低角色：editor。
• 唯读提示：false。幂等提示：true。外部世界提示：true。
• 如何检查结果：读取同步响应。