# 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 请求内运行长任务。

## 授权流程

1. 用户在 ChatGPT 连接 Multica；ChatGPT 发起携带 `resource`、`state`、PKCE S256 的授权请求。
2. 用户在连接器网页输入自己的 `mul_…` PAT；凭据仅发往固定的 `https://api.multica.ai`。
3. 连接器展示该用户工作区。用户选择工作区、读权限以及可选写/启动/取消权限。
4. ChatGPT 用授权码换取连接器令牌；服务端按令牌、scope、workspace 与 Multica 当前权限验证每次操作。
5. 用户在 `/disconnect` 再次验证 PAT，可撤销此账号的全部连接。ChatGPT 也可调用标准 `/oauth/revoke`。

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

## 开发与测试

要求 Node.js 22+。

```bash
npm ci
npm test
npm run check
```

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

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

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

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

## Vercel 部署

1. 将仓库导入 Vercel，Framework 选择 Other，Node.js 22，使用仓库中的 `vercel.json`。安装命令使用 `npm ci`（包括构建依赖），构建命令为 `npm run build`，输出目录保持默认。构建会把运行依赖合并成 `dist/server.cjs`，函数入口只加载这一份产物。
2. 在 Vercel Marketplace 创建托管 PostgreSQL（如 Neon），使用供应商要求的 TLS 连接配置。`DATABASE_URL` 使用连接池 URL。
3. 在 Vercel 环境变量配置 `.env.example` 中的六项配置。生成两个独立秘密，分别用于 AES 与 OAuth 客户端认证：

   ```bash
   openssl rand -base64 32
   openssl rand -hex 32
   ```

4. `CONNECTOR_ORIGIN` 为稳定的生产 HTTPS origin。`OAUTH_REDIRECT_URIS` 必须来自 ChatGPT 应用管理界面的实际回调值，以 JSON 数组形式填写，禁止通配符。
5. 先链接 Vercel 项目并安全拉取真实环境，再执行 `npm run migrate`；不要用临时/占位数据库配置跳过部署检查。重新部署后 `/health` 应返回 `{"status":"ok"}`。
6. 每天运行一次 `npm run cleanup`（运营方调度的数据库维护任务）；它清除过期会话、过期/撤销授权与相关凭据及操作记录。活跃授权的刷新令牌历史保留，以检测重放。

已有 Vercel CLI 登录会话时：

```bash
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 配置按来源的限流；内置数据库限流会在反向代理后合并来源，适合作为兜底限额。

## ChatGPT 配置

| 配置 | 值 |
|---|---|
| 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 地址：

```bash
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 密钥会使旧凭据不可解密。
- 长期运营需配置清理任务、数据库备份策略、监控、支持联系方式和完整服务条款。首页的隐私说明是第一版默认文案，公开目录发布前需补充运营方信息。

详细说明见 [实现说明](docs/implementation.md) 和 [设计方案](docs/design.md)。

## Sources

- [OpenAI 插件 OAuth](https://developers.openai.com/plugins/build/auth)
- [Vercel MCP 部署](https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel)
- [Multica 源代码](https://github.com/multica-ai/multica)
- [OAuth server library](https://github.com/node-oauth/node-oauth2-server)

## License

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