cursor2api

个人项目：把 Cursor 官方 SDK（@cursor/sdk）接到本地 Gateway / stdio MCP，给 Codex 主代理当 Worker，并提供 OpenAI Responses 文本兼容层。

推荐路径：

Sol（Codex 主代理）→ cursor2api MCP Worker → Cursor SDK → Grok 4.6

这不是完整的 Codex 模型 Provider，也不是原生跨 Provider subagent。Codex 原生子代理仍走 Codex 自己的模型配置；Grok 实现必须通过 Worker 工具。

只用官方 CURSOR_API_KEY，从 Cursor Dashboard → Integrations 创建。不要使用 Cursor 桌面 cookie 或非官方 API。

当前能力

可用：

• Worker：cursor_execute 执行一个有边界的任务；cursor_batch_execute 并行 1–3 个互不重叠的范围； 异步 cursor_start / cursor_status / cursor_result / cursor_followup / cursor_cancel 仍可用。

• 设置了 CURSOR_API_KEY 时使用真实 SdkCursorAdapter。WebUI 状态显示 backend=cursor 或 backend=fake。

• /v1/responses 文本 stream 与 non-stream。

• 隔离 Codex 会话可以把 model_provider = "cursor_relay" 指到本机 Gateway（仅文本路径）。

• WebUI：Overview、Setup、Models、Runs、Playground、Logs、Codex Setup、Settings。

不要指望：

• Function tool Capture/Resume（tool bridge 为 NO-GO）。/v1/responses 只保证文本，不保证完整工具循环。

• 原生 Codex 跨 Provider subagent。当前 Codex 子线程会继承父会话的 model_provider = "openai"，并拒绝 grok-4.6。日常 Grok 工作不要 spawn 原生 subagent。

未设置 CURSOR_API_KEY 时，生产路径不会静默落到 Fake Grok；/v1/responses 返回 missing_cursor_api_key。Fake 适配器仅在显式 CURSOR_BACKEND=fake（或测试注入）时启用。

Related MCP server: Code Worker MCP

快速开始（Windows）

需要 Node.js >=22.13。

如果希望由 Codex 自动完成安装与 MCP 注册，让它在解压后的仓库根目录阅读并执行 INSTALL.md。

cd cursor2api
npm.cmd install
copy .env.example .env
# 在 .env 填写 CURSOR_API_KEY 与 CURSOR_RELAY_API_KEY
npm.cmd run typecheck
npm.cmd run test
npm.cmd run lint

scripts\dev.ps1 一次启动 Gateway 与 WebUI（先 tsc -b）：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev.ps1

• WebUI：http://127.0.0.1:5173

• Gateway：http://127.0.0.1:8787 ，探活 http://127.0.0.1:8787/healthz

scripts\stop.ps1 同时关闭二者：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\stop.ps1

stdio MCP 由 Codex 拉起，不受这两个脚本管理。

环境变量

复制 .env.example 为 .env。Gateway 与 MCP stdio 都从本仓库根目录加载 .env，不依赖调用方 cwd。 不要把真实密钥写入仓库或本文档。

Gateway 默认监听 127.0.0.1:8787，数据目录 .data（scripts\dev.ps1 会设置 DATA_DIR）。

WebUI

打开 http://127.0.0.1:5173 。开发服务器把 /api、/v1、/healthz 代理到 Gateway。

Codex MCP 接入

先构建，再用绝对路径注册 stdio MCP（Codex 可能从任意 cwd 启动它）：

npm.cmd run typecheck
$node = (Get-Command node).Source
$script = (Resolve-Path .\apps\gateway\dist\mcp-stdio.js).Path
codex mcp add cursor2api -- $node $script
codex mcp get cursor2api

注册后重启 Codex。MCP 进程从本仓库 .env 读取 CURSOR_API_KEY，密钥不会写入 Codex 配置。

若用 codex mcp add 注册，在当前 Codex config.toml 的 [mcp_servers.cursor2api] 下补上 tool_timeout_sec = 1200（xhigh Worker 可能超过 Codex MCP 默认超时），或从 WebUI Codex Setup 复制完整片段。

把 ROOT 换成仓库根目录的绝对路径，command 换成 node.exe 的绝对路径：

[mcp_servers.cursor2api]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["ROOT\\apps\\gateway\\dist\\mcp-stdio.js"]
cwd = "ROOT"
tool_timeout_sec = 1200
enabled = true

用户级 Provider 片段见 integrations/codex/config.example.toml。不要把 model_provider = "cursor_relay" 设成 Codex 全局默认，否则 Sol 主会话也会切到 Cursor relay。

协调策略见仓库根目录 AGENTS.md，副本 integrations/codex/AGENTS.example.md。官方文档： Codex MCP。

卸载：codex mcp remove cursor2api。

MCP 生命周期

cursor2api 是本地 stdio MCP server。Codex 在初始化已启用的 MCP 时拉起该命令，不是每次 cursor_start 都新开进程。进程通常随 Codex 宿主会话存活，在宿主退出 / 重启、stdio 断开或进程失败时结束。

