@kinqs/brainrouter-mcp-server 0.3.4 → 0.3.5

package/README.md

@@ -1,6 +1,14 @@
-# @kinqs/brainrouter-mcp-server
+# `@kinqs/brainrouter-mcp-server`
 
-The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradiollc/BrainRouter) — exposed as a [Model Context Protocol](https://modelcontextprotocol.io/) server so any MCP-speaking agent (Claude Desktop, Cursor, [`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli), custom clients) can recall, capture, and reason over long-term memory.
+The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradiollc/BrainRouter)
+— exposed as a [Model Context Protocol](https://modelcontextprotocol.io/)
+server so any MCP-speaking agent (Claude Desktop, Cursor,
+[`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli),
+custom clients) can recall, capture, and reason over long-term memory.
+
+Ships the `brainrouter-mcp` binary.
+
+---
 
 ## What it gives you
 
@@ -10,46 +18,111 @@ The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradioll
 - **Skill catalogue** — `list_skills`, `get_skill`, `search_skills`, `get_persona` — ships with 70+ canonical skills bundled at publish time.
 - **HTTP and stdio transports** — run as a hosted service (HTTP/SSE) or spawn as a stdio child from any MCP client.
 
+---
+
 ## Install
 
 ```bash
-npm install @kinqs/brainrouter-mcp-server
+npm install -g @kinqs/brainrouter-mcp-server
 ```
 
-## Run
+The `-g` flag is required so `brainrouter-mcp` lands on your `$PATH`.
+See [`@kinqs/brainrouter-cli`'s README](https://www.npmjs.com/package/@kinqs/brainrouter-cli)
+for the sudo / nvm caveats — the same rules apply.
 
-```bash
-# HTTP transport on :3747
-npx brainrouter-mcp --http --port 3747
+Verify:
 
-# stdio (default — for clients that spawn the server themselves)
-npx brainrouter-mcp
+```bash
+which brainrouter-mcp
+brainrouter-mcp --version    # prints 0.3.5
 ```
 
+---
+
 ## Configure
 
-Copy `.env.example` to `.env` and set at minimum:
+The server reads its config from a `.env` file. The challenge for a
+globally-installed package is that you don't know where the package
+lives, and even if you did, it's typically in a path you can't easily
+edit (`/usr/local/lib/node_modules/...` or similar). To fix that, the
+server looks for `.env` in three places, in order:
+
+1. `$BRAINROUTER_ENV_FILE` — explicit override (set this when you want a
+   per-project or per-deployment config).
+2. `~/.config/brainrouter/server.env` — the canonical user location.
+3. `./.env` — current working directory (matches the classic dotenv
+   behavior; useful for monorepo dev).
+
+At startup the server prints which path it loaded from, so there's never
+any ambiguity:
+
+```
+env: loaded 17 vars from /Users/you/.config/brainrouter/server.env
+```
+
+### One-time setup
 
 ```bash
+brainrouter-mcp init             # scaffolds ~/.config/brainrouter/server.env
+$EDITOR ~/.config/brainrouter/server.env
+```
+
+`init` copies the package's bundled `.env.example` to
+`~/.config/brainrouter/server.env` and chmods it to `0600`. It won't
+overwrite an existing file.
+
+### Minimum fields to set
+
+```bash
+# Cognitive extraction LLM (any OpenAI-compatible endpoint:
+# OpenAI, OpenRouter, LM Studio, Ollama, vLLM…)
 BRAINROUTER_LLM_API_KEY=sk-...
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
+# Embeddings — required for vector recall. Key falls back to BRAINROUTER_LLM_API_KEY.
 BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
 BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
 BRAINROUTER_EMBEDDING_DIMENSIONS=1536
 
+# Server auth — change before exposing the server
 BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
-BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret  # `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+```
+
+Full knob list (reranker, prewarming, focus-scene triggers, sweep
+intervals, JWT, CORS) lives in the bundled `.env.example` — view it
+after `init` ran, or directly with:
+
+```bash
+cat "$(npm root -g)/@kinqs/brainrouter-mcp-server/.env.example"
 ```
 
-Full knob list (reranker, prewarming, focus-scene triggers, sweep intervals, JWT, CORS) lives in `.env.example` next to this README.
+---
+
+## Run
+
+```bash
+# HTTP transport on :3747 — what the CLI connects to via login
+brainrouter-mcp --http --port 3747
+
+# stdio transport — for clients that spawn the server themselves
+brainrouter-mcp
+```
+
+The server writes logs to stderr. To leave it running detached, use a
+process manager (launchd / systemd / tmux / `nohup`) of your choice.
+
+---
 
 ## Docs
 
-- [BrainRouter overview](https://github.com/kinqsradiollc/BrainRouter)
-- [What the memory engine does](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
-- [Deep dives](https://github.com/kinqsradiollc/BrainRouter/tree/main/brainrouter-docs)
+- **Repo**: <https://github.com/kinqsradiollc/BrainRouter>
+- **Memory engine deep-dive**: [BRAINROUTER.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
+- **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
+- **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
+
+---
 
 ## License
 

package/dist/env-loader.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/env-loader.js

@@ -0,0 +1,47 @@
+// Side-effect module: imported FIRST in src/index.ts so it sets process.env
+// from the right .env file BEFORE any other module evaluates and tries to
+// read those vars.
+//
+// Priority order (first hit wins):
+//   1. $BRAINROUTER_ENV_FILE              (explicit user override)
+//   2. ~/.config/brainrouter/server.env   (canonical user location — the
+//                                          one a globally-installed
+//                                          `npm i -g @kinqs/brainrouter-mcp-server`
+//                                          user should write to)
+//   3. ./.env                              (cwd — matches dotenv default,
+//                                          keeps monorepo dev working)
+//
+// The third entry matches dotenv's classic behavior, so existing
+// `cd brainrouter/ && npm run start:http` workflows keep loading
+// `brainrouter/.env` exactly as before. The first two are the additions
+// that fix the global-install UX (users no longer need to cd anywhere
+// special).
+import dotenv from 'dotenv';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+function resolveEnvFile() {
+    const candidates = [
+        process.env.BRAINROUTER_ENV_FILE,
+        path.join(os.homedir(), '.config', 'brainrouter', 'server.env'),
+        path.join(process.cwd(), '.env'),
+    ].filter(Boolean);
+    for (const file of candidates) {
+        if (fs.existsSync(file))
+            return file;
+    }
+    return null;
+}
+const envFile = resolveEnvFile();
+if (envFile) {
+    const result = dotenv.config({ path: envFile });
+    const count = Object.keys(result.parsed ?? {}).length;
+    process.stderr.write(`env: loaded ${count} var${count === 1 ? '' : 's'} from ${envFile}\n`);
+}
+else {
+    process.stderr.write(`env: no .env file found — looked at:\n` +
+        `  $BRAINROUTER_ENV_FILE  (${process.env.BRAINROUTER_ENV_FILE ? 'set, but missing' : 'unset'})\n` +
+        `  ~/.config/brainrouter/server.env\n` +
+        `  ${path.join(process.cwd(), '.env')}\n` +
+        `Run 'brainrouter-mcp init' to scaffold one (or set BRAINROUTER_LLM_API_KEY and friends in your shell).\n`);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+import './init.js';
+import './env-loader.js';

package/dist/index.js

@@ -14,6 +14,17 @@
 //     Runs an Express HTTP server. Connect via serverUrl in tool config.
 //     Usage: node dist/index.js --root /path/to/project --http --port 3747
 //
+//   init subcommand
+//     Scaffold ~/.config/brainrouter/server.env from the bundled
+//     .env.example and exit. Run this once after a global install.
+//     Usage: brainrouter-mcp init
+//
+// CRITICAL: import order matters. `init` may exit the process before
+// anything else loads (for `brainrouter-mcp init`). `env-loader` runs next
+// and sets process.env from the right .env file before any module body
+// reads env vars (sqlite/embedding/extractor all do at load time).
+import './init.js';
+import './env-loader.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -91,7 +102,7 @@ const PORT = parseInt(parseFlag('--port') ?? '3747', 10);
 function buildMcpServer(registry, options) {
     const defaultUserId = options?.defaultUserId ?? STDIO_DEFAULT_USER_ID;
     const isAdmin = options?.isAdmin ?? false;
-    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.4' }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.5' }, { capabilities: { tools: {} } });
     // ── Tool list ──────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [

package/dist/init.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/init.js

@@ -0,0 +1,64 @@
+// Side-effect module: imported FIRST in src/index.ts (before env-loader).
+//
+// Handles the `brainrouter-mcp init` subcommand by scaffolding a user-editable
+// .env file at ~/.config/brainrouter/server.env from the package's bundled
+// .env.example, then exiting. Never returns control when invoked.
+//
+// This solves the global-install UX gap: a user who runs
+// `npm install -g @kinqs/brainrouter-mcp-server` has no obvious place to put
+// their LLM credentials. `brainrouter-mcp init` creates the file in a known
+// user-writable location that env-loader.ts then auto-finds.
+//
+// If the file already exists, init prints the path so the user knows where
+// to edit it — but does NOT overwrite (don't clobber a user's real config).
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import url from 'node:url';
+function runInit() {
+    const userConfigDir = path.join(os.homedir(), '.config', 'brainrouter');
+    const userEnvFile = path.join(userConfigDir, 'server.env');
+    // .env.example sits at the package root (one level above src/ in source,
+    // one level above dist/ after build, both layouts work in the installed
+    // tarball because the `files` allowlist in package.json includes it).
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const exampleCandidates = [
+        path.resolve(here, '..', '.env.example'), // dist/init.js → ../.env.example
+        path.resolve(here, '..', '..', '.env.example'), // src/init.ts (dev) → ../../.env.example
+    ];
+    const examplePath = exampleCandidates.find((p) => fs.existsSync(p));
+    if (!examplePath) {
+        process.stderr.write(`init: couldn't find .env.example bundled with the package.\n` +
+            `Checked:\n${exampleCandidates.map((p) => `  ${p}`).join('\n')}\n` +
+            `This is a packaging bug — please file an issue at ` +
+            `https://github.com/kinqsradiollc/BrainRouter/issues\n`);
+        process.exit(1);
+    }
+    if (fs.existsSync(userEnvFile)) {
+        process.stdout.write(`init: ${userEnvFile} already exists — not overwriting.\n` +
+            `Edit it with: $EDITOR ${userEnvFile}\n` +
+            `(Or compare against the latest template at ${examplePath})\n`);
+        process.exit(0);
+    }
+    fs.mkdirSync(userConfigDir, { recursive: true });
+    fs.copyFileSync(examplePath, userEnvFile);
+    // Tighten perms — this file will hold API keys + a JWT secret.
+    try {
+        fs.chmodSync(userEnvFile, 0o600);
+    }
+    catch { /* best effort */ }
+    process.stdout.write(`init: created ${userEnvFile}\n` +
+        `\n` +
+        `Next steps:\n` +
+        `  1. Edit it:                 $EDITOR ${userEnvFile}\n` +
+        `  2. Set BRAINROUTER_LLM_API_KEY (required for cognitive extraction)\n` +
+        `  3. Change BRAINROUTER_ADMIN_PASSWORD and BRAINROUTER_JWT_SECRET\n` +
+        `  4. Start the server:        brainrouter-mcp --http --port 3747\n` +
+        `\n` +
+        `The server auto-finds this file via ~/.config/brainrouter/server.env\n` +
+        `(or set BRAINROUTER_ENV_FILE=/some/other/path to override).\n`);
+    process.exit(0);
+}
+if (process.argv.includes('init')) {
+    runInit();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-mcp-server",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "BrainRouter MCP server — the cognitive memory engine. Exposes recall, capture, focus scenes, persona, contradictions, skills, and graph queries as MCP tools for any MCP-speaking agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
     "gray-matter": "^4.0.3",
     "sqlite-vec": "^0.1.9",
     "zod": "^3.22.4",
-    "@kinqs/brainrouter-types": "^0.3.4"
+    "@kinqs/brainrouter-types": "^0.3.5"
   },
   "engines": {
     "node": ">=22.0.0"