跳转到内容
repo-harness

MCP 连接器

repo-harness 自带一个 MCP server，向 ChatGPT 和 Codex 只暴露你的工作流产物——计划、sprint、契约、检查、handoff。ChatGPT 通过一个公开的 /mcp 端点经由 HTTP 加 OAuth 连接；Codex 在本地通过 stdio 连接，无需隧道。这个 sidecar 不是远程编码 agent——它为本地 agent 宿主准备工作流产物。

前置条件

Section titled “前置条件”

一个已采用的仓库

在一个已经运行过 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

Section titled “1. 启动本地 MCP server”

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

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

  2. 确认它健康：

    Terminal window
    curl http://127.0.0.1:8765/health

  3. 读取本地 OAuth 口令——ChatGPT 在授权时会问你要：

    Terminal window
    jq -r .passphrase .repo-harness/mcp.oauth.json

  4. 冒烟测试 OAuth 发现：

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

2. 选择一个隧道端点

Section titled “2. 选择一个隧道端点”

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

Terminal window
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

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

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

3. 创建 ChatGPT Connector

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

4. 接线 Codex（stdio）

Section titled “4. 接线 Codex（stdio）”

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

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

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

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

Section titled “5. Dev 模式 agent runner（opt-in）”
Terminal window
repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 \
  --profile orchestrator --enable-dev-runner --dev-runner-agents codex

或者通过环境变量覆盖：

Terminal window
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。

暴露了什么

Section titled “暴露了什么”

planner profile 以读为主。它只能读取工作流文件、写入规划产物——绝不会碰应用源码、manifest、lockfile、CI 配置、密钥，或仓库根目录之外的文件。

  • 只读： harness_status、harness_doctor、read_workflow_file、list_workflow_files、latest_handoff、latest_checks
  • 规划写入： write_prd_from_idea、write_checklist_sprint、prepare_codex_goal_from_sprint

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

故障排查

Section titled “故障排查”
  • 如果 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。

下一步

Section titled “下一步”
ChatGPT Pro 规划器 这个 sidecar 解锁的 plan-and-review 工作流。
ChatGPT 浏览器引擎 通过 Oracle 驱动 ChatGPT Web——无需 API key。