Herald

🚀 Herald

Herald 是一个自托管的 MCP 服务器，它使用 Anthropic 的官方 Custom Connectors 协议，将 Claude Chat 与 Claude Code 连接起来。让你可以直接在手机上编写代码，真正实现随时随地进行代码开发。

🚀 快速开始

前提条件

• 安装 Claude Code CLI。
• 通过 ngrok（内置）或带有反向代理的域名实现 HTTPS。

安装

curl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh

git clone https://github.com/btouchard/herald.git
cd herald && make build
# 二进制文件位于 ./bin/herald

配置

mkdir -p ~/.config/herald
cp configs/herald.example.yaml ~/.config/herald/herald.yaml
# 使用你的域名和项目进行编辑（见下文）

运行

herald serve
# 客户端密钥在首次启动时自动生成，并显示在控制台中

编辑 ~/.config/herald/herald.yaml，添加你的域名和项目：

server:
  host: "127.0.0.1"
  port: 8420
  public_url: "https://herald.yourdomain.com"

auth:
  client_id: "herald-claude-chat"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    git:
      auto_branch: true
      branch_prefix: "herald/"

然后从 Claude Chat 进行连接：

1. Claude Chat → 设置 → 自定义连接器
2. 添加连接器：https://herald.yourdomain.com/mcp
3. 通过 OAuth 进行身份验证
4. 完成 —— Claude Chat 现在有 10 个新工具来控制你的工作站

使用 ngrok 快速开始（无需反向代理）

如果你没有域名或反向代理，可以使用 ngrok 通过 HTTPS 立即暴露 Herald：

获取 ngrok 认证令牌

在 ngrok.com 上注册（免费计划即可），并从 仪表盘 获取认证令牌。

在配置中启用隧道

编辑 ~/.config/herald/herald.yaml：

tunnel:
  enabled: true
  provider: "ngrok"
  authtoken: "2abc..."  # 或者设置 HERALD_NGROK_AUTHTOKEN 环境变量
  # domain: "my-herald.ngrok-free.app"  # 可选：固定域名（付费计划）

运行 Herald

herald serve
# 隧道 URL 显示在横幅中：
#   隧道: https://abc123.ngrok-free.app (ngrok)

使用横幅中显示的 ngrok URL 从 Claude Chat 进行连接。就是这么简单 —— 无需 Traefik、Caddy 或 DNS 设置。

注意：ngrok 隧道是可选的。如果你已经有反向代理（Traefik/Caddy），将 tunnel.enabled 设置为 false，并像往常一样使用你的域名。

server:
  host: "127.0.0.1"          # 始终为本地主机 —— 反向代理处理外部连接
  port: 8420
  public_url: "https://herald.yourdomain.com"
  log_level: "info"           # debug, info, warn, error
  log_file: ""                # 可选的日志输出文件路径

auth:
  client_id: "herald-claude-chat"
  # 客户端密钥自动生成 —— 如果需要，可以使用 HERALD_CLIENT_SECRET 环境变量覆盖
  access_token_ttl: 1h
  refresh_token_ttl: 720h    # 30 天
  redirect_uris:
    - "https://claude.ai/oauth/callback"
    - "https://claude.ai/api/oauth/callback"
    - "https://claude.ai/api/mcp/auth_callback"

database:
  path: "~/.config/herald/herald.db"
  retention_days: 90

execution:
  claude_path: "claude"
  model: "claude-sonnet-4-5-20250929"  # 任务的默认模型
  default_timeout: 30m
  max_timeout: 2h
  work_dir: "~/.config/herald/work"
  max_concurrent: 3
  max_prompt_size: 102400    # 100KB
  max_output_size: 1048576   # 1MB
  env:
    CLAUDE_CODE_ENTRYPOINT: "herald"
    CLAUDE_CODE_DISABLE_AUTO_UPDATE: "1"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    max_concurrent_tasks: 1
    git:
      auto_branch: true
      auto_stash: true
      auto_commit: true
      branch_prefix: "herald/"

tunnel:
  enabled: false               # 设置为 true 以启用 ngrok 隧道
  provider: "ngrok"
  authtoken: ""                # 或者设置 HERALD_NGROK_AUTHTOKEN 环境变量
  # domain: ""                 # 可选：固定域名（付费 ngrok 计划）

rate_limit:
  requests_per_minute: 200
  burst: 100

✨ 主要特性

核心特性

• 原生 MCP 桥接 —— 使用 Anthropic 的官方自定义连接器协议，不是黑客手段，不是包装器，也不是代理。
• 异步任务执行 —— 启动任务、检查进度、获取结果。Claude Code 在后台运行，你可以同时做其他事情。
• Git 分支隔离 —— 每个任务在自己的分支上运行，主分支保持不变。
• 会话恢复 —— 支持多轮 Claude Code 对话，可从上次中断的地方继续。
• 双向桥接 —— Claude Code 可以通过 herald_push 将会话上下文推送到 Herald，以便在其他设备上进行远程监控和继续操作。

