mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
7b0d99adb0
* fix: gbrain auth create dropped the name on the bare (no-flag) form Extract parseAuthCreateArgs; only exclude the --takes-holders value from the positional search when the flag is present (rest[takesIdx+1] resolved to rest[0] when takesIdx === -1, silently dropping the name). Add regression test. * feat: gbrain connect — one-command Claude Code onboarding from a bearer token New connect command prints a paste-ready claude-mcp-add block (or --install wires it + smoke-tests the token via a raw-bearer get_brain_identity probe). Direct HTTP MCP, literal-token default, URL normalization, token header-injection guard, --json redaction, execFileSync (no shell). Wired into CLI_ONLY + CLI_ONLY_SELF_HELP + handleCliOnly. 58 unit + 3 PGLite-E2E cases; e2e-test-map updated. * docs: lead CLAUDE_CODE.md with gbrain connect (remote fast path) + README one-liner Regenerate llms-full.txt for the README change. * refactor: pre-landing review fixes for gbrain connect - DRY: single DEFAULT_PROBE_TIMEOUT_MS + shared isAuthErrorMessage predicate - reuse promptLine (shared stdin lifecycle) for the --install confirm - harden redactToken with a Bearer <value> scrub (defense in depth) - +8 tests: orchestrator guard paths, deterministic timeout, invalid --timeout-ms, Bearer-redaction * fix: adversarial-review hardening for gbrain connect - probe: Promise.race the call against a real timer so a stalled connect()/SSE handshake (signal alone doesn't cover it) can't hang --install indefinitely - probe: close transport even if client.connect() throws - parseArgs: reject a missing/flag-shaped value (e.g. --token --install) - block link-local / cloud-metadata hosts (169.254/fe80:/fd00:ec2::254) — keeps localhost + RFC1918 LAN brains working - non-interactive --install now requires --yes - clearer message when --force removed then add failed +8 tests covering each * fix: codex-review P2s for gbrain connect - POSIX single-quote the rendered claude-mcp-add command so a token with shell metacharacters ($(), backticks) can't trigger command substitution on paste - detect IPv4-mapped IPv6 metadata addresses (::ffff:169.254.x.x / ::ffff:a9fe:*) so they don't bypass the link-local guard +3 tests * chore: bump version and changelog (v0.42.2.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: document gbrain connect + connect-probe in CLAUDE.md Key files (v0.42.2.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: gbrain connect — add codex and perplexity agents --agent codex emits 'codex mcp add ... --bearer-token-env-var GBRAIN_REMOTE_TOKEN' (token read from the env var at runtime, never in Codex config; --install runs it). --agent perplexity prints the URL + token for the Settings → Connectors GUI (no --install). Generalized the command file: AGENT_SPECS table, buildCodexMcpAddArgv, cmdString(binary,argv), binary-generic ConnectDeps (hasBinary/runBinary/env), agent-aware buildConnectBlock/buildJson. +25 tests. * docs: codex + perplexity connect paths (new CODEX.md, README, CHANGELOG, CLAUDE.md) Regenerate llms-full.txt for the CLAUDE.md/README edits. * test: real-CLI E2E for connect — drive actual claude + codex against a live server Adds claude-code + codex cases to connect-bearer.test.ts that run the real 'claude mcp add' / 'codex mcp add' through 'gbrain connect --install' against a live 'gbrain serve --http' (sandboxed HOME/CODEX_HOME), then assert via 'claude mcp get' / 'codex mcp get' that the server registered (and codex's token stays out of config). Skips when the binary is absent. Perplexity is GUI-only so it's print-asserted. Regen llms for the CLAUDE.md note. * docs: perplexity OAuth + serve --bind/--public-url footgun (per Perplexity feedback) PERPLEXITY.md now documents the host-side HTTP setup (gbrain serve --http --bind 0.0.0.0 --public-url, the v0.34 ECONNREFUSED footgun) and the OAuth 2.1 client_credentials path (gbrain auth register-client) alongside the legacy bearer token. The 'connect --agent perplexity' output points at the same bind/public-url requirement + PERPLEXITY.md. * feat: gbrain connect --oauth — client-credentials path for perplexity/generic OAuth is the correct path for a third-party cloud connector (Perplexity): instead of a long-lived full-access bearer token, the connector gets Issuer URL + Client ID + Client Secret and mints short-lived scoped tokens. --oauth --register mints a least-privilege client on the host (shells gbrain auth register-client); --oauth --client-id/--client-secret uses an existing one. Rejected for claude-code/codex (bearer) and with --install. Issuer derived from the mcp-url. New E2E proves the full chain: register → connect --oauth → OAuth discovery → /token client_credentials mint → get_brain_identity tool call against a live server. Docs: PERPLEXITY.md leads with OAuth; README + CLAUDE.md updated; +18 unit cases. * docs: add gbrain connect to INSTALL.md MCP section + link CODEX.md The remote-client onboarding command was documented in README/CLAUDE_CODE/CODEX/ PERPLEXITY but missing from INSTALL.md §3 (the natural 'how do I connect a client' home). Add the one-command connect how-to (claude-code/codex/perplexity) and the missing docs/mcp/CODEX.md link. * fix: connect LEARN_INSTRUCTION names put_page, not CLI-only capture The self-orientation block told a connected agent that `capture` is an available MCP tool. It isn't — `capture` is a CLI-only convenience command; the MCP write tool is `put_page`. An agent that followed the instruction hit "unknown tool". Drop capture; put_page was already in the list. Adds a regression block to connect.test.ts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: serve --http surfaces skill-publishing status (banner + nudge) When mcp.publish_skills is OFF, connected agents can search/write but can't call list_skills/get_skill, so the host's skill catalog is invisible to them. The startup banner now shows a Skills: line, and a stderr nudge fires when off with the paste-ready fix. Pure skillPublishStatus() helper, unit-tested. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: prove the local stdio MCP funnel end-to-end Spawns real `gbrain serve` (stdio) against a freshly init --pglite brain and drives the official MCP SDK client through initialize -> tools/list -> tools/call (get_brain_identity + search). Pins the advertised core-tool set against what the server actually exposes (asserts capture is NOT advertised). This funnel had zero e2e coverage before. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: make batch-retry-audit ENOENT case hermetic The 'no-op when audit dir does not exist' case called pruneOldBatchRetryAuditFiles(30) without a GBRAIN_AUDIT_DIR override, so it read the real ~/.gbrain/audit and flaked (kept:1) on any dev machine with a batch-retry-*.jsonl on disk. Point it at a guaranteed-missing temp subdir, matching this file's own hermetic-header contract. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: two-funnel coding-agent onboarding (Claude Code / Codex) New tutorial docs/tutorials/connect-coding-agent.md: Path A (connect to an existing brain) + Path B (start from nothing, local stdio), the brain-first protocol to paste into CLAUDE.md/AGENTS.md, and the four translatable habits. README gains a 'Quick start: Claude Code or Codex' fork separating lightweight retrieval from the full autonomous install. INSTALL.md shows the one-command wire-up at the standalone CLI section. mcp/CLAUDE_CODE + CODEX cross-link the tutorial + note publish_skills + capture-is-CLI-only. Tutorial promoted to Shipped in the tutorials index. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: changelog + regenerated llms (v0.42.2.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: CLAUDE.md Key Files annotation for two-funnel onboarding wave Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# Connect GBrain to Perplexity Computer
|
|
|
|
Perplexity Computer connects as a **remote** MCP client, so GBrain must be served
|
|
over HTTP and reachable at a public HTTPS URL. Perplexity does not run
|
|
`gbrain serve` (stdio) the way Claude Code does — it needs a reachable endpoint:
|
|
|
|
```
|
|
Perplexity Computer
|
|
→ ngrok tunnel (https://YOUR-DOMAIN.ngrok.app/mcp)
|
|
→ gbrain serve --http (built-in OAuth 2.1 transport)
|
|
→ Postgres / PGLite
|
|
```
|
|
|
|
## 1. Serve GBrain over HTTP (host side)
|
|
|
|
```bash
|
|
gbrain serve --http --port 3131 --bind 0.0.0.0 \
|
|
--public-url https://YOUR-DOMAIN.ngrok.app
|
|
```
|
|
|
|
- **`--bind 0.0.0.0` is required.** Since v0.34, `--http` defaults to
|
|
`127.0.0.1`, so without it the tunnel reaches the server but the connection is
|
|
refused (`ECONNREFUSED`).
|
|
- **`--public-url` must match the tunnel.** The OAuth issuer in the discovery
|
|
metadata has to line up with the URL Perplexity actually hits (RFC 8414 §3.3),
|
|
or OAuth client-credentials auth fails.
|
|
|
|
## 2. Expose it with a tunnel
|
|
|
|
```bash
|
|
ngrok http 3131 --url YOUR-DOMAIN.ngrok.app
|
|
```
|
|
|
|
See the [ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for a persistent
|
|
tunnel.
|
|
|
|
## 3. Create credentials
|
|
|
|
Two supported auth paths.
|
|
|
|
**OAuth 2.1 client credentials (recommended, v0.26.0+).** Perplexity is a cloud
|
|
service, so it holds whatever credential you give it. OAuth is the correct choice:
|
|
least-privilege scopes + short-lived rotating access tokens instead of a
|
|
long-lived full-access secret. Mint a client and print the connector fields in
|
|
one step (on the brain host):
|
|
|
|
```bash
|
|
gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --agent perplexity --oauth --register
|
|
```
|
|
|
|
Or register separately and pass the creds (works anywhere, no DB needed):
|
|
|
|
```bash
|
|
gbrain auth register-client perplexity --grant-types client_credentials --scopes "read write"
|
|
gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --agent perplexity --oauth \
|
|
--client-id gbrain_cl_xxx --client-secret gbrain_cs_xxx
|
|
```
|
|
|
|
`connect --oauth` prints the **Issuer URL + Client ID + Client Secret** to paste
|
|
in step 4.
|
|
|
|
**Legacy bearer token (simplest, best for local/personal):**
|
|
|
|
```bash
|
|
gbrain auth create "perplexity"
|
|
gbrain connect https://YOUR-DOMAIN.ngrok.app/mcp --token gbrain_xxx --agent perplexity
|
|
```
|
|
|
|
(Perplexity is a GUI connector, so there's no `--install` — `connect` prints the
|
|
exact values to paste in step 4.)
|
|
|
|
## 4. Add the connector in Perplexity
|
|
|
|
1. Open Perplexity (requires Pro subscription).
|
|
2. Go to **Settings → Connectors** (or **MCP Servers**).
|
|
3. Add a new remote connector:
|
|
- **URL:** `https://YOUR-DOMAIN.ngrok.app/mcp`
|
|
- **Authentication:** API Key / Bearer Token, or OAuth client credentials
|
|
- Paste the token (bearer) or `client_id` + `client_secret` (OAuth).
|
|
4. Save.
|
|
|
|
## Verify
|
|
|
|
In a Perplexity conversation, ask it to use your brain:
|
|
|
|
```
|
|
Use my GBrain to search for [topic]
|
|
```
|
|
|
|
Have it call `get_brain_identity` (whose brain this is), then `list_skills`
|
|
(everything it can do).
|
|
|
|
## Notes
|
|
|
|
- Perplexity Computer is available to Pro subscribers; both the Mac app and web
|
|
version support remote MCP connectors.
|
|
- The Mac app can also use a local MCP server (`gbrain serve` stdio) if you'd
|
|
rather not expose an HTTP endpoint.
|
|
- A `gbrain auth create` token is a long-lived, full-access secret. Keep it
|
|
private and prefer a scoped token where possible.
|