herdr-mcpv0.3.32

安装：从一台 Herdr 工作站到可用的 Web AI 开发环境

这篇文档负责把系统真正装起来。目标不是“某个本地进程能启动”，而是完成下面这条链：

ChatGPT
  ↓ OAuth + MCP
Cloudflare Edge
  ↓ authenticated WSS
herdr-link / herdr-mcp
  ↓
Herdr + managed Git projects

如果只想快速体验，先看 快速开始。如果想让本地 Coding Agent 代你完成绝大多数安装步骤，把 快速 Agent 安装 里的一句话发给 Agent；详细合同见 Agent 辅助安装。

普通用户路径： GitHub Release 二进制 → herdr-mcp install → herdr-mcp doctor（Edge 可能已预置，或按 agent-install §6 部署）。第二台 Mac GA UAT（仅维护者，不是面向消费者的安装流程）用内部文档 _wip UAT Agent 协议 — 见 干净机 UAT。

安装前确认#

1. Herdr 已经可用#

herdr-mcp 建立在 Herdr 上，不安装也不替代 Herdr。

herdr --version
herdr api schema >/dev/null

如果这里失败，先按 Herdr 官方安装文档 修好 Herdr。

2. 明确你要连接哪类客户端#

  • ChatGPT：需要稳定公网 Edge + OAuth。
  • 同机 Cursor / curl：可以直接连接 127.0.0.1，不需要 Cloudflare。
  • z.ai / DeepSeek 浏览器桥接：依赖浏览器扩展和 Native Messaging，本机链路即可。

本页主线以 ChatGPT 为例，因为它覆盖了完整安装链路。

运行本机 MCP runtime 不需要 Node.js。部署 Cloudflare Worker（npx wrangler）时仍可能临时用到 Node。从源码构建浏览器扩展属于高级/开发者路径，不是主安装路径。

支持平台（第一版 GA 建议）#

  • 第一版 GA 正式支持： macOS Apple Silicon（托管 install / service / update / rollback）。
  • Preview artifact： Windows x64 仍可能作为 Release 资产发布；在 G19 封板前不要宣称完整托管生命周期对等。
  • 第一版 GA 不宣称： Linux service lifecycle。CI 矩阵里出现 Linux 二进制不等于 Linux 已是 GA 平台。

第一步：安装原生 runtime（主路径）#

从 GitHub Releases 下载当前平台的 herdr-mcp 二进制，放到 PATH（例如 ~/.local/bin/herdr-mcp）并赋予可执行权限。然后执行 herdr-mcp install：安装器会在 ~/.config/herdr-mcp/runtime/ 下写入不可变 generation，并把 ~/.local/bin/herdr-mcp 重定向到 runtime/current/herdr-mcp，使 PATH 入口不再依赖 git checkout。

herdr-mcp install
herdr-mcp doctor
herdr-mcp status
herdr-mcp update check   # bare `herdr-mcp update` is equivalent

优先使用以上顶层命令。不要把 herdr-mcp service install 写成普通用户安装主路径；service ... 仍是高级/内部接口。不要用 clone 仓库或 npm/cargo 安装本机 MCP runtime。

产品仍处 alpha 时，保持 update.channel = "preview"（或在 alpha 二进制上不写 config），才能发现 prerelease；stable 只发现非 prerelease。

第二步：先把本地 runtime 跑通#

受管 runtime 默认监听 127.0.0.1:8772。二进制安装且本机服务健康后：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8772/

返回 200 或 401 都说明 HTTP 服务存在；401 表示它正在要求本机 bearer。

这一步还应该确认 Herdr socket 能被 runtime 访问。稍后真正连接后，herdr_inspect 应能返回当前 workspace / pane / managed roots。

日常升级（herdr-mcp update 与 update check 等价；有可用版本时 JSON 会给出 next_action）：

herdr-mcp update          # same as update check
herdr-mcp update apply
herdr-mcp update status

第三步：让 runtime 长期运行#

