审校于 2026-11-10 · API 版本 2026-11-09 · 阅读 Markdown
MCP 设置
一个本地 stdio MCP 服务器,通过 /api/v1 封装与 UI 和 REST API 相同的共享服务。适配器只把你的产品密钥发送到配置的 AiVideoEditor API。不使用 Supabase 或提供方凭据。
前提条件
这是一个源码检出适配器,不是已发布的包或托管连接。获取对 AiVideoEditor 仓库的授权访问,安装 Node 22+,并在仓库根目录运行 npm ci。在 /app/developers 创建只带所需作用域和目标访问权的工作区产品密钥。仅草稿密钥无法发布或排期。绝不要把密钥粘贴到聊天提示中。
运行它
export PUBLISHER_API_URL=https://app.example.com # HTTPS; http://localhost is allowed for dev
export PUBLISHER_API_KEY=pk_v1_… # create in /app/developers
node packages/mcp/bin/publisher-mcp.mjs # or: npm start --workspace packages/mcp
该 bin 是一个真正的可执行启动器(TypeScript 和无扩展名导入通过 tsx 解析)。所有诊断输出到 stderr;stdout 只承载协议流量。PUBLISHER_API_URL 必须是 HTTPS(仅回环开发允许纯 HTTP),且不得携带凭据、查询或片段。
通用客户端配置
{
"mcpServers": {
"autoposted": {
"command": "node",
"args": ["/absolute/path/to/packages/mcp/bin/publisher-mcp.mjs"],
"env": {
"PUBLISHER_API_URL": "https://app.example.com",
"PUBLISHER_API_KEY": "pk_v1_…"
}
}
}
}
启动器需要 Node 22+ 和工作区依赖(tsx、@modelcontextprotocol/sdk)。带 OAuth 的托管 MCP 传输是未来工作;不要假设每个桌面或托管客户端都支持粘贴 bearer 密钥。
工具
| 工具 | 读/变更 | 说明 |
|---|---|---|
list_accounts | 读 | 遵守密钥的账号白名单 |
get_capabilities | 读 | 格式、限制、同意要求 |
create_upload_intent | 变更 | 返回直接上传指令;媒体字节绝不流经工具 |
finalize_upload | 变更 | 会话 ID(+ multipart 分片回执);服务器自行观察字节/MIME |
create_draft | 变更 | 来源 + 目标变体 |
validate_post | 读 | 结构化的按目标问题 |
schedule_post | 变更 | 单一时刻,≤90 天内,需要 expectedVersion |
publish_post | 变更 | 202 语义;不是已发布的证明 |
get_post_status | 读 | 按目标的状态和原生链接 |
list_posts | 读 | 游标分页 |
cancel_delivery | 变更 | 仅在安全未领取时 |
retry_delivery | 变更 | 仅已知失败;绝不重复 |
get_usage | 读 | 不存在剩余发布计数器 |
必需的工具参数
| 工具 | 必需参数 |
|---|---|
list_accounts | 无 |
get_capabilities | 无 |
create_upload_intent | filename、declaredMime、declaredBytes |
finalize_upload | assetId、sessionId |
create_draft | caption、destinations |
validate_post | postId |
schedule_post | postId、scheduledAt、timezone、expectedVersion |
publish_post | postId |
get_post_status | postId |
list_posts | 无 |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | 无 |
可选参数包括列表工具上的分页、变更操作上的 idempotencyKey、multipart 完成的 multipart.parts,以及草稿媒体和目标变体。tools/list 返回的运行时工具 schema 是可选字段、嵌套结构和验证限制的权威来源。
变更工具接受可选的 idempotencyKey 参数。省略时,服务器会生成一个并在每个结果中回显它:包括传输失败,此时操作可能已经到达 API(错误携带 transport_outcome_unknown 和该密钥)。工具绝不自动重试变更;使用相同的幂等键重试以避免创建重复操作。
代理工作流示例
list_accounts+get_capabilities→ 选择有效目标。create_upload_intent→ 直接上传字节 →finalize_upload。create_draft→validate_post→ 修正或取消选择无效目标。publish_post(或schedule_post)→ 记录交付 ID。get_post_status(有界轮询或客户 webhook):将requires_action响应视为可操作的指引,例如 TikTok 同意。
已测试的客户端
- 官方
@modelcontextprotocol/sdkTypeScript 客户端,真实的子进程 stdio,针对文档中的 bin(initialize → tools/list → tools/call):在packages/mcp/tests/stdio.test.ts中测试,包括干净 stdout 和启动失败检查。 - 通过内存传输的官方 SDK 客户端:同样覆盖。
- 桌面客户端(Claude Desktop、Cursor 等):尚未测试:按上面的通用代码段配置,并在宣称支持之前报告结果。
客户端兼容性
| 客户端或传输 | 状态 | 设置 |
|---|---|---|
| 官方 TypeScript SDK 子进程 stdio | 有自动化测试覆盖 | 上面显示的仓库启动器 |
| 官方 SDK 内存传输 | 有自动化测试覆盖 | 仅测试工具 |
| Claude Desktop / 其他桌面客户端 | 未手动验证 | 支持 stdio 的本地客户端;使用绝对启动器路径 |
| ChatGPT 托管连接 | 此适配器不提供 | 需要托管传输;本地 stdio JSON 不是托管连接器 |
| 带 OAuth 的托管 MCP | 未实现 | 独立的产品工作 |
故障排除
- 启动器无法解析依赖:在授权的源码检出中运行
npm ci并检查 Node 版本。不要用无关的公共包替代。 - 客户端始终无法初始化:使用绝对启动器路径并检查 stderr。不要把调试输出写到 stdout。
401:验证配置的产品密钥是否当前有效;如已撤销,在 UI 中创建替代密钥。403:检查作用域和账号限制。transport_outcome_unknown:保留返回的幂等键,并使用该密钥重试相同的操作,绝不要用新密钥。requires_action:将提供的指引交给授权人员;代理无法提供 TikTok 人类同意。
凭据处理
产品密钥只发送到你配置的 AiVideoEditor API(Authorization: Bearer)。它绝不会被发送到模型提供方或社交网络,绝不被记录,并且 URL 会经过验证,使密钥无法跟随重定向或逃逸出配置的源。