fix(setup-gbrain): register the gbrain MCP through bun.exe on Windows so no console window opens

Rewrite of #2007, folding #1963's MCP notes. On Windows the local stdio
registration stored the bun `gbrain` binstub; gbrain.exe starts bun in a new
console, so every Claude Code session opened a visible terminal for the MCP
(the contributor's process trees show it; bun.exe launched directly attaches
to Claude Code's headless ConPTY).

Under MINGW/MSYS/Cygwin the skill now resolves BUN_ROOT from BUN_INSTALL or
~/.bun and registers `$BUN_ROOT/bin/bun.exe <global node_modules
gbrain/src/cli.ts> serve`. That path also covers a `bun link`ed clone, whose
global node_modules entry links to it; gstack-gbrain-install records no other
clone location. When bun.exe or the entry is missing it registers
`$BUN_ROOT/bin/gbrain.exe` by its full name, because Claude Code does not
apply PATHEXT to a stored path (#1963). POSIX keeps the binstub line. The
skill also notes that `claude mcp list` can show "Failed to connect" while a
live session holds a local PGLite brain's single-writer lock (#1963).

test/setup-gbrain-windows-mcp.test.ts runs the generated fence under bash with
stub uname/claude and a temp HOME for MINGW64, MSYS with BUN_INSTALL, a
missing entry, and Linux. It is listed as Windows-incompatible (POSIX stubs);
the console behavior needs a manual Windows check.

Co-authored-by: Max Hogan <max@maxhogan.dev>
Co-authored-by: maxpetrusenkoagent <280464918+maxpetrusenkoagent@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
committed 2026-10-08 06:32:56 +00:00
1 parent 6f1b4cad0f
commit 652b5d3558
4 files changed
+129 -2

No files matched your search

+4
View File
@@ -75,6 +75,10 @@ export const KNOWN_WINDOWS_INCOMPATIBLE: Array<{ file: string; reason: string }>
file: 'test/setup-gbrain-fixture.test.ts',
reason: 'the fixture invokes real POSIX detector/verifier helpers through executable shebang wrappers',
},
{
file: 'test/setup-gbrain-windows-mcp.test.ts',
reason: 'drives the Windows MCP registration branch on POSIX by putting uname/claude shebang stubs on a colon-separated PATH and comparing POSIX path spellings; the console behavior it guards needs a manual Windows check',
},
{
file: 'test/hermetic-skills-seeding.test.ts',
reason: 'seeds the POSIX PTY skill runtime, whose embedded shell paths require a POSIX temporary root',
+25 -1
View File
@@ -611,15 +611,39 @@ 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.
On Windows (Git Bash/MSYS) the `gbrain.exe` binstub starts bun in a new
console, so every Claude Code session would open a visible terminal for the
MCP. Register `bun.exe` with gbrain's entry instead, which attaches to Claude
Code's hidden console. Without them, register `gbrain.exe` by its full name,
because Claude Code does not add `.exe` to a stored path.
```bash
GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
case "$(uname -s)" in
MINGW*|MSYS*|CYGWIN*)
BUN_ROOT="${BUN_INSTALL:-$HOME/.bun}"
GBRAIN_ENTRY="$BUN_ROOT/install/global/node_modules/gbrain/src/cli.ts"
if [ -f "$BUN_ROOT/bin/bun.exe" ] && [ -f "$GBRAIN_ENTRY" ]; then
claude mcp add --scope user gbrain -- "$BUN_ROOT/bin/bun.exe" "$GBRAIN_ENTRY" serve
else
claude mcp add --scope user gbrain -- "$BUN_ROOT/bin/gbrain.exe" serve
fi
;;
*)
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
;;
esac
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
On a local PGLite brain, `claude mcp list` can show `Failed to connect`
while an open Claude Code session's gbrain holds the database's single-writer
lock. If `mcp__gbrain__*` tools work in that session, the registration is
fine.
### Both paths
If `claude` is not on PATH: emit "MCP registration skipped — this skill is
+25 -1
View File
@@ -275,15 +275,39 @@ 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.
On Windows (Git Bash/MSYS) the `gbrain.exe` binstub starts bun in a new
console, so every Claude Code session would open a visible terminal for the
MCP. Register `bun.exe` with gbrain's entry instead, which attaches to Claude
Code's hidden console. Without them, register `gbrain.exe` by its full name,
because Claude Code does not add `.exe` to a stored path.
```bash
GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
case "$(uname -s)" in
MINGW*|MSYS*|CYGWIN*)
BUN_ROOT="${BUN_INSTALL:-$HOME/.bun}"
GBRAIN_ENTRY="$BUN_ROOT/install/global/node_modules/gbrain/src/cli.ts"
if [ -f "$BUN_ROOT/bin/bun.exe" ] && [ -f "$GBRAIN_ENTRY" ]; then
claude mcp add --scope user gbrain -- "$BUN_ROOT/bin/bun.exe" "$GBRAIN_ENTRY" serve
else
claude mcp add --scope user gbrain -- "$BUN_ROOT/bin/gbrain.exe" serve
fi
;;
*)
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
;;
esac
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
On a local PGLite brain, `claude mcp list` can show `Failed to connect`
while an open Claude Code session's gbrain holds the database's single-writer
lock. If `mcp__gbrain__*` tools work in that session, the registration is
fine.
### Both paths
If `claude` is not on PATH: emit "MCP registration skipped — this skill is
+75
View File
@@ -0,0 +1,75 @@
/**
* /setup-gbrain's local stdio MCP registration (#2007, #1963). On Windows the
* bun `gbrain.exe` binstub starts bun in a new console, so registering it made
* every Claude Code session open a visible terminal; the skill registers
* `bun.exe <gbrain entry> serve` instead, and `gbrain.exe` by its full name
* when bun.exe or the entry is missing. POSIX keeps the binstub.
*
* Runs the generated fence under bash with stub `uname` and `claude` and a
* temp HOME. The console behavior itself needs a real Windows machine.
*/
import { afterAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
const ROOT = path.resolve(import.meta.dir, '..');
const SKILL = fs.readFileSync(path.join(ROOT, 'setup-gbrain', 'SKILL.md'), 'utf-8');
function localStdioFence(): string {
const section = SKILL.indexOf('### Paths 1, 2a, 2b, 3 (Local stdio)\n\nRegister at **user scope**');
expect(section).toBeGreaterThan(-1);
const start = SKILL.indexOf('```bash\n', section) + '```bash\n'.length;
return SKILL.slice(start, SKILL.indexOf('\n```', start));
}
const base = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gbrain-mcp-'));
afterAll(() => fs.rmSync(base, { recursive: true, force: true }));
function register(uname: string, files: string[], env: (home: string) => Record<string, string> = () => ({})) {
const dir = fs.mkdtempSync(path.join(base, 'case-'));
const home = path.join(dir, 'home');
const stubs = path.join(dir, 'stubs');
const log = path.join(dir, 'claude-argv');
fs.mkdirSync(stubs, { recursive: true });
for (const rel of files) {
fs.mkdirSync(path.dirname(path.join(home, rel)), { recursive: true });
fs.writeFileSync(path.join(home, rel), '');
}
fs.writeFileSync(path.join(stubs, 'uname'), `#!/bin/bash\necho ${uname}\n`, { mode: 0o755 });
fs.writeFileSync(path.join(stubs, 'claude'), `#!/bin/bash\ncase "$2" in add) printf '%s\\n' "$@" > "${log}" ;; list) echo 'gbrain: stub - ✓ Connected' ;; esac\nexit 0\n`, { mode: 0o755 });
const r = spawnSync('bash', ['-c', localStdioFence()], {
env: { PATH: `${stubs}:/usr/bin:/bin`, HOME: home, ...env(home) },
encoding: 'utf-8',
timeout: 20_000,
});
expect(r.status).toBe(0);
return { home, argv: fs.readFileSync(log, 'utf-8').trim().split('\n') };
}
const BUN_EXE = '.bun/bin/bun.exe';
const ENTRY = '.bun/install/global/node_modules/gbrain/src/cli.ts';
describe('setup-gbrain local stdio MCP registration', () => {
test('Windows (MINGW64): registers bun.exe with the gbrain entry, not the binstub', () => {
const { home, argv } = register('MINGW64_NT-10.0-26100', [BUN_EXE, ENTRY]);
expect(argv).toEqual(['mcp', 'add', '--scope', 'user', 'gbrain', '--', path.join(home, BUN_EXE), path.join(home, ENTRY), 'serve']);
});
test('Windows honors BUN_INSTALL', () => {
const files = ['custom-bun/bin/bun.exe', 'custom-bun/install/global/node_modules/gbrain/src/cli.ts'];
const { home, argv } = register('MSYS_NT-10.0', files, (h) => ({ BUN_INSTALL: path.join(h, 'custom-bun') }));
expect(argv).toEqual(['mcp', 'add', '--scope', 'user', 'gbrain', '--', ...files.map((f) => path.join(home, f)), 'serve']);
});
test('Windows without the entry: registers gbrain.exe by its full name', () => {
const { home, argv } = register('MINGW64_NT-10.0', [BUN_EXE]);
expect(argv).toEqual(['mcp', 'add', '--scope', 'user', 'gbrain', '--', path.join(home, '.bun/bin/gbrain.exe'), 'serve']);
});
test('Linux keeps the binstub registration', () => {
const { home, argv } = register('Linux', [BUN_EXE, ENTRY]);
expect(argv).toEqual(['mcp', 'add', '--scope', 'user', 'gbrain', '--', path.join(home, '.bun/bin/gbrain'), 'serve']);
});
});