在 macOS 上，安装完成后由原生二进制管理 LaunchAgent 生命周期。健康检查用 herdr-mcp status / herdr-mcp doctor，升级用 herdr-mcp update ...。不要把 launchd 指到 git checkout 或 target/*/herdr-mcp。

Linux / Windows 的服务封装目前更窄。第一版 GA 建议只正式支持 macOS Apple Silicon；Windows 若发布二进制仅作 preview。不要把未封板的 Linux lifecycle 写成正式支持。把 Release 二进制放在 PATH 上，并按当前 Release 资产中的平台说明处理。

第四步：部署稳定公网 Edge#

ChatGPT 不能访问你的 127.0.0.1。推荐架构是 Cloudflare Worker / Durable Object 作为稳定公网入口，工作站主动建立出站 WSS。

首次安装直接使用 workers.dev。它不要求购买域名，也避免在安装阶段把 DNS、证书和业务域名一起引入。

生成 Worker name#

WORKER_NAME="$(node scripts/cloudflare-worker-name.mjs "$(hostname)")"
printf '%s\n' "$WORKER_NAME"

Worker name 是 DNS label。像 MacBook.local 这种主机名不要原样复制；helper 会做规范化。

准备 Wrangler 配置#

cp edge/cloudflare/wrangler.user.example.toml edge/cloudflare/wrangler.user.toml

按模板填入：

  • Worker name；
  • workstation identity；
  • OAUTH_ISSUER / 公网 origin；
  • 模板要求的其他部署值。

部署：

cd edge/cloudflare
npx wrangler deploy --config wrangler.user.toml

公网 origin 形如：

https://herdr-edge-xxx.<account-subdomain>.workers.dev

MCP 端点：

https://herdr-edge-xxx.<account-subdomain>.workers.dev/mcp

凭据最小权限见 Cloudflare Edge Token；Worker / Durable Object / Link 细节见 Cloudflare Edge 部署。

第五步：验证工作站链路#

Worker 部署成功只证明 Edge 存在。Edge 还必须能路由到你的工作站。

确认：

  1. 本机 runtime 健康；
  2. herdr-link 在跑；
  3. workstation identity 与 Edge 配置一致；
  4. Edge /health 报告工作站在线；
  5. runtime generation/version 符合预期。

即使工作站离线，OAuth 也可能成功，所以要把公网 Edge 健康与工作站可达性当成不同层。

第六步：创建 ChatGPT Connector#

在 ChatGPT 中：

  1. 打开 Developer mode；
  2. 创建自定义 MCP Connector；
  3. 填入 https://<worker>.<account>.workers.dev/mcp；
  4. 在浏览器完成 OAuth；
  5. 新开一个会话做验证。

不要把 HERDR_MCP_TOKEN 贴进 ChatGPT。公网 Connector 的认证边界是 OAuth。

ChatGPT 会缓存工具快照。服务器升级后旧会话仍可能暴露旧契约；见 ChatGPT Connector。

第七步：做一次真实验证#

从只读请求开始：

检查当前 Herdr workspace 和项目状态。只读，不要修改。

预期：

  1. herdr_inspect 成功；
  2. 模型能看到真实 workspace / managed Git roots；
  3. 可能加载一次 herdr_skill；
  4. 能对真实项目状态使用 herdr_git 或 herdr_fs_read。

然后再试一次小的可逆编辑和测试命令。

当前生产公共契约是 epoch 2 / 18 tools。如果新会话仍只看到 17 个工具，先排查 Connector/工具快照缓存，而不是重装 runtime。

第八步：需要浏览器连续工作与本机观察时再装扩展#

MCP 解决的是“ChatGPT 到达工作站”。浏览器扩展再补三类能力：网页连续工作、Chrome Side Panel 控制中心，以及 z.ai / DeepSeek 的本机 JSON → MCP bridge。ChatGPT 还会获得“排队”，用于不中断当前回复地保存下一轮用户要求。

安装步骤见 浏览器扩展。扩展使用 Native Messaging 与本机 IPC；不把 Herdr bearer 存进浏览器状态。

安装后至少验证：

  1. 点击 Herdr 工具栏图标会直接打开 浏览器控制中心，并显示本机 runtime 可达；
  2. Control Center 的“当前页面”能识别当前 Project / conversation，并在这里绑定正确 workspace；
  3. Control Center 能实时看到 workspace / pane / Agent；
  4. 创建/关闭 pane 后 Side Panel 能看到生命周期变化；
  5. Control Center 的“提示 Agent / 调整会话 / Herdr API / 终端输入”明确显示为 Preview-only，而不是误以为已经开放写操作；
  6. ChatGPT 正在回复时，“排队”不会打断当前 turn，settled 后再发送下一轮。

控制中心交互见 浏览器控制中心。

何时再加 Custom Domain#

workers.dev 足以验证完整 Connector 路径。Custom Domain 适合：

  • 你要在自己控制的域名下长期固定 OAuth issuer；
  • 团队有集中域名治理；
  • 你想把公网身份与 Cloudflare account 子域解耦。

先在 workers.dev 上跑通完整流程，再单独迁移稳定 origin。

本机客户端：绕过 Cloudflare#

本机 Cursor / curl 可以直接连：

http://127.0.0.1:8772/mcp

并使用本机静态 bearer。这条路径也便于把 runtime 故障与 Edge 故障分开。

附录：开发者从源码构建#

clone + npm/cargo 工作流仍留给开发 herdr-mcp 本身的人。那不是最终用户安装主路径，也不应被要求用来运行本机 MCP runtime。

什么叫“装好了”#

一次完整的 ChatGPT 安装需要同时满足：

  • Herdr socket 可用；
  • herdr-mcp runtime 可用；
  • Edge 已部署；
  • 工作站链路在线；
  • OAuth 成功；
  • 新 ChatGPT 会话拿到 epoch-2 目录；
  • herdr_inspect 能看到真实工作站；
  • 至少一次真实的文件/Git/测试操作成功。

Worker 部署成功或 Connector 显示“connected”只是其中一层。

分层排障见 故障排查：本机 runtime → Link → Edge → OAuth → MCP → ChatGPT 快照。

文档

搜索 herdr-mcp

输入以搜索文档。