fix(setup-gbrain): smoke test command + MCP user scope with absolute path

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 <slug>` 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) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-24 02:02:41 -07:00
parent 04185d8f92
commit d9b9f83923
2 changed files with 44 additions and 12 deletions
+22 -6
View File
@@ -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
+22 -6
View File
@@ -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