MCP 连接器

repo-harness 自带一个 MCP server，给 ChatGPT 和 Codex 对你已注册仓库的只读访问——既包括工作流文件，也包括仓库目录树、文本搜索和文件内容——同时写入仍限定在工作流产物（计划、sprint、契约、handoff）范围内。ChatGPT 通过一个公开的 /mcp 端点经由 HTTP 加 OAuth 连接；Codex 在本地通过 stdio 连接，无需隧道。这个 sidecar 不是远程编码 agent——它为本地 agent 宿主准备工作流产物。

前置条件

一个已采用的仓库

在一个已经运行过 repo-harness adopt 的仓库中运行。见安装。

PATH 上有 repo-harness

repo-harness CLI 必须已安装，并能在你的 shell PATH 上解析到。

ChatGPT Developer Mode

一个能访问 Developer Mode 和自定义 MCP Connector 的 ChatGPT workspace。

一个公开的 /mcp 端点

用于 ChatGPT 长期使用的稳定公开 HTTPS /mcp URL。本地 Codex 使用 stdio，无需隧道。

1. 启动本地 MCP server

在 localhost 上以 planner profile 通过 HTTP 启动 server：

repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner

确认它健康：
Terminal window
```
curl http://127.0.0.1:8765/health
```
读取本地 OAuth 口令——ChatGPT 在授权时会问你要：
Terminal window
```
jq -r .passphrase .repo-harness/mcp.oauth.json
```

冒烟测试 OAuth 发现：

curl http://127.0.0.1:8765/.well-known/oauth-protected-resource/mcp

2. 选择一个隧道端点

ChatGPT 需要一个以 /mcp 结尾的公开 HTTPS URL。长期使用时优先用稳定的主机名——quick tunnel 的 URL 会变，而 ChatGPT 会把每个新 URL 当成不同的 Connector 应用。

稳定（命名隧道）
快速（一次性）

cloudflared tunnel login
cloudflared tunnel create repo-harness-mcp
cloudflared tunnel route dns repo-harness-mcp repo-harness-mcp.example.com
cloudflared tunnel run --url http://127.0.0.1:8765 repo-harness-mcp

然后把稳定端点记录到被忽略的本地配置里：

repo-harness mcp setup chatgpt --repo . --endpoint <https-url>/mcp

cloudflared tunnel --url http://127.0.0.1:8765

把打印出的 HTTPS URL 追加 /mcp 后作为你的 Connector URL：

<https-tunnel-url>/mcp

3. 创建 ChatGPT Connector

打开 ChatGPT Settings。
如果你的 workspace 暴露了 Developer Mode，启用它。
进入 Connectors。
创建一个名为 repo-harness 的 Connector。
粘贴以 /mcp 结尾的 HTTPS Connector URL。
把 Connector 认证配置为 OAuth。
点击 Scan Tools。
当授权页面打开时，输入 .repo-harness/mcp.oauth.json 中的口令。
等待工具扫描完成，然后创建该 Connector。
保持 write confirmations enabled。

4. 接线 Codex（stdio）

Codex 在本地运行，不需要隧道——它直接讲 stdio。自动生成配置：

repo-harness mcp setup codex --repo . --scope project

这会写出 .codex/config.toml，其中含一个 stdio 的 repo_harness server 条目和允许的工具列表。

5. Dev 模式 agent runner（opt-in）

repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 \
  --profile orchestrator --enable-dev-runner --dev-runner-agents codex

或者通过环境变量覆盖：

REPO_HARNESS_MCP_DEV_RUNNER=1 REPO_HARNESS_MCP_DEV_RUNNER_AGENTS=codex,claude \
  repo-harness mcp serve --repo . --transport http --profile orchestrator

启用后，server 会暴露 run_agent_goal。它只读取 .ai/harness/handoff/codex-goal.md，并通过允许的本地 CLI 运行那个固定的 handoff。它不是任意 shell。

暴露了什么

planner profile 以读为主：它能读取你已注册的仓库，并且只写入规划产物——绝不会碰应用源码、manifest、lockfile、CI 配置、密钥，或允许的仓库根目录之外的文件。

工作流读取： harness_status、harness_doctor、read_workflow_file、list_workflow_files、latest_handoff、latest_checks
仓库读取（只读）： reader_status、list_allowed_roots、open_workspace、tree、search_text、read_text——浏览和搜索整个仓库，而不仅仅是工作流文件
规划写入： write_prd_from_idea、write_checklist_sprint、prepare_codex_goal_from_sprint

即使开启了仓库读取，deny glob 仍然生效：.env、私钥、SSH 密钥、凭据、密钥、.git，以及依赖和构建产物永远不会被返回。

已注册仓库与多仓库

一个 Connector 就能服务你采用过的每一个仓库。repo-harness adopt 和 repo-harness init 会把仓库注册到 ~/.repo-harness/registered-repos.json；discover_harness_repos 列出它们，读取工具接受一个 repo_path 来指定具体仓库。全盘读取已弃用——遗留的 fullDiskRead: true 现在会fail closed；额外的非仓库根目录要用 --allow-root 显式添加。

User-scope 设置（repo-harness mcp setup chatgpt 不带 --repo，把配置和认证存放在 ~/.repo-harness/ 下）适用于 Developer Mode 部署。HTTP 认证支持 OAuth——带 offline_access 的 refresh-token 轮换——以及一个 url-token 兼容模式。

预期的规划链路：idea → write_prd_from_idea → write_checklist_sprint → prepare_codex_goal_from_sprint → 本地 Codex /goal 执行。

故障排查

如果 ChatGPT 连不上，确认隧道 URL 是 HTTPS 且以 /mcp 结尾。
如果 ChatGPT 返回未授权，确认 OAuth 发现正常，并重新走一遍口令流程。
如果工具缺失，重启 repo-harness mcp serve 并重新扫描工具。
如果写入失败，确认目标路径是 PRD、sprint、plan 或已批准的 handoff 文件。
如果 ChatGPT 生成的是 prose 而不是 checklist 形式的 Sprint task card，让它使用 write_checklist_sprint。
如果 Codex 看不到 server，运行 repo-harness mcp setup codex --repo . --scope project。

下一步

ChatGPT Pro 规划器这个 sidecar 解锁的 plan-and-review 工作流。

ChatGPT 浏览器引擎通过 Oracle 驱动 ChatGPT Web——无需 API key。