Multica ChatGPT Connector

通用、多用户的 Multica Cloud 连接器第一版。一个公网 MCP 地址，每位用户独立绑定账号与工作区。运行于 Node.js / Vercel Functions，使用 PostgreSQL 持久化授权状态。

当前交付是可运行的服务源码和集成测试。生产授权配置、真实 Multica 联调、ChatGPT 手机端验收及目录审核是独立的发布步骤，不能由单元/模拟测试替代。

第一版能力

OAuth Authorization Code + PKCE S256；预注册的 confidential client，支持 Basic / POST 客户端认证。
专用网页绑定 Multica Personal Access Token，验证 /api/me，手动选择工作区与权限。
AES-256-GCM 加密 PAT，关联授权 ID 作为 AAD；不把 PAT 传给 ChatGPT。
15 分钟访问令牌，30 天刷新有效期，授权最长 90 天。刷新轮换与重放撤销、单次授权码、持久化撤销检查。
无状态 Streamable HTTP MCP；每个请求独立构造 server / transport。
11 个工具：连接信息、项目/Agent 列表、任务搜索/详情、创建/分配、运行列表/输出、重跑/取消。
写操作使用 PostgreSQL 唯一键防止同一请求重复派发；不确定的上游结果进入 unknown 状态，必须查询后人工判断。
安全默认值：未配置时首页显示待配置，/health、OAuth 与 MCP 返回 503。

任务仍由 Multica 的执行环境运行。连接器不会在 Vercel 请求内运行长任务。

不要求开发者提供个人 dashboard 地址。V1 只支持 Multica Cloud。多实例、自托管和 Multica 原生第三方 OAuth 是后续适配范围。

要求 Node.js 22+。

npm ci
npm test
npm run check

测试使用真实 PostgreSQL 引擎的 PGlite 和模拟 Multica HTTP 响应，不需要生产凭据。覆盖 OAuth 全流程、PKCE、回调校验、CSRF、scope、跨用户/工作区隔离、刷新重放、撤销、并发幂等和写入超时。

本地运行需要配置 .env。Node 不会自动加载该文件：

node --env-file=.env scripts/migrate.js
node --env-file=.env scripts/serve.js

授权表单使用 Secure Cookie。浏览器授权联调必须经过 HTTPS 域名或安全开发隧道，不能使用普通 HTTP 浏览器页面。不要在聊天中提供 PAT、数据库密码或 OAuth secret。

将仓库导入 Vercel，Framework 选择 Other，Node.js 22，使用仓库中的 vercel.json。安装命令使用 npm ci（包括构建依赖），构建命令为 npm run build，输出目录保持默认。构建会把运行依赖合并成 dist/server.cjs，函数入口只加载这一份产物。
在 Vercel Marketplace 创建托管 PostgreSQL（如 Neon），使用供应商要求的 TLS 连接配置。DATABASE_URL 使用连接池 URL。
在 Vercel 环境变量配置 .env.example 中的六项配置。生成两个独立秘密，分别用于 AES 与 OAuth 客户端认证：
```
openssl rand -base64 32
openssl rand -hex 32
```
CONNECTOR_ORIGIN 为稳定的生产 HTTPS origin。OAUTH_REDIRECT_URIS 必须来自 ChatGPT 应用管理界面的实际回调值，以 JSON 数组形式填写，禁止通配符。
先链接 Vercel 项目并安全拉取真实环境，再执行 npm run migrate；不要用临时/占位数据库配置跳过部署检查。重新部署后 /health 应返回 {"status":"ok"}。
每天运行一次 npm run cleanup（运营方调度的数据库维护任务）；它清除过期会话、过期/撤销授权与相关凭据及操作记录。活跃授权的刷新令牌历史保留，以检测重放。

已有 Vercel CLI 登录会话时：

vercel link
vercel env pull .env.local
node --env-file=.env.local scripts/migrate.js
vercel --prod

/mcp 和 OAuth metadata 必须可被 ChatGPT 访问。OAuth 回调使用稳定生产域名。不要把变化的 preview URL 注册成生产 issuer。建议在 Vercel WAF 配置按来源的限流；内置数据库限流会在反向代理后合并来源，适合作为兜底限额。

配置	值
MCP transport	Streamable HTTP
MCP endpoint	`<CONNECTOR_ORIGIN>/mcp`
Issuer	`<CONNECTOR_ORIGIN>`
Authorization URL	`<CONNECTOR_ORIGIN>/oauth/authorize`
Token URL	`<CONNECTOR_ORIGIN>/oauth/token`
Authentication	OAuth，填入对应的 Client ID / Secret
Scope	`catalog:read issues:read issues:write runs:read runs:start runs:control`
Resource	与 MCP endpoint 完全一致

支持预注册客户端；不宣告 DCR/CIMD。用户可在同意页缩小权限。需要更多权限时重新连接。生产服务只有一个客户端配置；另一个 OAuth 客户端应单独部署或扩展 client registry，不能共享 secret。

plugins/multica 是附带的 Codex 插件包装，服务未部署前不包含虚假 MCP 地址：

node scripts/configure-plugin.js https://your-stable-connector-domain

这一步仅生成 endpoint 配置，不会自动发布、安装或通过 ChatGPT 应用目录审核。ChatGPT 手机端实际可用性需要在目标账号/客户端完成连接后验收。

工具	所需权限	行为
get_connection / list_projects / list_agents	catalog:read	查询已授权范围
search_issues / get_issue	issues:read	搜索和任务详情
create_issue	issues:write	创建未分配任务
assign_issue	issues:write；启动时另需 runs:start	`start_run=false` 发送 `suppress_run=true`
list_issue_runs / get_run_output	runs:read	查询执行历史与输出
rerun_issue	runs:start	使用当前分配启动一次新运行
cancel_run	runs:control	校验 issue/run 关系后取消指定运行

所有写工具标记为可能产生副作用。ChatGPT 应先说明目标和操作并取得用户同意；服务端只信任 OAuth 权限与校验后的参数。运行完成与任务状态分别展示。分配已有任务不会自动取消旧运行。

Multica app API /api/* 并非全部属于稳定的 public API v1。接口核对基于 multica-ai/multica 提交 7a438bd5b8bf39afd54259a7eb0971390e50a8ef；未来改动可能需要更新适配器。
不进行自动重试的写操作也无法实现跨系统严格 exactly-once。unknown/pending 记录禁止自动重发；请查询 Multica 当前状态后决定下一步。
输出最大读取 2 MB，返回到模型的运行输出最多末尾 30,000 字符；超限读取明确报错。V1 不提供日志流式订阅、主动通知或定时派发服务。
密钥轮换需要先撤销连接或增加带版本的密钥环；直接替换 AES 密钥会使旧凭据不可解密。
长期运营需配置清理任务、数据库备份策略、监控、支持联系方式和完整服务条款。首页的隐私说明是第一版默认文案，公开目录发布前需补充运营方信息。

MIT. This is an independent integration and is not an official Multica or OpenAI product.