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 或可能在下次更新時失效的黑客手段。