@littlebigbrain/mcp 0.2.4 → 0.2.5

package/README.md

@@ -41,7 +41,7 @@ Run against any data-plane endpoint with a stack API key:
       "command": "npx",
       "args": ["-y", "@littlebigbrain/mcp"],
       "env": {
-        "LBB_BASE_URL": "https://db.eu.littlebigbrain.com",
+        "LBB_BASE_URL": "https://0abc1def--production.db.eu.littlebigbrain.com",
         "LBB_API_KEY": "lbb_sk_live_..."
       }
     }
@@ -50,6 +50,9 @@ Run against any data-plane endpoint with a stack API key:
 ```
 
 Set `LBB_GRAPH` or `LBB_BRANCH` to target a scope other than `main`.
+`LBB_BASE_URL` has no hosted default: copy `endpoint_url` from the stack's
+Connect page. The MCP process exits with a configuration error when it is
+missing.
 
 ## Tools
 
@@ -77,7 +80,7 @@ For self-hosting behind your own auth, the package also serves the tools over HT
 import { createMcpHttpServer } from "@littlebigbrain/mcp";
 
 createMcpHttpServer({
-  baseUrl: "https://db.eu.littlebigbrain.com",
+  baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com",
   mcpPath: "/mcp",
   allowedHosts: ["127.0.0.1", "localhost", "::1"],
 }).listen(8080, "127.0.0.1");

package/dist/http-server.d.ts

@@ -1,7 +1,8 @@
 import { type IncomingMessage, type Server } from "node:http";
 import { LbbClient } from "@littlebigbrain/client";
 export interface McpHttpServerOptions {
-    baseUrl?: string;
+    /** Required Little Big Brain stack endpoint (`endpoint_url` from Connect). */
+    baseUrl: string;
     mcpPath?: string;
     maxBodyBytes?: number;
     requestTimeoutMs?: number;
@@ -30,4 +31,4 @@ export declare function readJsonBody(req: IncomingMessage, maxBodyBytes?: number
  * Build the key-bearer streamable-HTTP MCP edge without starting a listener.
  * The hosted multi-tenant OAuth endpoint remains in the SaaS API.
  */
-export declare function createMcpHttpServer(options?: McpHttpServerOptions): Server;
+export declare function createMcpHttpServer(options: McpHttpServerOptions): Server;

package/dist/http-server.js

@@ -96,13 +96,16 @@ export function readJsonBody(req, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
  * Build the key-bearer streamable-HTTP MCP edge without starting a listener.
  * The hosted multi-tenant OAuth endpoint remains in the SaaS API.
  */
-export function createMcpHttpServer(options = {}) {
-    const baseUrl = options.baseUrl ?? "https://db.eu.littlebigbrain.com";
+export function createMcpHttpServer(options) {
+    const baseUrl = options.baseUrl.trim();
     const mcpPath = options.mcpPath ?? "/mcp";
     const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
     const requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
     const allowedHosts = options.allowedHosts;
     const allowedOrigins = options.allowedOrigins ?? [];
+    if (!baseUrl) {
+        throw new Error("baseUrl is required; copy endpoint_url from the stack's Connect page");
+    }
     if (!mcpPath.startsWith("/"))
         throw new Error("mcpPath must start with /");
     if (!Number.isInteger(maxBodyBytes) || maxBodyBytes <= 0) {

package/dist/http.js

@@ -20,8 +20,12 @@ function csv(value) {
     return items && items.length > 0 ? items : undefined;
 }
 const mcpPath = process.env.LBB_MCP_PATH ?? "/mcp";
+const baseUrl = process.env.LBB_BASE_URL?.trim();
+if (!baseUrl) {
+    throw new Error("LBB_BASE_URL is required. Copy endpoint_url from your stack's Connect page, for example https://<tenant-short-id>--<stack-slug>.db.eu.littlebigbrain.com");
+}
 const httpServer = createMcpHttpServer({
-    baseUrl: process.env.LBB_BASE_URL ?? "https://db.eu.littlebigbrain.com",
+    baseUrl,
     mcpPath,
     allowedHosts: csv(process.env.LBB_MCP_ALLOWED_HOSTS) ??
         (isLoopback ? LOOPBACK_HOSTS : undefined),

package/dist/stdio.js

@@ -1,27 +1,75 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { LbbClient } from "@littlebigbrain/client";
 import { buildLbbServer } from "./server.js";
+const BASE_URL_HELP = "LBB_BASE_URL is required. Copy endpoint_url from your Little Big Brain stack's Connect page.";
 /**
  * Local stdio entrypoint (`npx @littlebigbrain/mcp`). Reads the connection from the
  * environment and serves the little big brain tools over stdio, the transport every
  * editor (Claude Code, Cursor, Codex) supports.
  *
- *   LBB_BASE_URL  (default http://127.0.0.1:7400)
+ *   LBB_BASE_URL  (required for tool calls; copy endpoint_url from the stack Connect page)
  *   LBB_API_KEY   stack API key (lbb_sk_live_…) or single-mode token
  *   LBB_GRAPH / LBB_BRANCH  (optional; server defaults to main/main)
+ *
+ * The base URL is required lazily, at the first tool invocation, not at
+ * process start: MCP hosts launch servers to complete the initialize
+ * handshake and list tools before the user has finished configuring them,
+ * and a startup crash surfaces as an opaque "server failed to start" in
+ * every editor. An unconfigured server therefore boots, handshakes, and
+ * lists tools normally — and every tool call fails with the actionable
+ * message above until LBB_BASE_URL is set. (There is deliberately no
+ * localhost default: pointing production tool calls at 127.0.0.1 silently
+ * was worse than failing loudly.)
  */
-async function main() {
-    const client = new LbbClient({
-        baseUrl: process.env.LBB_BASE_URL ?? "http://127.0.0.1:7400",
-        apiKey: process.env.LBB_API_KEY,
-        graph: process.env.LBB_GRAPH,
-        branch: process.env.LBB_BRANCH,
+export function unconfiguredClient() {
+    return new Proxy({}, {
+        get(_target, property) {
+            // Allow the runtime's duck-typing probes without exploding.
+            if (property === "then" || typeof property === "symbol")
+                return undefined;
+            throw new Error(BASE_URL_HELP);
+        },
     });
+}
+async function main() {
+    const baseUrl = process.env.LBB_BASE_URL?.trim();
+    if (!baseUrl) {
+        console.error(`warning: ${BASE_URL_HELP} Tool calls will fail until it is set.`);
+    }
+    const client = baseUrl
+        ? new LbbClient({
+            baseUrl,
+            apiKey: process.env.LBB_API_KEY,
+            graph: process.env.LBB_GRAPH,
+            branch: process.env.LBB_BRANCH,
+        })
+        : unconfiguredClient();
     const server = buildLbbServer(client);
     await server.connect(new StdioServerTransport());
 }
-main().catch((error) => {
-    console.error(error);
-    process.exit(1);
-});
+// Only start the server when executed as the bin entrypoint — importing this
+// module (e.g. the unconfiguredClient unit tests) must not attach a stdio
+// transport to the host process, which would hold its stdin open forever.
+// npm installs bins as symlinks, so argv[1] must be realpath'd before
+// comparing against import.meta.url (which is always the resolved file).
+function entrypointHref() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return undefined;
+    try {
+        return pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return pathToFileURL(argv1).href;
+    }
+}
+const invokedAsBin = import.meta.url === entrypointHref();
+if (invokedAsBin) {
+    main().catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "MCP server for little big brain — graph and hybrid search tools for agents",
   "license": "Apache-2.0",
   "repository": {