将 ChatCut MCP 插件从 Codex 桌面应用移植到 WorkBuddy —— 完整适配实录

将 ChatCut MCP 插件从 Codex 桌面应用移植到 WorkBuddy —— 完整适配实录2026-07-13 | 实战验证成功52 个 MCP 工具全部可用ChatGPT install instructions — ChatCut一、背景与动机ChatCut 是一款 AI 视频编辑工具官方仅提供 ChatGPT / Codex 桌面应用专用插件通过 Codex 插件市场安装并自动完成认证。WorkBuddy 是另一款 AI 助手平台同样支持 MCPModel Context Protocol连接器框架但 ChatCut 没有官方 WorkBuddy 版本。Codex 插件WorkBuddy 连接器我们需要在 WorkBuddy 中使用 ChatCut 的 52 个视频编辑工具剪辑、MG 动画、素材生成、字幕转录等就必须将插件移植适配。二、逆向分析从.mcp.json找到核心入口ChatCut 插件的 GitHub 仓库公开在https://github.com/ChatCut-Inc/agent-plugin。关键文件是插件根目录下的.mcp.json{ mcpServers: { chatcut: { url: https://api.chatcut.io/api/external-mcp/mcp, headers: { x-chatcut-mcp-surface: codex } } } }这就是移植的起点——一个远程 HTTP MCP 端点外加一个自定义头x-chatcut-mcp-surface: codex。Codex 桌面应用会自动处理认证但 WorkBuddy 没有。方法论提炼任何第三方 MCP 插件的移植第一步永远是读取其.mcp.json或.codex-plugin/plugin.json提取端点 URL、传输协议和自定义头。三、MCP 配置与初遇 403将.mcp.json中的关键信息提取出来写入 WorkBuddy 的 MCP 配置文件~/.workbuddy/mcp.json{ mcpServers: { chatcut: { url: https://api.chatcut.io/api/external-mcp/mcp, headers: { x-chatcut-mcp-surface: codex }, disabled: false } } }然后在 WorkBuddy 连接器管理页面启用chatcut。连接器状态显示已连接但实际调用时报错Streamable HTTP error: Error POSTing to endpoint: htmltitle403 Forbidden/title/html四、诊断与 OAuth 探路用curl直接探测端点curl -s -D - -X POST https://api.chatcut.io/api/external-mcp/mcp \ -H Content-Type: application/json \ -H x-chatcut-mcp-surface: codex \ -d {jsonrpc:2.0,method:initialize,id:1,...}响应头中发现了关键线索WWW-Authenticate: Bearer realmchatcut, ...服务器要求Authorization: Bearer token而不是 API Key 或 Cookie。这是一个标准 OAuth 2.0 保护资源。方法论提炼遇到 403/401 时先检查WWW-Authenticate响应头它会告诉你认证类型Bearer / Basic / Digest和资源元数据 URL。五、OAuth 元数据发现从WWW-Authenticate头中提取的资源元数据 URLhttps://api.chatcut.io/.well-known/oauth-protected-resource/api/external-mcp/mcp返回内容揭示了授权服务器{ authorization_servers: [https://api.chatcut.io], bearer_methods_supported: [header] }继续访问授权服务器元数据https://api.chatcut.io/.well-known/oauth-authorization-server得到完整的 OAuth 端点列表端点URL动态注册https://api.chatcut.io/auth/mcp/register授权https://api.chatcut.io/auth/mcp/authorize令牌交换https://api.chatcut.io/auth/mcp/token以及支持的授权方式authorization_coderefresh_tokenPKCES256。方法论提炼OAuth 保护资源的标准发现路径是.well-known/oauth-protected-resource→.well-known/oauth-authorization-server这是 RFC 9728 规范越来越多的 MCP 服务会采用。六、手动实现 OAuth 2.0 PKCE 流程6.1 动态客户端注册向注册端点提交请求curl -X POST https://api.chatcut.io/auth/mcp/register \ -H Content-Type: application/json \ -d { redirect_uris: [http://localhost:18930/callback], client_name: WorkBuddy MCP Client, grant_types: [authorization_code, refresh_token], response_types: [code], token_endpoint_auth_method: none, scope: openid profile email offline_access }服务器返回{ client_id: jLAvbQWfvKVjlmPBvBxqWqPZuYJlwVoa, client_secret: null, ... }注意token_endpoint_auth_method: none意味着这是一个公共客户端public client必须用 PKCE 保护授权码不需要 client_secret。6.2 PKCE 生成import base64, hashlib, secrets code_verifier base64.urlsafe_b64encode(secrets.token_bytes(32)).decode(ascii).rstrip() code_challenge base64.urlsafe_b64encode( hashlib.sha256(code_verifier.encode(ascii)).digest() ).decode(ascii).rstrip()6.3 浏览器授权构建授权 URL 并打开浏览器auth_url ( https://api.chatcut.io/auth/mcp/authorize? urlencode({ response_type: code, client_id: client_id, redirect_uri: http://localhost:18930/callback, code_challenge: code_challenge, code_challenge_method: S256, scope: openid profile email offline_access, resource: https://api.chatcut.io/api/external-mcp/mcp }) ) webbrowser.open(auth_url)用户在浏览器中登录 ChatCut 账户并点击授权浏览器重定向到本地回调http://localhost:18930/callback?codexxxxxxxx6.4 授权码交换令牌data urlencode({ grant_type: authorization_code, code: auth_code, redirect_uri: http://localhost:18930/callback, client_id: client_id, code_verifier: code_verifier # PKCE 关键参数 }).encode(utf-8) response urlopen(Request(TOKEN_URL, datadata, ...)) token_data json.loads(response.read()) # → access_token, refresh_token, expires_in36006.5 注入令牌到 MCP 配置拿到access_token后更新~/.workbuddy/mcp.json{ mcpServers: { chatcut: { url: https://api.chatcut.io/api/external-mcp/mcp, headers: { x-chatcut-mcp-surface: codex, Authorization: Bearer access_token }, disabled: false } } }七、验证与测试重启 WorkBuddy 后ChatCut 连接器显示52/52 工具全部加载成功。调用两个只读工具做最终验证list_projects→ 成功返回 1 个项目 Brilliant Pink Limpet (id: cd7a2652-00a2-4da7-b063-0eb4db713b6e)browse_library→ 成功返回素材库概览273 个素材 Motion Graphics (210) | Sound Effects (35) | Transitions (13) FX (9) | Zoom (4) | LUTs (2) | Audio FX (0)八、技能模块的移植ChatCut 插件不仅提供 MCP 工具还附带了 15 个技能模块Skill用于指导 AI 正确使用各种视频编辑功能。从仓库克隆并安装git clone --depth 1 https://github.com/ChatCut-Inc/agent-plugin.git /tmp/chatcut-plugin mkdir -p ~/.workbuddy/skills/chatcut cp -r /tmp/chatcut-plugin/chatcut/skills/* ~/.workbuddy/skills/chatcut/15 个技能子目录技能用途chatcut-plugin-basics基础操作上下文与启动指南asset-import视频音频素材导入create-motion-graphicsMG 动画制作export视频导出与渲染image-genAI 图片生成video-genAI 视频生成voiceTTS 旁白生成musicAI 音乐生成shader-genWebGL Shader 效果transcription字幕转录talking-head-guide口播视频指南verification操作验证检查known-errors已知问题与排障product-help产品功能帮助widget-forms交互表单组件九、令牌维护access_token有效期约 1 小时过期后需要刷新。刷新流程python scripts/chatcut_refresh.py脚本读取chatcut_token.json中的refresh_token向令牌端点申请新access_token并自动更新~/.workbuddy/mcp.json。十、方法论总结第三方 MCP 插件移植通用流程本次 ChatCut 适配的成功可以提炼为以下通用方法论适用于任何专为某个 AI 客户端设计的 MCP 插件移植到 WorkBuddy或其他支持自定义 MCP 配置的平台第一步提取 MCP 端点配置从插件仓库的.mcp.json、plugin.json或官方文档中找到MCP 端点 URL远程 HTTP / SSE / 本地 stdio自定义头 / 环境变量传输协议streamable-http/sse/stdio第二步写入目标平台 MCP 配置将提取的信息适配为目标平台格式。WorkBuddy 使用~/.workbuddy/mcp.json结构与 Codex 的.mcp.json相似但可能有字段名差异如mcpServersvsservers。第三步诊断认证障碍启用连接器后如果出现 403/401 错误用curl -D -探测端点检查响应头中的WWW-Authenticate按头中的提示访问.well-known/oauth-protected-resource和.well-known/oauth-authorization-server确定认证类型Bearer OAuth / API Key / Basic Auth第四步实现认证流程根据认证类型手动实现OAuth 2.0 PKCE动态注册 → PKCE 生成 → 浏览器授权 → 令牌交换 → 注入Authorization: BearerAPI Key直接注入headers或envBasic Auth注入Authorization: Basic base64第五步注入认证信息到 MCP 配置将获得的令牌/密钥写入 MCP 配置的headers或env字段重启或重新连接目标平台。第六步移植技能模块从插件仓库的skills/目录复制 SKILL.md 及附带资源到目标平台的 skills 目录。如果技能中有硬编码的原环境命令如codex plugin marketplace add需要替换或注释掉。第七步验证调用只读 MCP 工具如list_projects、browse_library确认连接正常检查工具数量是否与官方声称一致。第八步维护创建令牌刷新脚本记录令牌有效期提醒定期刷新。将完整流程保存为可复用 Skill。十一、完整适配架构图┌─────────────────────────────────────────────────────────────┐ │ WorkBuddy 平台 │ │ │ │ ~/.workbuddy/mcp.json │ │ ┌──────────────────────────────────────────────────┐ │ │ │ chatcut: { │ │ │ │ url: https://api.chatcut.io/.../mcp, │ │ │ │ headers: { │ │ │ │ x-chatcut-mcp-surface: codex, ← 伪装头 │ │ │ │ Authorization: Bearer token ← OAuth注入 │ │ │ │ } │ │ │ │ } │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ~/.workbuddy/skills/chatcut/ │ │ ├── 15 个技能子目录 (SKILL.md) │ │ │ chatcut-plugin-basics / asset-import / ... │ │ │ │ │ ~/.workbuddy/skills/chatcut-workbuddy-setup/ │ │ ├── SKILL.md (安装流程文档) │ │ ├── scripts/chatcut_oauth.py (OAuth 认证) │ │ └── scripts/chatcut_refresh.py (令牌刷新) │ │ │ │ → 52 个 MCP 工具全部可用 ✅ │ │ create_project / list_projects / import_media / │ │ edit_item / submit_export / browse_library / ... │ └─────────────────────────────────────────────────────────────┘ │ │ HTTPS Bearer Token ▼ ┌─────────────────────────────────────────────────────────────┐ │ ChatCut MCP 服务器 (api.chatcut.io) │ │ │ │ /auth/mcp/register → 动态客户端注册 │ │ /auth/mcp/authorize → 浏览器 OAuth 授权 │ │ /auth/mcp/token → 令牌交换 刷新 │ │ /api/external-mcp/mcp → MCP 工具端点 (52 工具) │ └─────────────────────────────────────────────────────────────┘十二、已知限制与展望限制说明令牌过期access_token ~1h需手动刷新或自动化非官方适配x-chatcut-mcp-surface: codex是伪装头ChatCut 可能未来校验更严格部分功能受限依赖 Codex 内置浏览器的功能如navigate_to_codex_page在 WorkBuddy 中无法使用动态注册不保证OAuth 客户端是动态注册的长期未使用可能失效展望如果 ChatCut 开放长期 API Key 或 WorkBuddy 官方集成 ChatCut以上限制将自然消除。在当前阶段本适配方案已经可以完整使用 ChatCut 的视频剪辑、MG 动画和素材生成三大功能板块。本文记录的完整工作流已保存为 WorkBuddy Skillchatcut-workbuddy-setup可通过 Skill 工具直接复用。