HTTP Gateway 与 WebUI 是另一组进程：关掉 Gateway 不会关掉 stdio MCP。

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 status
# 前台调试，Ctrl+C 结束；不能接到已运行的 Codex
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 start
# 停掉本仓库对应进程；Codex 在 enabled 时可能再次拉起
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 stop

持久关闭：把当前 Codex config.toml 里 [mcp_servers.cursor2api] 的 enabled 设为 false，然后重启 Codex。不要在 Worker 任务运行中 stop MCP。

Worker 工具与任务分配

先判断是否值得委派

Grok Worker 每次都需要定位文件、读取相关上下文、执行任务并返回摘要。对于很小的改动，这部分成本可能比实际修改更高， 反而降低速度并增加 token 消耗。因此，不要因为任务“边界明确”就自动委派。

通常由 Sol 直接完成：

• 只涉及 1–3 个紧密相关文件的简单修改；

• 文档、配置、文案、样式、清理和明显的小型 bug；

• 读取少量代码、执行几条命令就能完成和验证的工作；

• Worker 结果后的快速修正或局部审查。

适合交给 Grok Worker：

• 有实质工作量的多文件功能实现；

• 需要较多代码阅读、调试和测试的独立任务；

• 大范围但规则清楚的重复修改；

• 虽然文件少，但算法或实现本身复杂的任务。

文件数量只是判断信号，不是硬性门槛。核心原则是：只有 Grok 节省的执行工作明显大于它重新加载上下文的成本时才委派。

推荐流程：

1. Sol 先判断任务是否值得委派；小改动直接完成。

2. 需要委派时，写一份紧凑契约：绝对 cwd、objective、allowed_files、constraints、checks、risk。

3. 默认 cursor_execute：Sol → Worker → Grok 实现 / 测试 / 自审 → 精简结果 → Sol 验收。

4. 长任务或需要取消时用 cursor_start，间歇 cursor_status，终态再 cursor_result。

5. cursor_batch_execute 只用于 2–3 个文件范围互不重叠、且各自有足够工作量的独立任务。

6. 不希望沿用上一轮 Worker 上下文时，设 reuse_session=false。

cursor_execute 必填 objective、cwd；可选 allowed_files、constraints、checks、 risk（low / medium / high）、model、params、reuse_session。

模型与参数

默认模型 grok-4.6，默认参数 effort=xhigh、fast=false。这是目录解析与 WebUI 持久化默认，不是唯一组合。

在 Models 页可刷新真实目录、选择其他模型与参数并保存为后续 Worker 默认。单次任务可用 model / params 覆盖。

建议（可被任务覆盖）：小型机械改动由 Sol 直接完成；需要委派的大批量机械修改用 effort=medium；常规实现用 high； 难调试或算法用 xhigh。除非明确更在意延迟，否则保持 fast=false。

OpenAI Responses 文本接口

POST http://127.0.0.1:8787/v1/responses

• 只保证文本 stream 与 non-stream，不声称完整工具循环兼容。

• 需要 Authorization: Bearer <CURSOR_RELAY_API_KEY>。

• 未配置 CURSOR_API_KEY 时返回 missing_cursor_api_key。

• strict 模式下带 function tools 会得到 501 tool_bridge_unavailable。

Playground 可做文本试调用。隔离 Codex Provider 冒烟：npm.cmd run smoke:codex。

脚本与测试

Live Cursor 测试需要同时设置 CURSOR_LIVE_TEST=1 和 CURSOR_API_KEY。

仓库安全

• 复制 .env.example 为 .env；永远不要提交 .env、API Key、SQLite 数据、日志或运行数据。

• Fake backend 测试是默认行为；真实 Cursor 测试需要显式 opt-in，并会消耗账号用量。

• 报告漏洞或分享诊断信息前，先阅读 SECURITY.md。

常见问题

端口占用。 scripts\dev.ps1 需要 8787 与 5173 空闲。先跑 scripts\stop.ps1。

backend=fake 或没有真实模型。 .env 里要有有效 CURSOR_API_KEY，且不要设 CURSOR_BACKEND=fake。到 Models 页刷新目录。

MCP 工具超时。 确认 tool_timeout_sec = 1200。xhigh 任务可能很长。

主工具列表里没看到 Cursor 工具。 先用 /mcp 确认 cursor2api 已连接；修改配置后重启 Codex。部分运行环境会把 MCP 工具延迟加载，不显示在顶层清单中，但仍可通过完整 MCP 工具名调用。

停了 Gateway，Codex 仍能调 MCP。 正常。stdio MCP 由 Codex 拉起，与 HTTP Gateway 分开。

想用原生 Sol → Grok subagent。 当前 Codex 版本不可用，继续走 MCP Worker。

主会话也变成 Grok。 不要把 model_provider = "cursor_relay" 写成全局默认。

贡献与归属

开发流程见 CONTRIBUTING.md，项目归属见 CONTRIBUTORS.md，发布步骤见 docs/PUBLISHING_CHECKLIST.md。

尚未选择开源许可证。在原作者与仓库所有者达成一致之前，默认保留所有版权权利。