多项目支持

• 多个项目 —— 可以根据需要配置任意数量的项目，每个项目都有自己的设置。
• 按项目限制工具使用 —— 精确控制 Claude Code 可以使用的工具，每个项目都有完整的沙箱环境。

操作特性

• MCP 推送通知 —— Herald 通过 MCP 服务器通知直接将任务更新推送到 Claude Chat，无需轮询。
• SQLite 持久化 —— 任务在服务器重启后仍然存在，拥有完整的历史记录，并且可以完全搜索。

工程特性

• 单二进制文件 —— 一个约 15MB 的 Go 可执行文件，无需 Docker、运行时或 node_modules。
• 零 CGO —— 纯 Go 实现，可交叉编译到 Linux、macOS、Windows、ARM 等平台。
• 6 个依赖项 —— chi、mcp-go、modernc/sqlite、uuid、yaml、testify，这就是整个依赖树。

💻 使用示例

基础用法

你可以在沙发上，用手机打开 Claude Chat 并输入：

"Refactor the auth middleware in my-api to use JWT instead of session cookies. Run the tests."

四分钟后，任务完成。分支创建、代码重构、测试通过、更改提交，所有工作都由你的工作站完成，你甚至不需要打开笔记本电脑。

高级用法

正向流程：Claude Chat → Herald → Claude Code

You (Claude Chat)          Herald                     Claude Code
─────────────────          ──────                     ───────────
"Refactor auth..."    ──►  start_task
                           → creates branch
                           → spawns Claude Code  ──►  reads codebase
                                                      refactors code
                                                      runs tests
                                                      commits changes
                      ◄──  task_id: herald-a1b2c3d4

"How's it going?"     ──►  check_task
                      ◄──  ✅ Completed (4m 12s)
                           4 files changed (+127/-23)

"Show me the diff"    ──►  get_diff
                      ◄──  auth/middleware.go
                           +func ValidateJWT(...)
                           -func CheckSession(...)

反向流程：Claude Code → Herald

如果你在终端中工作，想在手机上继续，可以让 Claude Code 将会话推送到 Herald：

You (terminal)             Claude Code                Herald
──────────────             ───────────                ──────
"Push this to Herald"  ──►  herald_push
                             → session_id, summary,
                               files, branch       ──►  linked task created
                                                         🔗 visible in list_tasks

You (phone, later)         Claude Chat                Herald
──────────────────         ───────────                ──────
"What sessions are         list_tasks
 waiting for me?"     ──►  (status: linked)      ──►  🔗 herald-a1b2c3d4
                                                         my-api / feat/auth

"Resume that session"  ──► start_task
                            (session_id)          ──►  picks up where you left off

📚 详细文档

MCP 工具

Herald 通过 MCP 协议自动向 Claude Chat 暴露 10 个工具：

🔧 技术细节

架构

Claude Chat (mobile/web)
  → HTTPS (MCP Streamable HTTP + OAuth 2.1)
  → Traefik / Caddy (TLS termination)
  → Herald (Go binary, port 8420)
    ├── MCP Handler (/mcp)
    ├── OAuth 2.1 Server (PKCE, token rotation)
    ├── Task Manager (goroutine pool, priority queue)
    ├── Executor Registry (pluggable backends, default: Claude Code)
    ├── SQLite (persistence)
    └── MCP Notifications (server push via SSE)

设计原则：单二进制文件（所有内容编译到一个 Go 可执行文件中）、异步优先（每个任务是一个 goroutine）、无状态 MCP 与有状态后端、故障安全（Herald 崩溃不会终止正在运行的 Claude Code 进程）。

安全机制

Herald 将 Claude Code 暴露到网络中，因此安全至关重要：

📄 许可证

本项目采用 AGPL-3.0 许可证。由 Benjamin Touchard 开发。

如果你觉得 Herald 节省了你的时间，请在 GitHub 上给项目点个星，这有助于其他人发现该项目。

路线图

如果你有想法，请 提交一个 issue，我们会根据用户需求进行开发。

贡献

Herald 处于早期 alpha 阶段，这是塑造项目的最佳时机。

# 开始贡献
git clone https://github.com/btouchard/herald.git
cd herald
make build && make test

# 创建你的分支
git checkout -b feat/your-feature

# 编码、测试、检查代码风格
make lint && make test

# 提交 PR

提交信息遵循 Conventional Commits 规范（feat:、fix:、refactor:、docs:）。

无论是修复 bug、添加新的通知后端还是改进文档，所有贡献都非常欢迎。

为什么选择 Herald？

Herald 使用 Anthropic 为其自身集成构建的相同协议，无需逆向工程、非官方 API 或可能在下次更新时失效的黑客手段。