@littlebigbrain/mcp 0.5.1 → 0.6.0

package/README.md

@@ -1,38 +1,52 @@
 # @littlebigbrain/mcp
 
-Eight 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.
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for
+[little big brain](https://littlebigbrain.com), a search platform for AI
+applications such as chatbots, search tools, and agents.
 
-## Hosted (OAuth) — recommended
+Connect an MCP client to search your data, follow relationships, and read the
+facts behind an answer. The tools also let you load data and define validation
+rules.
 
-The client opens WorkOS sign-in; your machine never stores a Little Big Brain key. Point it at your stack:
+[Documentation](https://docs.littlebigbrain.com/sdks/mcp/) ·
+[Quickstart](https://docs.littlebigbrain.com/start/quickstart/) ·
+[Issues](https://github.com/littlebigbrains/lbb-mcp/issues)
 
-```json
-{
-  "mcpServers": {
-    "lbb": {
-      "url": "https://mcp.littlebigbrain.com/mcp/<stack-slug>"
-    }
-  }
-}
+## Connect
+
+Create a stack in the [console](https://cloud.littlebigbrain.com), then choose a
+hosted connection or a local process.
+
+### Hosted connection
+
+For clients that support remote MCP with OAuth, use this URL and sign in with
+your little big brain account. Replace `<stack-slug>` with your stack's slug:
+
+```text
+https://mcp.littlebigbrain.com/mcp/<stack-slug>
 ```
 
-Codex sends the URL as an OAuth `resource`, so use the origin plus a stack header instead:
+For clients that use an `mcpServers` JSON configuration:
 
 ```json
 {
   "mcpServers": {
     "lbb": {
-      "type": "http",
-      "url": "https://mcp.littlebigbrain.com",
-      "headers": { "X-LBB-Stack": "<stack-slug>" }
+      "url": "https://mcp.littlebigbrain.com/mcp/<stack-slug>"
     }
   }
 }
 ```
 
-## Local (stdio)
+This connection uses account sign-in and does not require a stack API key.
+The [connection guide](https://docs.littlebigbrain.com/sdks/mcp/#hosted-streamable-http-oauth)
+includes client-specific setup, including the origin URL and `X-LBB-Stack` header
+for Codex.
+
+### Local process
 
-Run against any data-plane endpoint with a stack API key:
+Requires Node.js 18+. Copy the complete endpoint and a stack API key from
+**Connect** in the console, then add them to your client's MCP configuration:
 
 ```json
 {
@@ -41,147 +55,126 @@ Run against any data-plane endpoint with a stack API key:
       "command": "npx",
       "args": ["-y", "@littlebigbrain/mcp"],
       "env": {
-        "LBB_BASE_URL": "https://0abc1def--production.db.eu.littlebigbrain.com",
-        "LBB_API_KEY": "lbb_sk_live_..."
+        "LBB_BASE_URL": "https://<your-complete-stack-host>",
+        "LBB_API_KEY": "<your-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.
+The client starts the server and communicates through standard input and output
+(stdio). Keep the key in your local configuration. Set `LBB_GRAPH` to change
+the default graph from `main`.
 
-## Tools
+## Run a first query
 
-| Tool | Use it for |
-| --- | --- |
-| `lbb_inspect` | graph discovery, complete paginated ontology/schema, publication status, entity, state, history, and provenance |
-| `lbb_rdf` | import full RDF/OWL or add axioms using INSERT DATA |
-| `lbb_query` | SPARQL text, structured SPARQL bodies, and canned analysis |
-| `lbb_commit` | facts, properties, and embeddings |
-| `lbb_observe` | conversation episodes plus reviewed extraction |
-| `lbb_branch` | isolation branches and validated merge |
-| `lbb_models` | shadow evaluation and training datasets |
-| `lbb_configure` | native ontology definition/evolution and SHACL preview/publication |
-
-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.
-
-Query pages preserve complete RDF values and may contain fewer than `row_limit`
-rows to fit the 80 KB UTF-8 output budget. Follow the returned `next` arguments
-until absent; the cursor advances by rows actually delivered. A single row that
-exceeds the budget fails explicitly: project fewer fields or use the direct
-SPARQL HTTP endpoint for that row.
-
-
-Both `lbb_query` SPARQL modes (`sparql` and `structured`) support retained commit reads
-through `as_of_commit_seq`. When omitted, the connector pins the current head
-commit and reuses it for cursor pages. Valid-time `as_of` is unsupported and is
-rejected before an API call, including when carried in an old cursor. Start a
-new query without that selector or choose a retained commit sequence.
-
-## Create and evolve an ontology through MCP
-
-Start with `lbb_inspect action=guide`; `action=graphs` helps select an existing
-scope, and a missing graph returns bootstrap guidance. Decide what questions
-the graph must answer before choosing classes and relations. Distinguish
-source-backed facts from hypotheses, and preserve evidence and dates.
-
-Native metadata and stored RDF axioms are separate:
-
-- `lbb_configure action=define_ontology` accepts a friendly `spec`, including
-  class `super_types`. Unknown spec fields fail explicitly. `lbb_json` expects
-  an internal serialized ontology, not a friendly spec. Raw OWL supplied to
-  configure is reduced to native metadata; it is not stored as a full document.
-- `lbb_rdf action=import` stores the complete Turtle, N-Triples, N-Quads, or TriG
-  document as queryable graph facts, including RDF lists, annotations, and OWL
-  axioms. Pass `source`; the published RDF tier supports only the default RDF
-  graph. Dataset formats must contain only default-graph quads. The first RDF
-  data write selects RDF-native storage, which refuses
-  later property-graph commits; choose the write workflow before bootstrap.
-- `lbb_configure action=evolve_ontology` supports explicit native changes,
-  including `add_super_types`. `dry_run: true` previews define/evolve/publish;
-  the same flag previews `lbb_commit mode=facts` without writing.
-- `lbb_rdf action=update` submits SPARQL Update unchanged; currently only
-  `INSERT DATA` is supported. DELETE, WHERE, and graph replacement are refused.
-  Re-importing is
-  additive and does not remove obsolete axioms. Content-based retry keys are
-  automatic; use a new explicit key for an intentional repeat after other edits.
-
-For example, add a superclass without a browser or RDF conversion:
+This example stores three facts in a graph named `quickstart`: a service writes
+to a database, and each has a label. The graph is created on its first write.
+
+Ask your client to call `lbb_rdf` with these arguments:
 
 ```json
 {
-  "action": "update",
-  "update": "INSERT DATA { <urn:Person> <http://www.w3.org/2000/01/rdf-schema#subClassOf> <urn:Contact> }"
+  "action": "import",
+  "graph": "quickstart",
+  "format": "ntriples",
+  "source": "<https://example.org/auth-service> <https://example.org/writesTo> <https://example.org/user-db> .\n<https://example.org/auth-service> <http://www.w3.org/2000/01/rdf-schema#label> \"Auth Service\" .\n<https://example.org/user-db> <http://www.w3.org/2000/01/rdf-schema#label> \"User Database\" .",
+  "idempotency_key": "mcp-quickstart-v1"
 }
 ```
 
-Removing or replacing RDF axioms requires native bounded update support in the
-engine. Until then, import a revised document into a new versioned LBB graph,
-verify it, and explicitly switch consumers. Do not implicitly delete the original.
-
-`publish_schema` activates SHACL shapes against unchanged native metadata.
-Its preview checks parsing and compatibility without writing objects or
-scheduling jobs; it does not audit the entire graph. Preview restrictive
-native edits with evolve, resolve conflicts, then apply. For restrictive
-SHACL, use warn → inspect conformance → repair → reject.
-
-After applying, inspect `action=publication`, then verify both asserted axioms
-and expected inferred answers. `lbb_query mode=sparql` accepts explicit
-`entailment: "none" | "subclass" | "rdfs" | "owl"` (default `none`),
-`consistency: "eventual" | "strong"`, and `min_indexed_seq`. Cursors retain
-these controls. OWL is the server's supported inference profile, not arbitrary
-OWL DL. An upload acknowledgement is not proof of successful reasoning.
-
-To read asserted axioms in the default graph, query with `entailment: "none"`
-and follow all returned row cursors:
-
-```sparql
-SELECT ?s ?p ?o WHERE {
-  ?s ?p ?o
-} ORDER BY ?s ?p ?o
+Now ask **which database does Auth Service write to?** The `lbb_query` call is:
+
+```json
+{
+  "mode": "sparql",
+  "graph": "quickstart",
+  "consistency": "strong",
+  "query": "SELECT ?database WHERE { <https://example.org/auth-service> <https://example.org/writesTo> ?db . ?db <http://www.w3.org/2000/01/rdf-schema#label> ?database } ORDER BY ?database LIMIT 10"
+}
 ```
 
-`lbb_inspect action=ontology` and `action=schema` page complete native metadata
-with `page_size` (default 50, maximum 500), optional `section`, and `cursor`.
-Pass the returned `next` arguments until absent. These pages preserve nested
-values even with `detail=compact`; they never replace the remainder with a
-suggestion to repeat `detail=full`. If a single entry is too large, the result
-contains `entry_fragment`: concatenate `serialized_json` by `char_offset`, then
-JSON-parse the completed entry. Changed metadata invalidates the cursor rather
-than mixing versions. Restart inspection after applying edits.
+The result contains one row on a fresh graph:
+
+| database |
+| --- |
+| User Database |
+
+The query follows a stored relationship to its database label. Strong consistency
+lets it read the import without waiting for a background index job.
+
+For your own data, start with `lbb_inspect` using `action: "guide"` or
+`action: "ontology"`. Imported Resource Description Framework (RDF) data keeps
+its original identifiers; inspect it with SPARQL when choosing query predicates.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `lbb_inspect` | Read the schema, graph status, entities, history, and evidence. |
+| `lbb_query` | Run SPARQL queries, search by meaning, or request summary statistics. |
+| `lbb_rdf` | Import RDF documents or add facts with SPARQL `INSERT DATA`. |
+| `lbb_embeddings` | Inspect search setup and preview the text to embed. |
+| `lbb_embeddings_manage` | Set up or refresh embeddings, or change the embedding model. |
+| `lbb_embeddings_delete` | Delete an embedding and its stored vectors. |
+| `lbb_commit` | Write or retract JSON facts, or record search feedback. |
+| `lbb_configure` | Define record types and relationships, or publish validation rules. |
+| `lbb_evals` | Label query results and check whether later queries return the expected answers. |
+| `lbb_models` | Compare retrieval settings and read model training datasets. |
+
+See [search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning/)
+for embedding setup. To define constraints with the Shapes Constraint Language
+(SHACL), see [query and validation](https://docs.littlebigbrain.com/guides/sparql-and-shacl/).
+
+RDF imports and JSON facts use different write workflows. A graph first written
+through `lbb_rdf` does not accept JSON fact writes through `lbb_commit`. Choose
+the workflow when creating the graph. RDF updates
+support additive `INSERT DATA`;
+see the [RDF guide](https://docs.littlebigbrain.com/guides/load-rdf/) for format and
+update limits.
+
+## Pages and saved queries
+
+When a result includes `next`, pass those arguments to the same tool to read the
+next page. Continue until `next` is absent. `row_limit` sets a maximum; large
+values can make a page shorter.
+
+SPARQL queries keep the same commit across pages. Save the query and its returned
+commit sequence to check an answer later, then use `as_of_commit_seq` to select
+that version. See [history and replay](https://docs.littlebigbrain.com/guides/time-travel-audit/)
+for retention and evidence handling.
 
 ## Embed the server
 
-For self-hosting behind your own auth, the package also serves the tools over HTTP:
+To serve the tools from your own Node.js process:
 
 ```ts
 import { createMcpHttpServer } from "@littlebigbrain/mcp";
 
 createMcpHttpServer({
-  baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com",
+  baseUrl: process.env.LBB_BASE_URL!,
   mcpPath: "/mcp",
   allowedHosts: ["127.0.0.1", "localhost", "::1"],
 }).listen(8080, "127.0.0.1");
 ```
 
-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: [docs.littlebigbrain.com/sdks/mcp](https://docs.littlebigbrain.com/sdks/mcp/).
+Clients connect to `http://127.0.0.1:8080/mcp` and send a stack API key in
+`Authorization: Bearer <key>`. See the
+[Node.js integration guide](https://docs.littlebigbrain.com/sdks/mcp/#embed-in-a-node-process)
+for HTTP options and integration with an existing MCP server.
 
-## Local end-to-end ontology check
+## Development
 
-From the repository root, build the server and SDKs, then opt into the isolated
-real-server MCP test (it creates and removes its own temporary data root):
+From a clone of this repository:
 
 ```sh
-cargo build -p lbb-server
-npm run build -w @littlebigbrain/client
-LBB_TEST_SERVER_BIN="$PWD/target/debug/lbb-server" npm test -w @littlebigbrain/mcp
+npm ci
+npm run build
+npm run typecheck
+npm test
 ```
 
-The test verifies native hierarchy evolution, preservation of RDF annotations,
-subclass/inverse inference, additive edits, and refusal of unsupported deletion.
+## License
+
+[Apache-2.0](LICENSE).

package/dist/http-server.d.ts

@@ -22,7 +22,6 @@ export interface McpHttpServerOptions {
         baseUrl: string;
         apiKey: string;
         graph?: string;
-        branch?: string;
     }) => LbbClient;
 }
 export declare function bearer(req: IncomingMessage): string | undefined;

package/dist/http-server.js

@@ -150,7 +150,6 @@ export function createMcpHttpServer(options) {
                 baseUrl,
                 apiKey,
                 graph: url.searchParams.get("graph") ?? undefined,
-                branch: url.searchParams.get("branch") ?? undefined,
             };
             const client = options.clientFactory
                 ? options.clientFactory(clientOptions)

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { registerLbbTools } from "./tools.js";
 export { buildLbbServer } from "./server.js";
+export type { LbbServerOptions, McpQueryStage, McpQueryStageEvent, } from "./query-observer.js";
 export { createMcpHttpServer, type McpHttpServerOptions, } from "./http-server.js";

package/dist/metadata-pages.d.ts

@@ -4,7 +4,6 @@ import { metadataPageSchema } from "./tool-contracts.js";
 type Request = z.infer<z.ZodObject<typeof metadataPageSchema>> & {
     action: "ontology" | "schema";
     graph?: string;
-    branch?: string;
 };
 /** Stateless pagination of complete entries, including their full nested values.
  * A digest rejects mixed-version reads instead of skipping/repeating definitions
@@ -24,7 +23,6 @@ export declare function metadataPage(client: LbbClient, args: Request): Promise<
     next: {
         action: "ontology" | "schema";
         graph: string | undefined;
-        branch: string | undefined;
         section: string | undefined;
         page_size: number;
         cursor: string;

package/dist/metadata-pages.js

@@ -7,7 +7,6 @@ const cursorSchema = z
     v: z.literal(1),
     action: z.enum(["ontology", "schema"]),
     graph: z.string().optional(),
-    branch: z.string().optional(),
     section: z.string().optional(),
     page_size: z.number().int().min(1).max(500),
     offset: z.number().int().nonnegative().safe(),
@@ -27,23 +26,16 @@ export async function metadataPage(client, args) {
         catch {
             throw new Error("invalid lbb_inspect cursor; restart without cursor");
         }
-        for (const key of [
-            "action",
-            "graph",
-            "branch",
-            "section",
-            "page_size",
-        ]) {
+        for (const key of ["action", "graph", "section", "page_size"]) {
             if (args[key] !== undefined && args[key] !== cursor[key]) {
                 throw new Error(`cursor ${key} does not match the supplied ${key}`);
             }
         }
     }
     const graph = cursor?.graph ?? args.graph;
-    const branch = cursor?.branch ?? args.branch;
     const section = cursor?.section ?? args.section;
     const pageSize = cursor?.page_size ?? args.page_size ?? 50;
-    const target = client.withScope({ graph, branch });
+    const target = client.withScope({ graph });
     const value = (args.action === "ontology"
         ? await target.ontologyView({ counts: true })
         : await target.schema.view());
@@ -62,7 +54,6 @@ export async function metadataPage(client, args) {
         v: 1,
         action: args.action,
         graph,
-        branch,
         section,
         page_size: pageSize,
         fingerprint,
@@ -94,7 +85,6 @@ export async function metadataPage(client, args) {
                 ? {
                     action: args.action,
                     graph,
-                    branch,
                     section,
                     page_size: pageSize,
                     cursor: Buffer.from(JSON.stringify({

package/dist/query-observer.d.ts

@@ -0,0 +1,33 @@
+/** Local opt-in query measurements. No event contains query or response data. */
+export type McpQueryStage = "query_pin_metadata" | "query_http_total" | "query_results_parse" | "query_envelope" | "query_render";
+export interface McpQueryStageEvent {
+    stage: McpQueryStage;
+    durationMs: number;
+    outcome: "success" | "error";
+    mode: "sparql" | "structured";
+    continuation: boolean;
+    row_limit: number;
+    offset: number;
+    received_rows?: number;
+    returned_rows?: number;
+    cursor_bytes?: number;
+    text_bytes?: number;
+}
+export interface LbbServerOptions {
+    /** Query text only; fitting and rendering always use this same format. */
+    queryTextFormat?: "compact" | "pretty";
+    timing?: {
+        /** Monotonic milliseconds; defaults to performance.now(). */
+        now?: () => number;
+        observe: (event: Readonly<McpQueryStageEvent>) => void;
+    };
+}
+type QueryCounts = Pick<McpQueryStageEvent, "received_rows" | "returned_rows" | "cursor_bytes" | "text_bytes">;
+type QueryIdentity = Pick<McpQueryStageEvent, "mode" | "continuation" | "row_limit" | "offset">;
+/** Each tool call owns its small counter record; servers may serve concurrently. */
+export declare function queryTiming(options: LbbServerOptions, identity: QueryIdentity): {
+    counts(update: QueryCounts): void;
+    measure<T>(stage: McpQueryStage, operation: () => T): T;
+    measureAsync<T>(stage: McpQueryStage, operation: () => Promise<T>): Promise<T>;
+};
+export {};

package/dist/query-observer.js

@@ -0,0 +1,95 @@
+function count(value) {
+    return Number.isFinite(value)
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+        : 0;
+}
+/** Each tool call owns its small counter record; servers may serve concurrently. */
+export function queryTiming(options, identity) {
+    const timing = options.timing;
+    const counts = {};
+    const now = () => {
+        try {
+            const value = timing?.now?.() ?? performance.now();
+            return Number.isFinite(value) ? value : performance.now();
+        }
+        catch {
+            return performance.now();
+        }
+    };
+    const emit = (stage, start, outcome) => {
+        if (!timing)
+            return;
+        const elapsed = now() - start;
+        const event = {
+            stage,
+            durationMs: Number.isFinite(elapsed)
+                ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, elapsed))
+                : 0,
+            outcome,
+            mode: identity.mode,
+            continuation: identity.continuation,
+            row_limit: count(identity.row_limit),
+            offset: count(identity.offset),
+            ...counts,
+        };
+        try {
+            // Async callbacks also remain isolated even though observation is not
+            // awaited and the public callback contract does not require a Promise.
+            const pending = timing.observe(event);
+            if (pending &&
+                typeof pending.then === "function") {
+                void Promise.resolve(pending).catch(() => { });
+            }
+        }
+        catch {
+            // A local observer cannot turn a successful query into a failure.
+        }
+    };
+    return {
+        counts(update) {
+            if (!timing)
+                return;
+            // Explicit keys prevent caller-supplied objects from adding fields.
+            for (const key of [
+                "received_rows",
+                "returned_rows",
+                "cursor_bytes",
+                "text_bytes",
+            ]) {
+                const value = update[key];
+                if (value !== undefined)
+                    counts[key] = count(value);
+            }
+        },
+        measure(stage, operation) {
+            if (!timing)
+                return operation();
+            const start = now();
+            let outcome = "error";
+            try {
+                const result = operation();
+                outcome = "success";
+                return result;
+            }
+            finally {
+                emit(stage, start, outcome);
+            }
+        },
+        measureAsync(stage, operation) {
+            if (!timing)
+                return operation();
+            const start = now();
+            return (async () => {
+                let outcome = "error";
+                try {
+                    const result = await operation();
+                    outcome = "success";
+                    return result;
+                }
+                finally {
+                    emit(stage, start, outcome);
+                }
+            })();
+        },
+    };
+}

package/dist/rdf-tool.js

@@ -49,13 +49,12 @@ export function registerRdfTool(server, client) {
             return errorResult(parsed.error);
         const args = parsed.data;
         return run(client, `lbb_rdf.${args.action}`, args.detail, async () => {
-            const target = scoped(client, args.graph, args.branch);
+            const target = scoped(client, args.graph);
             const { idempotency_key } = args;
             const operation = { ...args };
             delete operation.detail;
             delete operation.idempotency_key;
-            const key = idempotency_key ??
-                contentHashKey({ graph: args.graph, branch: args.branch }, operation);
+            const key = idempotency_key ?? contentHashKey({ graph: args.graph }, operation);
             if (args.action === "import") {
                 return target.importRdf(args.source, {
                     format: args.format ?? "turtle",

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { LbbClient } from "@littlebigbrain/client";
+import type { LbbServerOptions } from "./query-observer.js";
 /** Build an MCP server exposing the little big brain tool belt, bound to one client. */
-export declare function buildLbbServer(client: LbbClient): McpServer;
+export declare function buildLbbServer(client: LbbClient, options?: LbbServerOptions): McpServer;

package/dist/server.js

@@ -3,8 +3,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerLbbTools } from "./tools.js";
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 /** Build an MCP server exposing the little big brain tool belt, bound to one client. */
-export function buildLbbServer(client) {
+export function buildLbbServer(client, options = {}) {
     const server = new McpServer({ name: "lbb", version });
-    registerLbbTools(server, client);
+    registerLbbTools(server, client, options);
     return server;
 }

package/dist/stdio.js

@@ -12,7 +12,7 @@ const BASE_URL_HELP = "LBB_BASE_URL is required. Copy endpoint_url from your Lit
  *
  *   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)
+ *   LBB_GRAPH     (optional; server defaults to main)
  *
  * The base URL is required lazily, at the first tool invocation, not at
  * process start: MCP hosts launch servers to complete the initialize
@@ -44,7 +44,6 @@ async function main() {
             baseUrl,
             apiKey: process.env.LBB_API_KEY,
             graph: process.env.LBB_GRAPH,
-            branch: process.env.LBB_BRANCH,
         })
         : unconfiguredClient();
     const server = buildLbbServer(client);