@littlebigbrain/mcp 0.2.3 → 0.2.5

package/README.md

@@ -1,12 +1,10 @@
 # @littlebigbrain/mcp
 
-Eleven task-shaped MCP tools for searching, querying, and writing a little big
-brain graph from Claude, Cursor, Codex, or another MCP client.
+Eleven task-shaped [MCP](https://modelcontextprotocol.io) tools that let Claude, Cursor, Codex, or any MCP client search, query, and write a [Little Big Brain](https://littlebigbrain.com) graph. Ships two ways: a hosted endpoint with OAuth sign-in, and a local stdio server.
 
-## Hosted OAuth
+## Hosted (OAuth) — recommended
 
-Use the hosted endpoint; the client opens WorkOS sign-in and your machine never
-stores a little big brain stack key:
+The client opens WorkOS sign-in; your machine never stores a Little Big Brain key. Point it at your stack:
 
 ```json
 {
@@ -18,7 +16,7 @@ stores a little big brain stack key:
 }
 ```
 
-Codex Desktop should use the origin plus a stack header:
+Codex sends the URL as an OAuth `resource`, so use the origin plus a stack header instead:
 
 ```json
 {
@@ -32,7 +30,9 @@ Codex Desktop should use the origin plus a stack header:
 }
 ```
 
-## Local stdio
+## Local (stdio)
+
+Run against any data-plane endpoint with a stack API key:
 
 ```json
 {
@@ -41,7 +41,7 @@ Codex Desktop should use the origin plus a stack header:
       "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_..."
       }
     }
@@ -49,7 +49,10 @@ Codex Desktop should use the origin plus a stack header:
 }
 ```
 
-Set `LBB_GRAPH` or `LBB_BRANCH` when the scope is not `main`.
+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
 
@@ -67,24 +70,22 @@ Set `LBB_GRAPH` or `LBB_BRANCH` when the scope is not `main`.
 | `lbb_configure` | ontology, schema, and inference rules |
 | `lbb_index` | BM25, vector, and adjacency refresh |
 
-Read tools return compact structured envelopes by default. Use `detail`,
-`row_limit`, and returned cursors to page without silently truncating results.
-Write tools derive idempotency keys unless you provide one.
+Read tools return compact structured envelopes by default — use `detail`, `row_limit`, and returned cursors to page without silently truncating. Write tools derive an idempotency key unless you provide one.
 
 ## Embed the server
 
+For self-hosting behind your own auth, the package also serves the tools over HTTP:
+
 ```ts
 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", "[::1]"],
+  allowedHosts: ["127.0.0.1", "localhost", "::1"],
 }).listen(8080, "127.0.0.1");
 ```
 
-The embedded HTTP server passes a key bearer to the database and is for
-self-hosting behind your own auth. The hosted endpoint's OAuth/ownership layer
-is served by the little big brain API.
+The embedded server passes a key bearer to the data plane; the hosted endpoint's OAuth and ownership layer is served separately by the Little Big Brain API.
 
-Full tool schemas and examples: [MCP documentation](https://docs.littlebigbrain.com/sdks/mcp/).
+Full tool schemas and examples: [docs.littlebigbrain.com/sdks/mcp](https://docs.littlebigbrain.com/sdks/mcp/).

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.3",
+  "version": "0.2.5",
   "description": "MCP server for little big brain — graph and hybrid search tools for agents",
   "license": "Apache-2.0",
   "repository": {
@@ -52,7 +52,7 @@
     "test:coverage": "npm run clean:test && tsc -p tsconfig.test.json && node --test --experimental-test-coverage --test-coverage-include=test-dist/*.js --test-coverage-exclude=test-dist/*.test.js --test-coverage-exclude=test-dist/stdio.js --test-coverage-exclude=test-dist/test-support.js --test-coverage-lines=90 --test-coverage-branches=70 --test-coverage-functions=85 \"test-dist/**/*.test.js\""
   },
   "dependencies": {
-    "@littlebigbrain/client": "^0.4.0",
+    "@littlebigbrain/client": "^0.6.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },