From d9b9f83923b1d10433f45d76baba96b38ed78e31 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 24 Apr 2026 02:02:41 -0700 Subject: [PATCH] fix(setup-gbrain): smoke test command + MCP user scope with absolute path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three Step 5a/9 defects found running /setup-gbrain end-to-end: 1. Step 9 smoke test used `gbrain put_page --title ... --tags ...`, which doesn't exist. The real command is `gbrain put ` with body piped on stdin. Updated to match. 2. Step 5a registered MCP with `claude mcp add gbrain -- gbrain serve`. Default scope is local (per-workspace), so other projects never saw gbrain. Cross-session memory is the whole point — user scope is correct. 3. Step 5a passed `gbrain` by bare name, relying on PATH being resolved when Claude Code spawns the subprocess. Fragile across shell configs. Use absolute path from `command -v gbrain` with ~/.bun/bin/gbrain fallback. Also: remove any stale local-scope registration before re-adding, and tell the user that open Claude Code sessions need a restart to see the new mcp__gbrain__* tools (loaded at session start, not mid-session). Co-Authored-By: Claude Opus 4.7 (1M context) --- setup-gbrain/SKILL.md | 28 ++++++++++++++++++++++------ setup-gbrain/SKILL.md.tmpl | 28 ++++++++++++++++++++++------ 2 files changed, 44 insertions(+), 12 deletions(-) diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index cc1c752e..a9d28d54 100644 --- a/setup-gbrain/SKILL.md +++ b/setup-gbrain/SKILL.md @@ -1283,17 +1283,33 @@ doctor output and STOP. Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface for gbrain? (recommended yes)" -If yes: +If yes, register at **user scope** with an **absolute path** to the gbrain +binary. User scope makes the MCP available in every Claude Code session on +this machine, not just the current workspace. Absolute path avoids PATH +resolution issues when Claude Code spawns `gbrain serve` as a subprocess. ```bash -claude mcp add gbrain -- gbrain serve -claude mcp list | grep gbrain # verify +GBRAIN_BIN=$(command -v gbrain) +[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain" +claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve +claude mcp list | grep gbrain # verify: should show "✓ Connected" +``` + +If the user already had a local-scope registration from an earlier run, +remove it first so both scopes don't conflict: +```bash +claude mcp remove gbrain 2>/dev/null || true ``` If `claude` is not on PATH: emit "MCP registration skipped — this skill is Claude-Code-targeted; register `gbrain serve` in your agent's MCP config manually." Continue to step 6. +**Heads-up for the user:** an already-open Claude Code session will not +pick up the new MCP tools until restart. Tell them: "Restart any open +Claude Code sessions to see `mcp__gbrain__*` tools — they're loaded at +session start, not mid-session." + --- ## Step 6: Per-remote policy (D3 triad, gated repo-import) @@ -1368,9 +1384,9 @@ Find-and-replace (or append) this section in CLAUDE.md: ## Step 9: Smoke test ```bash -gbrain put_page --title "setup-gbrain smoke test" --tags "meta" \ - <<<"Set up on $(date)" -gbrain search "smoke test" | grep -i "setup-gbrain smoke test" +SLUG="setup-gbrain-smoke-test-$(date +%s)" +echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG" +gbrain search "smoke test" | grep -i "$SLUG" ``` Confirms the round trip. On failure, surface `gbrain doctor --json` output diff --git a/setup-gbrain/SKILL.md.tmpl b/setup-gbrain/SKILL.md.tmpl index 1abe7a46..685e15e0 100644 --- a/setup-gbrain/SKILL.md.tmpl +++ b/setup-gbrain/SKILL.md.tmpl @@ -285,17 +285,33 @@ doctor output and STOP. Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface for gbrain? (recommended yes)" -If yes: +If yes, register at **user scope** with an **absolute path** to the gbrain +binary. User scope makes the MCP available in every Claude Code session on +this machine, not just the current workspace. Absolute path avoids PATH +resolution issues when Claude Code spawns `gbrain serve` as a subprocess. ```bash -claude mcp add gbrain -- gbrain serve -claude mcp list | grep gbrain # verify +GBRAIN_BIN=$(command -v gbrain) +[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain" +claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve +claude mcp list | grep gbrain # verify: should show "✓ Connected" +``` + +If the user already had a local-scope registration from an earlier run, +remove it first so both scopes don't conflict: +```bash +claude mcp remove gbrain 2>/dev/null || true ``` If `claude` is not on PATH: emit "MCP registration skipped — this skill is Claude-Code-targeted; register `gbrain serve` in your agent's MCP config manually." Continue to step 6. +**Heads-up for the user:** an already-open Claude Code session will not +pick up the new MCP tools until restart. Tell them: "Restart any open +Claude Code sessions to see `mcp__gbrain__*` tools — they're loaded at +session start, not mid-session." + --- ## Step 6: Per-remote policy (D3 triad, gated repo-import) @@ -370,9 +386,9 @@ Find-and-replace (or append) this section in CLAUDE.md: ## Step 9: Smoke test ```bash -gbrain put_page --title "setup-gbrain smoke test" --tags "meta" \ - <<<"Set up on $(date)" -gbrain search "smoke test" | grep -i "setup-gbrain smoke test" +SLUG="setup-gbrain-smoke-test-$(date +%s)" +echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG" +gbrain search "smoke test" | grep -i "$SLUG" ``` Confirms the round trip. On failure, surface `gbrain doctor --json` output