@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/runtime/mcpClient.js

@@ -13,14 +13,46 @@ export class McpClientWrapper {
      * blowing up, which the agent's existing try/catch wrappers already handle.
      */
     connected = false;
+    /**
+     * 10a: cached identity. Set once by `detectMcpIdentity` after the first
+     * successful `listTools()` (or by `connect` if the config + URL gave us
+     * a clear signal). The value drives status surfaces and the brain-offline
+     * prompt swap — distinguishes "our brain went down" from "a random
+     * third-party MCP went down" once item 11's multi-MCP support lands.
+     */
+    identity = 'unknown';
+    serverName;
     constructor() {
-        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.5' }, { capabilities: {} });
+        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.7' }, { capabilities: {} });
     }
     /** Whether this wrapper has an active MCP transport. */
     isConnected() {
         return this.connected;
     }
-    async connect(serverConfig, llmConfig) {
+    /** 10a: who is this MCP? Set by `detectMcpIdentity`; 'unknown' before first list. */
+    getIdentity() {
+        return this.identity;
+    }
+    /** 10a: profile name passed at connect (`brainrouter` / `local-http` / etc.). */
+    getServerName() {
+        return this.serverName;
+    }
+    /**
+     * 10a: connect with an optional `name` so the wrapper can render identity
+     * tags ("BrainRouter MCP offline" vs "third-party MCP offline") without
+     * the caller threading it through every error path. The pre-10a single-
+     * arg form remains supported — callers that don't pass a name fall back
+     * to URL-pattern detection.
+     */
+    async connect(serverConfig, llmConfig, name) {
+        this.serverName = name;
+        // Resolve identity upfront from config metadata + name/URL patterns.
+        // The tool-signature fallback (memory_recall + list_skills) runs after
+        // the first successful `listTools` in `refreshIdentityFromTools`.
+        this.identity = resolveIdentityFromConfig(serverConfig, name);
+        return this._connect(serverConfig, llmConfig);
+    }
+    async _connect(serverConfig, llmConfig) {
         if (serverConfig.type === 'stdio') {
             if (!serverConfig.command) {
                 throw new Error('Stdio server configuration missing "command".');
@@ -107,16 +139,11 @@ export class McpClientWrapper {
             if (llmConfig?.model && !mergedEnv.BRAINROUTER_LLM_MODEL) {
                 mergedEnv.BRAINROUTER_LLM_MODEL = llmConfig.model;
             }
-            // Loud diagnostic: if NO LLM key reached the child, server-side
-            // memory extraction is dead — every sensory capture will pile up
-            // un-extracted. Print a yellow banner so the user knows BEFORE they
-            // see "0 records" in every briefing.
-            if (!mergedEnv.BRAINROUTER_LLM_API_KEY) {
-                console.warn('\n⚠️  No LLM API key reached the MCP child. Sensory turns will be ' +
-                    'captured but cognitive extraction (the thing that makes them ' +
-                    'searchable) will fail silently. Set OPENAI_API_KEY or ' +
-                    'BRAINROUTER_LLM_API_KEY before starting brainrouter.\n');
-            }
+            // (Previously: a loud console.warn here if no LLM API key reached the
+            // MCP child. That message landed above the Ink banner and looked like a
+            // CLI error even though it was a server-side concern. Server-side
+            // extraction failures should surface through MCP's own status channel —
+            // not by the CLI second-guessing what the server needs.)
             // Spawn the MCP child with cwd set to the MCP package directory if we
             // can find it from the first arg (typically
             // `node /path/to/BrainRouter/brainrouter/dist/index.js`). The child
@@ -147,6 +174,14 @@ export class McpClientWrapper {
                 args: serverConfig.args ?? [],
                 env: mergedEnv,
                 cwd: childCwd,
+                // The MCP child is a separate process with its own concerns (its own
+                // dotenv, its own auth failures, its own platform warnings). Inheriting
+                // its stderr meant every `[BrainRouter] FATAL …`, every dotenv banner,
+                // every SQLite ExperimentalWarning leaked above our Ink chat banner
+                // and looked like the CLI was crashing. Pipe it so the SDK owns the
+                // stream; the CLI can surface a single graceful "MCP unreachable" line
+                // through its own offline-mode flow instead.
+                stderr: 'pipe',
             });
             await this.client.connect(this.transport);
             this.connected = true;
@@ -178,7 +213,22 @@ export class McpClientWrapper {
         // with only local tools instead of crashing when it tries to enumerate.
         if (!this.connected)
             return { tools: [] };
-        return this.client.listTools({});
+        const res = await this.client.listTools({});
+        // 10a: tool-signature fallback for identity detection. If the config +
+        // URL didn't already pin the identity, the BrainRouter MCP exposes a
+        // distinctive pair (`memory_recall` AND `list_skills`) that no neutral
+        // third-party MCP will. Cache the result so the next list doesn't
+        // re-probe — identity is stable for the lifetime of a connection.
+        if (this.identity === 'unknown' && Array.isArray(res?.tools)) {
+            const names = new Set(res.tools.map((t) => t?.name));
+            if (names.has('memory_recall') && names.has('list_skills')) {
+                this.identity = 'brainrouter';
+            }
+            else {
+                this.identity = 'third-party';
+            }
+        }
+        return res;
     }
     async callTool(name, args) {
         // Offline mode: synthesize an error envelope that downstream consumers
@@ -232,3 +282,44 @@ export class McpClientWrapper {
         this.connected = false;
     }
 }
+/**
+ * 10a: figure out who an MCP profile belongs to from config metadata + name
+ * + URL alone, before any network call. Explicit `identity` wins; otherwise
+ * we check name prefix and URL host. Returns 'unknown' when nothing matches
+ * — the caller (currently `listTools`) falls back to tool-signature
+ * detection after the first successful enumeration.
+ *
+ * Detection cases:
+ *   - explicit `identity: 'brainrouter'` or `identity: 'third-party'` → that.
+ *   - profile name (case-insensitive) starts with `brainrouter` → brainrouter.
+ *   - http URL hostname matches `*.brainrouter.cloud` / `*.brainrouter.dev`
+ *     / `*.brainrouter.io` / `*.kinqs.brainrouter.*` → brainrouter.
+ *   - stdio command basename matches `brainrouter` / `brainrouter-mcp` → brainrouter.
+ *   - otherwise → unknown (let the tool-signature fallback decide).
+ */
+export function resolveIdentityFromConfig(serverConfig, name) {
+    if (serverConfig.identity === 'brainrouter' || serverConfig.identity === 'third-party') {
+        return serverConfig.identity;
+    }
+    if (name && /^brainrouter/i.test(name.trim())) {
+        return 'brainrouter';
+    }
+    if (serverConfig.type === 'http' && serverConfig.url) {
+        try {
+            const url = new URL(serverConfig.url);
+            if (/\.brainrouter\.(cloud|dev|io|com|app)$/i.test(url.hostname)) {
+                return 'brainrouter';
+            }
+        }
+        catch {
+            // Malformed URL; let later code surface the connection error.
+        }
+    }
+    if (serverConfig.type === 'stdio' && serverConfig.command) {
+        const base = serverConfig.command.split(/[/\\]/).pop() ?? '';
+        if (/^brainrouter(-mcp)?$/i.test(base)) {
+            return 'brainrouter';
+        }
+    }
+    return 'unknown';
+}

package/dist/runtime/mcpPool.d.ts

@@ -0,0 +1,162 @@
+import { McpClientWrapper } from './mcpClient.js';
+import type { LLMConfig, ServerConfig } from '../config/config.js';
+/**
+ * 0.3.7 — Multi-MCP support. Wraps a `Map<serverId, McpClientWrapper>`
+ * and exposes the same public API as a single wrapper (`isConnected`,
+ * `getIdentity`, `getServerName`, `listTools`, `callTool`, `close`),
+ * so existing call-sites that hold an `mcpClient` reference keep
+ * working unchanged.
+ *
+ * Pattern lifted from Claude Code's `.mcp.json` model (see
+ * `openSrc/claude-code/CHANGELOG.md` — concurrent startup at line 688,
+ * tool prefixing at line 1515, graceful degradation at line 189). Our
+ * shape:
+ *
+ *   - All configured servers attempt connection concurrently on boot,
+ *     each with a 5s timeout. Offline ones do NOT block others.
+ *   - Tools surface to the agent with `mcp_<serverId>_<toolName>`
+ *     prefix (Claude Code style).
+ *   - `callTool` accepts BOTH the prefixed form (the canonical name
+ *     the LLM sees in the tool inventory) AND the raw form (back-compat
+ *     for the existing system prompt and skills that hardcode
+ *     `memory_recall` etc.). Raw form routes to the unique server
+ *     providing that tool name; collision (two servers expose the same
+ *     unprefixed name) returns a helpful error pointing at the
+ *     prefixed form.
+ *
+ * Future versions may drop the raw-name fallback once skills and
+ * prompts are migrated to prefixed names; the pool then becomes the
+ * pure Claude Code shape. Until then the dual-name resolution is a
+ * transition aid documented in CHANGELOG `[0.3.7]`.
+ */
+export type McpServerStatus = {
+    serverId: string;
+    identity: 'brainrouter' | 'third-party' | 'unknown';
+    /** 'connected' once the underlying wrapper reports isConnected. */
+    status: 'connected' | 'connecting' | 'offline' | 'failed';
+    /** Filled after the first successful listTools (used by /mcp list). */
+    toolCount?: number;
+    /** Per-server error message when status === 'failed'. */
+    error?: string;
+};
+/**
+ * Choose which configured MCP profiles should connect for a normal CLI run.
+ *
+ * BrainRouter profiles are special: users may store several BrainRouter MCPs
+ * (local, staging, remote, self-hosted), but only one should be active at a
+ * time because the BrainRouter MCP is the memory/brain plane. Third-party MCPs
+ * are additive tools, so they all connect concurrently.
+ *
+ * `requestedProfile` is the explicit escape hatch (`--profile <name>`): it
+ * scopes the run to exactly that profile, matching the existing single-server
+ * mode.
+ */
+export declare function selectMcpServerIds(servers: Record<string, ServerConfig>, activeServer?: string, requestedProfile?: string): string[];
+export declare class McpClientPool {
+    /** serverId → connected wrapper. */
+    private clients;
+    /** serverId → status entry (kept even for failed/offline servers so /mcp can render them). */
+    private statuses;
+    /**
+     * Unprefixed tool name → owning serverId. Sentinel `__COLLISION__`
+     * marks tool names exposed by multiple servers (must be addressed
+     * via the prefixed form).
+     */
+    private toolToServer;
+    /** Prefixed form (`mcp_<serverId>_<tool>`) → `{serverId, tool}` for fast dispatch. */
+    private prefixedToServer;
+    /** LLM config from the last connectAll — needed for reconnect calls. */
+    private currentLlmConfig?;
+    /** Raw server configs from the last connectAll — needed for /mcp reconnect <id>. */
+    private serverConfigs;
+    /** serverId → prefix used in tool names. Brainrouter servers get "brainrouter"; others keep their config key. */
+    private prefixIds;
+    /** Reverse: prefixId → serverId (needed to dispatch `mcp_brainrouter_X` back to the real key). */
+    private prefixToServerId;
+    private getPrefixId;
+    private assignPrefixId;
+    /**
+     * Connect to every entry in `servers` concurrently. Each connect
+     * gets its own timeout; offline servers don't block the others.
+     * Returns the status array after all connects settle.
+     */
+    connectAll(servers: Record<string, ServerConfig>, llmConfig?: LLMConfig, options?: {
+        timeoutMs?: number;
+        onStatusChange?: (s: McpServerStatus) => void;
+    }): Promise<McpServerStatus[]>;
+    /**
+     * Connect a single server. Used both by `connectAll` and by
+     * `/mcp connect <id>` for late-joining servers. Idempotent — if
+     * the server is already connected, closes the previous wrapper first.
+     */
+    connectOne(serverId: string, config: ServerConfig, llmConfig?: LLMConfig, timeoutMs?: number): Promise<void>;
+    /** Tear down a single server. Removes it from the pool and rebuilds the tool index. */
+    disconnectOne(serverId: string): Promise<void>;
+    /** Reconnect: close + connect again using the stashed config. */
+    reconnectOne(serverId: string): Promise<void>;
+    /**
+     * Walk every connected client and rebuild the tool→server indices.
+     * Called after every connect / disconnect / reconnect so the
+     * dispatch path stays correct without re-fetching tools on every
+     * `callTool`.
+     */
+    private refreshToolIndex;
+    /**
+     * Concatenated tool list across every connected server, with names
+     * prefixed `mcp_<serverId>_<toolName>` (Claude Code style). The
+     * agent calls this once per turn and hands it to the LLM.
+     */
+    listTools(): Promise<{
+        tools: any[];
+    }>;
+    /**
+     * Route a tool call to the right server. Accepts both name forms:
+     *
+     *   - `mcp_<serverId>_<tool>` — the canonical form the LLM sees
+     *     in the inventory. Stripped + dispatched directly.
+     *   - `<tool>` raw form — back-compat for prompts/skills that
+     *     hardcode `memory_recall`-style names. Routed to the unique
+     *     server providing that tool. Returns a helpful error if two
+     *     servers expose the same name (caller must use the prefix).
+     */
+    callTool(name: string, args: Record<string, any>): Promise<any>;
+    /** Internal — map a name (prefixed OR raw) to a concrete server + tool. */
+    private resolveToolCall;
+    /** True iff at least one server is connected. */
+    isConnected(): boolean;
+    /**
+     * Identity precedence: any connected `brainrouter` > any connected
+     * `third-party` > `unknown`. The CLI banner + offline prompt swap
+     * branch on this — "BrainRouter is offline" makes sense only when
+     * we expected one and didn't get one.
+     */
+    getIdentity(): 'brainrouter' | 'third-party' | 'unknown';
+    /**
+     * Human-readable summary for the banner/statusline. Single-server
+     * pools render just the server name; multi-server pools render
+     * a count + the first few names.
+     */
+    getServerName(): string | undefined;
+    /**
+     * Look up a wrapper by serverId. Used by `/mcp tools <server>` and
+     * similar commands that want to talk to one specific server.
+     */
+    getClient(serverId: string): McpClientWrapper | undefined;
+    /**
+     * Find the connected wrapper whose identity is 'brainrouter'. Some
+     * code paths (memory capture, working-memory offload) specifically
+     * need the canonical brain regardless of how many third-party MCPs
+     * the user added.
+     */
+    getBrainrouterClient(): McpClientWrapper | undefined;
+    /** Server id for the currently connected BrainRouter MCP, if one is active. */
+    getActiveBrainrouterServerId(): string | undefined;
+    /** Status snapshot for every server the pool has tried to connect to. */
+    getStatuses(): McpServerStatus[];
+    /** Status for one server (returns undefined if the pool has never seen it). */
+    getStatus(serverId: string): McpServerStatus | undefined;
+    /** List of serverIds currently held by the pool (connected or not). */
+    getServerIds(): string[];
+    /** Close every wrapper. Used on CLI exit. */
+    close(): Promise<void>;
+}