From 5a284660475091f4126d8232634a355dee48c420 Mon Sep 17 00:00:00 2001 From: AmberCXX Date: Wed, 13 May 2026 17:30:12 +0800 Subject: [PATCH 1/2] docs(engine): document `server:engine` channel allowlist requirement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Channels are research preview — even when the engine MCP server connects fine (`claude mcp list` shows ✓), notifications are silently dropped unless the launching `claude` invocation includes `--dangerously-load-development-channels server:engine`. Without this flag the scheduler fires on time and writes the trigger log, but nothing reaches the agent — so the symptom is "engine never delivers messages" with zero error output, easy to mistake for a deeper bug. - Spell out the flag requirement as a dedicated step in 快速开始 - Show the multi-channel form (`server:hub server:engine`, space-separated) - Add a verification recipe using engine_add_task so users can confirm the channel notification path is actually wired up - Cross-link the Anthropic Channels Reference + forge-launcher (which handles this automatically) Co-Authored-By: Claude Opus 4.7 --- forge-engine/README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/forge-engine/README.md b/forge-engine/README.md index 16ce64f..b120129 100644 --- a/forge-engine/README.md +++ b/forge-engine/README.md @@ -63,19 +63,42 @@ bun install } ``` -3. 注册为 Claude Code MCP server（`.claude.json` 或 `claude_desktop_config.json`）： +3. 注册为 Claude Code MCP server——推荐用 `claude mcp add`（user scope，所有 session 共享）： +```bash +claude mcp add --scope user engine /Users//.bun/bin/bun /absolute/path/to/forge-engine/engine-channel.ts +``` + +或手写到 `~/.claude.json` 的 `mcpServers`： ```json { "mcpServers": { "engine": { "command": "bun", - "args": ["path/to/forge-engine/engine-channel.ts"] + "args": ["/absolute/path/to/forge-engine/engine-channel.ts"] } } } ``` -4. 用 `fh engine` 管理任务： +4. **启动 Claude Code 时把 engine 加入 channels 白名单**——这一步**必不可少**，否则 engine 的定时通知会被 Claude Code 静默丢弃： + +```bash +claude --dangerously-load-development-channels server:hub server:engine +``` + +> [!IMPORTANT] +> Channels 是 research preview（详见 [Channels Reference](https://code.claude.com/docs/en/channels-reference)），自定义 channel server（包括 forge-engine、forge-hub 的 hub-channel）必须用 `--dangerously-load-development-channels server:` 显式白名单才被识别。`claude mcp list` 显示 `✓ Connected` **只代表 MCP 子进程成功启动**，**不代表 channel 通知能投递**——后者还需要这一步。 +> +> 多 channel 用**空格分隔**：`server:hub server:engine`（不是逗号）。和 forge-hub 一起用时两个都要加。如果你用 [forge-launcher](https://github.com/LinekForge/forge-launcher) 启动菜单栏会话管理器，它会自动带上这俩 flag。 + +**验证 channel 通知是否真的接通**： +```bash +# 在跑 Claude Code 的窗口里让 agent 用 engine_add_task 工具加一个 30 秒后的一次性任务， +# 如果 30 秒后窗口里收到 包裹的消息，说明白名单生效。 +# 收不到 → 检查是不是漏了 server:engine。 +``` + +5. 用 `fh engine` 管理任务： ```bash fh engine list fh engine pause 30 From 40599c18c2cd99f29bad9576981d4d1842f383d5 Mon Sep 17 00:00:00 2001 From: AmberCXX Date: Thu, 14 May 2026 22:35:41 +0800 Subject: [PATCH 2/2] docs(engine): refine MCP setup steps per review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address PR #28 review: - Fix `claude mcp add` syntax: add `--transport stdio` and `--` separator before command, matching official `claude mcp add --help` example shape. - Use `bun` (PATH) consistently in both CLI and JSON examples instead of mixing absolute path and PATH name. - Verification recipe: rewrite from a comment-only bash block into a natural-language step, matching the rest of the README's style. Self-audit (independent of review): - Restructure step 3 as explicit "二选一 (A | B)" so users don't try to do both registrations. - Strip `server:hub` from the primary launch command — forge-engine readers may not have hub installed; multi-channel form moved into the IMPORTANT callout. - Split the dense step 4 into 4 (whitelist) + 5 (verify) so each step carries one concept. Docs-only — touches `forge-engine/README.md` only. --- forge-engine/README.md | 47 ++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/forge-engine/README.md b/forge-engine/README.md index b120129..7414e15 100644 --- a/forge-engine/README.md +++ b/forge-engine/README.md @@ -63,42 +63,39 @@ bun install } ``` -3. 注册为 Claude Code MCP server——推荐用 `claude mcp add`（user scope，所有 session 共享）： -```bash -claude mcp add --scope user engine /Users//.bun/bin/bun /absolute/path/to/forge-engine/engine-channel.ts -``` - -或手写到 `~/.claude.json` 的 `mcpServers`： -```json -{ - "mcpServers": { - "engine": { - "command": "bun", - "args": ["/absolute/path/to/forge-engine/engine-channel.ts"] - } - } -} -``` +3. 注册 engine 为 Claude Code 的 MCP server（二选一）： + + **方式 A（推荐）**：CLI 一行注册（user scope，所有 session 共享） + ```bash + claude mcp add --transport stdio --scope user engine -- bun /absolute/path/to/forge-engine/engine-channel.ts + ``` + + **方式 B**：手写到 `~/.claude.json` 的 `mcpServers` + ```json + { + "mcpServers": { + "engine": { + "command": "bun", + "args": ["/absolute/path/to/forge-engine/engine-channel.ts"] + } + } + } + ``` 4. **启动 Claude Code 时把 engine 加入 channels 白名单**——这一步**必不可少**，否则 engine 的定时通知会被 Claude Code 静默丢弃： ```bash -claude --dangerously-load-development-channels server:hub server:engine +claude --dangerously-load-development-channels server:engine ``` > [!IMPORTANT] > Channels 是 research preview（详见 [Channels Reference](https://code.claude.com/docs/en/channels-reference)），自定义 channel server（包括 forge-engine、forge-hub 的 hub-channel）必须用 `--dangerously-load-development-channels server:` 显式白名单才被识别。`claude mcp list` 显示 `✓ Connected` **只代表 MCP 子进程成功启动**，**不代表 channel 通知能投递**——后者还需要这一步。 > -> 多 channel 用**空格分隔**：`server:hub server:engine`（不是逗号）。和 forge-hub 一起用时两个都要加。如果你用 [forge-launcher](https://github.com/LinekForge/forge-launcher) 启动菜单栏会话管理器，它会自动带上这俩 flag。 +> 和 forge-hub 一起用要带两个，**空格分隔**：`server:hub server:engine`（不是逗号）。如果你用 [forge-launcher](https://github.com/LinekForge/forge-launcher) 启动菜单栏会话管理器，它会自动带上这俩 flag。 -**验证 channel 通知是否真的接通**： -```bash -# 在跑 Claude Code 的窗口里让 agent 用 engine_add_task 工具加一个 30 秒后的一次性任务， -# 如果 30 秒后窗口里收到 包裹的消息，说明白名单生效。 -# 收不到 → 检查是不是漏了 server:engine。 -``` +5. 验证 channel 通知接通：在跑 Claude Code 的窗口里让 agent 调用 `engine_add_task` 工具（设 `delay_seconds: 30`）。30 秒后窗口收到 `` 包裹的消息说明白名单生效；收不到 → 检查是否漏了 `server:engine`。 -5. 用 `fh engine` 管理任务： +6. 用 `fh engine` 管理任务： ```bash fh engine list fh engine pause 30