@andespindola/brainlink 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.8.1
+
+- **Fix the Connect page's Codex snippet auth.** The `/connect` page's Codex `config.toml` block passed the bearer token via a `MCP_AUTHORIZATION` env var, but `mcp-remote` does not read that env — so the request went out unauthenticated and `mcp-remote` fell back to a hanging OAuth flow. The token is now passed as an `mcp-remote` `--header "Authorization: Bearer <token>"` argument (verified to connect), and both the remote and local Codex snippets gained `startup_timeout_sec = 60` so Codex doesn't time out the cold-start MCP handshake.
+
+## 1.8.0
+
+- **"Connect your agent" page in the graph UI.** The exposed graph web UI (`brainlink server --expose`) now serves a new auth-gated `GET /connect` page, reachable from the account menu, with ready-to-paste MCP setup for wiring agents and chats (Codex, Claude Code, ChatGPT/generic MCP) to this brainlink. It detects its mode server-side: in **remote** mode — when the server is exposed and `BRAINLINK_MCP_TOKEN` is set — it builds the MCP endpoint from the request host as `https://<host>/mcp` and renders the Codex `~/.codex/config.toml` (`mcp-remote`), Claude Code `claude mcp add --transport http`, `.mcp.json` (streamable HTTP) and ChatGPT/generic connector snippets, each carrying the owner's bearer token; in **local** mode — no token / not exposed — it renders the stdio equivalents (`brainlink mcp-server --vault <path>`) and never shows a token. The page also ships a ready AGENTS.md operating contract, per-snippet copy-to-clipboard buttons, and the shared neon identity. It is served behind the same session as `/settings`, so the token is shown only to the authenticated graph owner and never on any unauthenticated route.
+
 ## 1.7.0
 
 - **Unified neon graph UI.** The graph web frontend now shares one visual identity with the SaaS app so the app → SSO → graph handoff reads as a single product. Every self-contained page served by the graph server — the login and change-password pages, the settings page, the OAuth authorize/consent page, the graph explorer, and the injected account menu — is repainted onto the neon palette: `#0a0e1a` base with a faint cyan/violet cyber grid and soft ambient glow, cyan `#22d3ee` nodes, violet `#8b5cf6` edges/context, glass panels, gradient "Brainlink" wordmark, cyan focus glow, and a neon gradient primary button. Typography moves to Space Grotesk (headings) + DM Sans (body) via a Google Fonts `@import` with a robust system fallback so it degrades gracefully offline, while a monospace stack stays for graph node ids and code. All graph behavior (WebGL/worker/2D-fallback rendering, layout, zoom, pan, search, streaming, context grouping, versioning UI) and every endpoint, form field and OAuth flow are unchanged — this is a visual/identity pass only. Contrast on the new palette meets WCAG AA, focus rings are visible, and motion respects `prefers-reduced-motion`.

package/dist/application/frontend/client/account-menu.js

@@ -136,6 +136,10 @@ const startAccountMenu = () => {
       button.setAttribute('aria-expanded', 'true')
     }
 
+    addItem('Connect your agent', () => {
+      closeMenu()
+      window.location.href = '/connect'
+    })
     addItem('Settings', () => {
       closeMenu()
       window.location.href = '/settings'

package/dist/application/frontend/connect-page.js

@@ -0,0 +1,438 @@
+// Self-contained branded "Connect your agent" page for the graph web server.
+// Served as a plain string (inline <style> + inline <script>, no external assets
+// beyond the shared Google Fonts @import, no framework) so it works identically
+// for a global npm install. The visual identity is the unified neon system
+// shared with the auth pages, the settings page and the graph client (see
+// neon-theme.ts): #0a0e1a base, faint cyber grid, cyan #22d3ee + violet #8b5cf6,
+// Space Grotesk headings / DM Sans body, glass card + gradient wordmark.
+//
+// The page renders ready-to-paste MCP setup so a graph owner can wire their
+// agents (Codex, Claude Code, ChatGPT/MCP) to this brainlink. It has two modes,
+// picked server-side:
+//   - remote:  the server is exposed AND an MCP token is configured. Snippets
+//              point at the request host over HTTPS and carry a bearer token.
+//   - local:   no token / not exposed. Snippets run the local stdio MCP server
+//              against the server's configured vault path — never a token.
+// This page is only ever served behind the same session gate as /settings, so
+// the token is shown only to the authenticated graph owner.
+import { neonAmbientEffects, neonFontImport, neonGridBackground, neonRootTokens, neonWordmark } from './neon-theme.js';
+// HTML-escape for text interpolated into the served document. Snippets are
+// rendered as textContent client-side, but the AGENTS.md / labels are inlined,
+// so escape defensively to keep the page well-formed and injection-free.
+const escapeHtml = (value) => value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+// The compact operating contract shown on the page and offered as a ready
+// AGENTS.md. Neutral/professional, referencing only the agent product names.
+export const connectAgentsMarkdown = () => `# Brainlink — canonical memory
+
+Brainlink is your canonical, persistent memory across turns and sessions. Treat
+it as the continuity of your cognition, not an optional lookup.
+
+## At session start
+- Run \`brainlink_bootstrap\` with a short \`query\` describing the task. Re-run it
+  whenever your context is stale.
+
+## Before you act
+- Consult Brainlink before any decision, recommendation, question, or
+  implementation. Never act from memory alone when durable context may exist.
+- Retrieve with \`strategy: "auto"\` (CAG on a fresh pack, RAG otherwise) and
+  \`mode: "hybrid"\` (FTS + semantic) unless a narrower mode clearly fits.
+
+## After you learn
+- Write durable learnings back with \`brainlink_remember\` (or
+  \`brainlink_add_note\` for structured notes), then reindex with
+  \`brainlink_index\`.
+- Write connected memory: include \`[[wiki links]]\`, tags, and priority markers
+  so notes join the knowledge graph instead of sitting orphaned.
+`;
+const connectStyles = () => `${neonFontImport()}
+:root {
+${neonRootTokens()}
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  min-height: 100%;
+  margin: 0;
+}
+
+body {
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  min-height: 100vh;
+  min-height: 100dvh;
+  padding: 40px 24px;
+  color: var(--text);
+  font-family: var(--font-body);
+${neonGridBackground()}
+}
+
+${neonAmbientEffects()}
+
+button {
+  font: inherit;
+}
+
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.connect-card {
+  width: 100%;
+  max-width: 720px;
+  padding: 32px 28px;
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  background: var(--panel);
+  box-shadow: 0 24px 80px rgba(2, 6, 18, 0.55);
+  backdrop-filter: blur(16px);
+  animation: neon-fade-up 260ms cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .connect-card {
+    animation: none;
+  }
+}
+
+.connect-brand {
+  display: grid;
+  gap: 4px;
+  margin-bottom: 20px;
+}
+
+.connect-brand strong {
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+${neonWordmark()}
+}
+
+.connect-brand span {
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.connect-lede {
+  margin: 0 0 8px;
+  color: var(--text);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.connect-mode {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 20px;
+  padding: 6px 12px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: rgba(19, 26, 42, 0.55);
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.connect-mode strong {
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.connect-endpoint {
+  display: grid;
+  gap: 6px;
+  margin-bottom: 24px;
+  padding: 12px 14px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: rgba(19, 26, 42, 0.55);
+}
+
+.connect-endpoint span {
+  color: var(--muted);
+  font-size: 11px;
+  letter-spacing: 0.02em;
+}
+
+.connect-endpoint code {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--accent);
+  overflow-wrap: anywhere;
+}
+
+.connect-section {
+  margin-top: 26px;
+  padding-top: 22px;
+  border-top: 1px solid var(--line);
+  display: grid;
+  gap: 12px;
+}
+
+.connect-section h2 {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-weight: 600;
+  font-size: 16px;
+  letter-spacing: 0.01em;
+}
+
+.connect-hint {
+  margin: 0;
+  color: var(--muted);
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+.connect-hint code {
+  font-family: var(--font-mono);
+  color: var(--accent);
+}
+
+.connect-snippet {
+  position: relative;
+  display: grid;
+  gap: 8px;
+}
+
+.connect-snippet pre {
+  margin: 0;
+  padding: 14px 16px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: rgba(10, 14, 26, 0.75);
+  overflow-x: auto;
+}
+
+.connect-snippet code {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--text);
+  white-space: pre;
+}
+
+.connect-copy {
+  justify-self: start;
+  height: 32px;
+  padding: 0 14px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: rgba(19, 26, 42, 0.7);
+  color: var(--text);
+  cursor: pointer;
+  font-size: 12px;
+  transition: border-color 150ms ease, background 150ms ease, box-shadow 150ms ease;
+}
+
+.connect-copy:hover,
+.connect-copy:focus {
+  border-color: var(--accent);
+  background: var(--accent-weak);
+  box-shadow: var(--glow-cyan);
+}
+
+.connect-back {
+  display: inline-block;
+  margin-top: 24px;
+  color: var(--muted);
+  font-size: 12px;
+  text-decoration: none;
+}
+
+.connect-back:hover,
+.connect-back:focus {
+  color: var(--accent);
+}`;
+// One inline copy-button behaviour reused for every snippet, mirroring the
+// settings page: prefer the async clipboard API, fall back to a text selection.
+const connectScript = () => `(function () {
+  var buttons = document.querySelectorAll('.connect-copy');
+
+  function flash(button) {
+    var original = button.getAttribute('data-label') || 'Copy';
+    button.textContent = 'Copied';
+    setTimeout(function () {
+      button.textContent = original;
+    }, 1200);
+  }
+
+  Array.prototype.forEach.call(buttons, function (button) {
+    button.setAttribute('data-label', button.textContent);
+    button.addEventListener('click', function () {
+      var targetId = button.getAttribute('data-target');
+      var target = targetId ? document.getElementById(targetId) : null;
+      if (!target) {
+        return;
+      }
+      var text = target.textContent || '';
+      if (navigator.clipboard && navigator.clipboard.writeText) {
+        navigator.clipboard.writeText(text).then(
+          function () {
+            flash(button);
+          },
+          function () {
+            selectText(target);
+          }
+        );
+        return;
+      }
+      selectText(target);
+      try {
+        document.execCommand('copy');
+        flash(button);
+      } catch (err) {
+        // Selection is left in place so the user can copy manually.
+      }
+    });
+  });
+
+  function selectText(node) {
+    if (typeof window.getSelection !== 'function' || typeof document.createRange !== 'function') {
+      return;
+    }
+    var selection = window.getSelection();
+    var range = document.createRange();
+    range.selectNodeContents(node);
+    selection.removeAllRanges();
+    selection.addRange(range);
+  }
+})();`;
+// A snippet block: a titled hint, a <pre><code> with a stable id, and its copy
+// button. The code body is escaped so it survives interpolation verbatim.
+const snippetBlock = (id, title, hint, body) => `
+      <div class="connect-snippet">
+        <p class="connect-hint"><strong>${escapeHtml(title)}</strong> — ${hint}</p>
+        <pre><code id="${escapeHtml(id)}">${escapeHtml(body)}</code></pre>
+        <button class="connect-copy" type="button" data-target="${escapeHtml(id)}">Copy</button>
+      </div>`;
+const remoteSnippets = (mcpUrl, token) => {
+    // The bearer token MUST be an mcp-remote `--header` arg — mcp-remote does not
+    // read a MCP_AUTHORIZATION env var, so the env form leaves the request
+    // unauthenticated and mcp-remote falls back to a hanging OAuth flow.
+    const codexToml = `[mcp_servers.brainlink]
+command = "npx"
+args = ["-y", "mcp-remote", "${mcpUrl}", "--header", "Authorization: Bearer ${token}"]
+startup_timeout_sec = 60`;
+    const claudeCmd = `claude mcp add --transport http brainlink ${mcpUrl} --header "Authorization: Bearer ${token}"`;
+    const mcpJson = `{
+  "mcpServers": {
+    "brainlink": {
+      "type": "http",
+      "url": "${mcpUrl}",
+      "headers": {
+        "Authorization": "Bearer ${token}"
+      }
+    }
+  }
+}`;
+    const chatgptCmd = `Connector URL: ${mcpUrl}
+Authorization: Bearer ${token}`;
+    return `
+    <section class="connect-section" aria-labelledby="codexTitle">
+      <h2 id="codexTitle">Codex</h2>
+      ${snippetBlock('codexSnippet', '~/.codex/config.toml', 'add this MCP server block, then restart Codex.', codexToml)}
+    </section>
+    <section class="connect-section" aria-labelledby="claudeTitle">
+      <h2 id="claudeTitle">Claude Code</h2>
+      ${snippetBlock('claudeSnippet', 'terminal', 'register the remote server over streamable HTTP.', claudeCmd)}
+    </section>
+    <section class="connect-section" aria-labelledby="mcpJsonTitle">
+      <h2 id="mcpJsonTitle">.mcp.json</h2>
+      ${snippetBlock('mcpJsonSnippet', 'project .mcp.json', 'drop-in config for any MCP client that reads .mcp.json.', mcpJson)}
+    </section>
+    <section class="connect-section" aria-labelledby="chatgptTitle">
+      <h2 id="chatgptTitle">ChatGPT / generic MCP</h2>
+      ${snippetBlock('chatgptSnippet', 'connector', 'point a generic MCP connector at the endpoint with a bearer token.', chatgptCmd)}
+    </section>`;
+};
+const localSnippets = (vaultPath) => {
+    const codexToml = `[mcp_servers.brainlink]
+command = "brainlink"
+args = ["mcp-server", "--vault", "${vaultPath}"]
+startup_timeout_sec = 60`;
+    const claudeCmd = `claude mcp add brainlink -- brainlink mcp-server --vault ${vaultPath}`;
+    const mcpJson = `{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink",
+      "args": ["mcp-server", "--vault", "${vaultPath}"]
+    }
+  }
+}`;
+    return `
+    <section class="connect-section" aria-labelledby="codexTitle">
+      <h2 id="codexTitle">Codex</h2>
+      ${snippetBlock('codexSnippet', '~/.codex/config.toml', 'run the local MCP server over stdio, then restart Codex.', codexToml)}
+    </section>
+    <section class="connect-section" aria-labelledby="claudeTitle">
+      <h2 id="claudeTitle">Claude Code</h2>
+      ${snippetBlock('claudeSnippet', 'terminal', 'register the local stdio server.', claudeCmd)}
+    </section>
+    <section class="connect-section" aria-labelledby="mcpJsonTitle">
+      <h2 id="mcpJsonTitle">.mcp.json</h2>
+      ${snippetBlock('mcpJsonSnippet', 'project .mcp.json', 'drop-in stdio config for any MCP client that reads .mcp.json.', mcpJson)}
+    </section>`;
+};
+const modeBadge = (mode) => mode === 'remote'
+    ? '<div class="connect-mode">Mode <strong>Remote</strong> · authenticated over HTTPS with your token</div>'
+    : '<div class="connect-mode">Mode <strong>Local</strong> · stdio MCP server on this machine</div>';
+const endpointBlock = (data) => data.mode === 'remote'
+    ? `<div class="connect-endpoint">
+        <span>MCP endpoint</span>
+        <code>${escapeHtml(data.mcpUrl)}</code>
+        <span>Authorization</span>
+        <code>Bearer ${escapeHtml(data.token)}</code>
+      </div>`
+    : `<div class="connect-endpoint">
+        <span>Vault path</span>
+        <code>${escapeHtml(data.vaultPath)}</code>
+      </div>`;
+export const createConnectPageHtml = (data) => {
+    const snippets = data.mode === 'remote' ? remoteSnippets(data.mcpUrl, data.token) : localSnippets(data.vaultPath);
+    const lede = data.mode === 'remote'
+        ? 'Wire your agents and chats to this brainlink over the remote MCP endpoint. Paste a snippet, keep your token private.'
+        : 'Wire your agents and chats to this brainlink by running the local MCP server against your vault. Paste a snippet to get started.';
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Connect your agent · Brainlink</title>
+    <style>${connectStyles()}</style>
+  </head>
+  <body>
+    <main class="connect-card">
+      <div class="connect-brand">
+        <strong>Brainlink</strong>
+        <span>Connect your agent</span>
+      </div>
+      <p class="connect-lede">${escapeHtml(lede)}</p>
+      ${modeBadge(data.mode)}
+      ${endpointBlock(data)}
+      ${snippets}
+      <section class="connect-section" aria-labelledby="agentsTitle">
+        <h2 id="agentsTitle">Ready AGENTS.md</h2>
+        <p class="connect-hint">Drop this operating contract into your agent so it treats this brainlink as canonical memory.</p>
+        <div class="connect-snippet">
+          <pre><code id="agentsSnippet">${escapeHtml(connectAgentsMarkdown())}</code></pre>
+          <button class="connect-copy" type="button" data-target="agentsSnippet">Copy</button>
+        </div>
+      </section>
+      <a class="connect-back" href="/">&larr; Back to graph</a>
+    </main>
+    <script>${connectScript()}</script>
+  </body>
+</html>`;
+};

package/dist/application/server/routes.js

@@ -29,6 +29,7 @@ import { getGraphVersion } from './graph-version.js';
 import { readAuthStatus, readEditableSettings, updateEditableSettings } from './settings-store.js';
 import { connectVaultRemote, ensureDeployKey, readVersioningStatus } from './versioning.js';
 import { createSettingsPageHtml } from '../frontend/settings-page.js';
+import { createConnectPageHtml } from '../frontend/connect-page.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 import { parseMultipartForm } from './multipart.js';
 const readRuntimeDefaults = async (url) => {
@@ -90,6 +91,29 @@ const requestIsSecure = (request) => {
     const proto = firstHeaderValue(request.headers['x-forwarded-proto']);
     return typeof proto === 'string' && proto.split(',')[0]?.trim() === 'https';
 };
+// Resolve the "Connect your agent" page data at request time. Remote mode is
+// picked only when the server is exposed (auth-gated) AND an MCP token is
+// configured: only then can we hand out a working bearer + public endpoint.
+// Otherwise the page falls back to the local stdio config and never shows a
+// token. The host prefers the proxy-forwarded value since exposed mode sits
+// behind a TLS-terminating reverse proxy.
+const resolveConnectHost = (request, url) => {
+    const forwarded = firstHeaderValue(request.headers['x-forwarded-host']);
+    const forwardedHost = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : '';
+    if (forwardedHost) {
+        return forwardedHost;
+    }
+    const host = firstHeaderValue(request.headers.host);
+    return typeof host === 'string' && host.length > 0 ? host : url.host;
+};
+const resolveConnectPageData = (request, url, vaultPath, requireAuth) => {
+    const token = process.env.BRAINLINK_MCP_TOKEN?.trim() ?? '';
+    if (requireAuth && token.length > 0) {
+        const host = resolveConnectHost(request, url);
+        return { mode: 'remote', mcpUrl: `https://${host}/mcp`, token, vaultPath };
+    }
+    return { mode: 'local', mcpUrl: '', token: '', vaultPath };
+};
 const isHtmlNavigation = (request, url) => {
     if (url.pathname.startsWith('/api/')) {
         return false;
@@ -566,6 +590,12 @@ export const route = async (request, url, vaultPath, options = {}) => {
     if (isReadMethod(request) && url.pathname === '/settings') {
         return createResponse(createSettingsPageHtml(), 200, contentTypes['.html']);
     }
+    // "Connect your agent": ready-to-paste MCP setup for wiring agents to this
+    // brainlink. Auth-gated with the rest of the exposed graph (runAuthGate ran
+    // above), so it may surface the owner's bearer token in remote mode.
+    if (isReadMethod(request) && url.pathname === '/connect') {
+        return createResponse(createConnectPageHtml(resolveConnectPageData(request, url, vaultPath, options.requireAuth === true)), 200, contentTypes['.html']);
+    }
     // Vault git versioning: generate an SSH deploy key on demand and connect a
     // GitHub repo (clone-and-aggregate, conflict-preserving — never overwrites).
     if (isReadMethod(request) && url.pathname === '/api/versioning-status') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",