@littlebigbrain/mcp 0.5.0 → 0.5.2

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,140 +55,128 @@ 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` or
+`LBB_BRANCH` to change the default scope 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.
-
-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_branch` | Create branches and merge reviewed changes. |
+| `lbb_observe` | Store conversation episodes and reviewed facts extracted from them. |
+| `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`, or branch
+forks and merges. 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/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/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/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/tool-contracts.js

@@ -14,6 +14,12 @@ export const MUTATING = {
     destructiveHint: false,
     openWorldHint: false,
 };
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 export const detailSchema = z
     .enum(["compact", "standard", "full"])
     .optional()
@@ -481,11 +487,71 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             .nonnegative()
             .optional()
             .describe("Snapshot pin: run the query as of this commit_seq. Errors if past head."),
+        request: z
+            .string()
+            .optional()
+            .describe("The user's own words behind this query (managed evals). When present the server records an eval trace and the result carries its trace_id; label the rows valid or not with lbb_evals action=label. Omit on continuation pages."),
         row_limit: rowLimitSchema,
         cursor: cursorSchema,
         ...readScope,
     })
         .strict(),
+    z
+        .object({
+        mode: z.literal("search"),
+        embedding: z
+            .string()
+            .optional()
+            .describe("One embedding by name (see lbb_embeddings action=list). Omit it to search every searchable class of the graph; each hit names its class."),
+        text: z
+            .string()
+            .optional()
+            .describe("The query text (required); embedded with the graph's model."),
+        top_k: z.number().int().positive().max(200).optional(),
+        probe: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Clusters to read (default 4·√clusters, at least 8). More reads cost latency and find more."),
+        include: z
+            .array(z.enum(["text"]))
+            .optional()
+            .describe("text: return the embedded text of each hit."),
+        filter: z
+            .array(z
+            .object({
+            class: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe("A class condition: one class IRI or a list (any of); subclasses too. One class condition per search."),
+            via: z
+                .string()
+                .optional()
+                .describe("A relationship condition: the relationship, a local name (calls), prefix:name, or <iri>."),
+            to: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe("With via: the entity, an IRI or a name (its label; a spelling slip resolves when one entity is clearly closest), or a list (any of)."),
+            direction: z
+                .enum(["out", "in"])
+                .optional()
+                .describe("With via: out (default), the hit links to the entity; in, the entity links to the hit."),
+        })
+            .strict())
+            .optional()
+            .describe('Conditions every hit must meet: {"class": …} or {"via": …, "to": …}. The response\'s filter shows how each condition resolved; an unknown relationship or name answers with the options.'),
+        explain: z
+            .boolean()
+            .optional()
+            .describe("Plan without running: the scope, the resolved filter, and the allowed count. No model call."),
+        request: z
+            .string()
+            .optional()
+            .describe("The user's own words (managed evals): records an eval trace; label it with lbb_evals action=label."),
+        ...readScope,
+    })
+        .strict(),
     z
         .object({
         mode: z.literal("analyze"),

package/dist/tool-runtime.js

@@ -311,104 +311,94 @@ export function envelope(label, value, detailArg, next) {
         next: { ...(next ?? {}), detail: "full" },
     };
 }
-export function queryEnvelope(label, value, detailArg, rowPage, next, repage) {
-    const detail = normalizeDetail(detailArg);
-    const limits = compactLimits(detail);
-    const state = { truncated: false };
-    const returned = rowPage?.returned;
-    const rowCap = rowPage
-        ? Math.max(limits.maxItems, rowPage.returned)
-        : limits.maxItems;
-    let data = truncateValue(value, { ...limits, maxItems: rowCap }, state);
-    const partialRows = rowPage
-        ? rowPage.returned < rowPage.total || rowPage.has_more
-        : false;
-    const rowText = rowPage
-        ? rowPage.returned < rowPage.total
-            ? `returned ${rowPage.returned} of ${rowPage.total} rows`
-            : `returned ${rowPage.returned} rows`
-        : undefined;
-    const serverFlags = serverTruncationFlags(value);
-    const serverTruncated = serverFlags.length > 0;
-    const serverText = serverTruncated
-        ? ` [server-truncated: ${serverFlags.join(", ")}]`
-        : "";
-    let result = {
-        summary: rowText
-            ? `${label}: ${rowText}${serverText}${state.truncated ? " [truncated output]" : ""}`
-            : defaultSummary(label, value, state.truncated),
-        data,
-        counts: countsFor(value),
-        row_page: rowPage,
-        truncated: state.truncated || partialRows || serverTruncated || undefined,
-        next: partialRows && next
-            ? next
-            : state.truncated && nextDetail(detail)
-                ? { detail: nextDetail(detail) }
-                : next,
-    };
-    let text = JSON.stringify(result, null, 2);
-    if (text.length <= HARD_OUTPUT_CHARS)
-        return result;
-    // The full result overflows one MCP tool result, so the displayed rows are
-    // capped to fit. `row_page`/`counts` still describe the *server* page, so
-    // reporting only those reads as "every row delivered" even when the display
-    // was cut — the recurring MCP false-positive. So: state shown-vs-returned
-    // explicitly (`rows_shown`), and give advice that matches reality —
-    //   * server itself withheld rows (partialRows): page with the existing cursor;
-    //   * server returned the complete set but it is too big: page the same set at
-    //     a smaller row_limit via a fresh cursor (offered here as `next`) or narrow
-    //     with HAVING.
-    // "page with the cursor" is never suggested unless a cursor is actually given.
-    const remedy = partialRows
-        ? " page with the cursor for the remaining rows"
-        : repage
-            ? " re-run with the returned cursor to page the full set at a smaller row_limit, or add a HAVING filter to narrow the groups"
-            : " re-run with a lower row_limit to page the full set, or add a HAVING filter to narrow the groups";
-    const capNote = (shown) => returned !== undefined && shown < returned
-        ? ` [MCP showed ${shown} of ${returned} rows — over the ${HARD_OUTPUT_CHARS}-char output budget]`
-        : " [hard-capped for MCP output]";
-    for (const cap of [200, 100, 50, 25, 10, 5, 3]) {
-        const hardState = { truncated: true };
-        data = truncateValue(value, { maxItems: cap, maxString: 160 }, hardState);
-        const shown = returned !== undefined ? Math.min(cap, returned) : cap;
-        const hardNext = partialRows
-            ? next
-            : repage
-                ? continuationNext(repage, shown, Math.max(1, shown))
+export function queryEnvelope(label, value, detailArg, rowPage, next, repage, options = {}) {
+    // A query page is data, not a preview: keep entire terms/values and page
+    // the rows themselves to fit the wire budget. The cursor must advance by
+    // what the caller actually received, even inside a partial server page.
+    const source = value;
+    const results = source?.results;
+    const key = Array.isArray(results?.bindings)
+        ? "bindings"
+        : Array.isArray(source?.groups) && source.groups.length > 0
+            ? "groups"
+            : Array.isArray(source?.solutions)
+                ? "solutions"
                 : undefined;
-        result = {
-            summary: rowText
-                ? `${label}: ${rowText}${serverText}${capNote(shown)} —${remedy}`
-                : `${label}${capNote(shown)} —${remedy}`,
-            data,
-            counts: countsFor(value),
+    const rows = key === "bindings" ? results?.bindings : key ? source[key] : undefined;
+    if (!rowPage || !repage || !Array.isArray(rows)) {
+        return {
+            ...envelope(label, value, detailArg, next),
             row_page: rowPage,
-            rows_shown: returned !== undefined ? shown : undefined,
-            truncated: true,
-            next: hardNext,
+            ...(options.notes?.length ? { notes: options.notes } : {}),
         };
-        text = JSON.stringify(result, null, 2);
-        if (text.length <= HARD_OUTPUT_CHARS)
-            return result;
     }
-    return {
-        summary: rowText
-            ? `${label}: ${rowText}${serverText}${capNote(0)} —${remedy}`
-            : `${label}${capNote(0)} —${remedy}`,
-        data: {
-            note: "The response was too large for the MCP tool result even at the minimum row cap. Page with a smaller row_limit or add a HAVING filter to narrow the groups.",
-            preview: text.slice(0, 20_000),
-        },
-        counts: countsFor(value),
-        row_page: rowPage,
-        rows_shown: returned !== undefined ? 0 : undefined,
-        truncated: true,
-        next: partialRows
-            ? next
-            : repage
-                ? continuationNext(repage, 0, 1)
+    if (rows.length !== rowPage.returned) {
+        throw new Error("Query row count does not match its page; refusing a cursor that could skip rows.");
+    }
+    const flags = serverTruncationFlags(value);
+    const build = (count) => {
+        const hasMore = count < rows.length || rowPage.has_more;
+        const page = {
+            ...rowPage,
+            returned: count,
+            has_more: hasMore,
+            next_offset: hasMore ? rowPage.offset + count : undefined,
+        };
+        const selected = rows.slice(0, count);
+        const data = key === "bindings"
+            ? { ...source, results: { ...results, bindings: selected } }
+            : { ...source, [key]: selected, row_page: page };
+        return {
+            summary: `${label}: returned ${count}${count < page.total ? ` of ${page.total}` : ""} rows${flags.length ? ` [server-truncated: ${flags.join(", ")}]` : ""}${count < rows.length ? " [byte-bounded page; continue with the cursor]" : ""}`,
+            data,
+            counts: countsFor(data),
+            row_page: page,
+            rows_shown: count < rows.length ? count : undefined,
+            truncated: hasMore || flags.length > 0 || undefined,
+            next: hasMore
+                ? continuationNext(repage, page.offset + count, repage.row_limit)
                 : undefined,
+            ...(options.notes?.length ? { notes: options.notes } : {}),
+        };
+    };
+    // Retain the existing reserve, but include actual normalization notes in
+    // every fit so even a large note list cannot push the final text over cap.
+    // Count UTF-8 bytes, including multibyte literals, not JavaScript code units.
+    const fits = (page) => Buffer.byteLength(serializeQueryEnvelope(page, options.textFormat), "utf8") <=
+        HARD_OUTPUT_CHARS - 2048;
+    const full = build(rows.length);
+    if (fits(full))
+        return full;
+    let lo = 0;
+    let hi = rows.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (fits(build(mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    if (lo === 0) {
+        throw new Error(rows.length === 0
+            ? "Query page metadata or normalization notes exceed the MCP output budget. Narrow the query or use the SPARQL HTTP API; no rows were skipped."
+            : "One query row exceeds the MCP output budget. Project fewer fields or use the SPARQL HTTP API for this value; no rows were skipped.");
+    }
+    return build(lo);
+}
+/** One formatter for query page fitting and the text returned to MCP clients. */
+export function serializeQueryEnvelope(value, format = "compact") {
+    return format === "pretty"
+        ? JSON.stringify(value, null, 2)
+        : JSON.stringify(value);
+}
+export function queryToolResult(value, format) {
+    const text = serializeQueryEnvelope(value, format);
+    if (Buffer.byteLength(text, "utf8") > HARD_OUTPUT_CHARS) {
+        throw new Error("Query response exceeds the MCP output budget. Narrow the query or use the SPARQL HTTP API; no rows were skipped.");
+    }
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: value,
     };
 }
 export function toolResult(value) {
@@ -695,6 +685,7 @@ export async function guide(scopedClient) {
             search_feedback: "When a result set is useful or clearly wrong, write relevance labels with lbb_commit mode=search_feedback. Use grade 3 for ideal/good results, grade 1 for partially relevant results, and grade 0 for bad results. Include the original query, search_id when present, target identity, rank, score, and an optional split train/eval/unspecified. These labels are stored in __lbb_feedback/main and later exported as qrels-style training/eval data; they are not customer facts.",
             inspect: "Use lbb_inspect for ontology, schema metadata, the published conformance report, metadata, state/history/why, and this guide. Use lbb_query with SPARQL property paths for exact path queries.",
             ontology_decorations: "lbb_inspect action=ontology returns a decoration_status catalog: each ontology decoration is enforced (the engine acts on it — state_reducer, value_type, super_types, properties, supernode_policy; cardinality, which GET /v1/ontology/conformance audits as sh:maxCount; and inverse_name/symmetric, which SPARQL resolves as relation aliases — an inverse name is queryable directly (lowered to ^forward, no stored inverse triple) and a symmetric relation matches both directions), advisory (transitive, temporal_semantics, required), or reserved (stored but unwired — default_weight, resolvable, alias/embedding_fields). You can also always reverse any relation in SPARQL by flipping the triple pattern or using ^forward. Each relation_def also carries edge_count — the number of current edges of that relation in this branch's snapshot — so you can tell at a glance which declared relations are actually populated (edge_count 0 = declared but unused) without a separate summary call.",
+            search: "Use lbb_query mode=search to find instances by meaning. It covers every searchable class; filter narrows it by class and by relationship, and the graph checks every hit. To plan a search: (1) lbb_embeddings action=list gives the searchable classes, the facts each text is made from, and the graph's model. (2) lbb_query mode=sparql shows the relationships of a class on a sample: PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?p (COUNT(DISTINCT ?s) AS ?n) (SAMPLE(?l) AS ?example) WHERE { { SELECT ?s WHERE { ?s a <CLASS> } LIMIT 500 } ?s ?p ?o . FILTER(isIRI(?o) && ?p != rdf:type) OPTIONAL { ?o rdfs:label ?l } } GROUP BY ?p ORDER BY DESC(?n); write ?o ?p ?s for the links into the class, and SELECT ?c WHERE { ?c rdfs:subClassOf* <CLASS> } (same prefixes) for its subclasses. (3) lbb_query mode=search with filter [{class}, {via, to}] and explain=true returns the plan: the resolved relationship and entities, the allowed count, and the mode, with no model call. Check it, then run the search without explain. A name in to resolves against labels (a small typo too); an unknown relationship or name answers with the options.",
             query: "Use lbb_query for structured SPARQL-subset bodies, SPARQL text, and canned analysis. SPARQL is the only query surface. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
             write: "Use lbb_commit for fact writes and relevance feedback; omitted idempotency keys are content-derived so retries dedupe. Set typed scalar attributes via entity_properties once the field is registered (add it on a live graph with lbb_configure evolve_ontology add_property). For feedback, use mode=search_feedback rather than fact triplets.",
             configure: "Use lbb_configure dry_run=true to preview definitions, ordered evolution (including add_super_types), or SHACL publication. Definition extracts native metadata; use lbb_rdf import to store full RDF/OWL and lbb_rdf update for additive INSERT DATA; RDF deletion/replacement is unsupported. Follow every lbb_inspect ontology/schema next cursor; fields are complete and metadata changes invalidate the cursor. Publication is asynchronous: inspect action=publication, then verify asserted axioms AND expected answers with lbb_query entailment=owl. SHACL conformance alone does not prove ontology completeness. First identify the questions the model must answer, reusable vocabularies, dates, evidence, and distinctions such as hypothesis versus confirmed fact.",

package/dist/tools.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { LbbClient } from "@littlebigbrain/client";
-export declare function registerLbbTools(server: McpServer, client: LbbClient): void;
+import { type LbbServerOptions } from "./query-observer.js";
+export declare function registerLbbTools(server: McpServer, client: LbbClient, options?: LbbServerOptions): void;

package/dist/tools.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { metadataPage } from "./metadata-pages.js";
 import { registerRdfTool } from "./rdf-tool.js";
-import { IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, } from "./tool-contracts.js";
-import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, requireString, rowPageFrom, rowPageNext, run, scoped, stableJson, toolResult, } from "./tool-runtime.js";
-export function registerLbbTools(server, client) {
+import { queryTiming } from "./query-observer.js";
+import { DESTRUCTIVE, IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, } from "./tool-contracts.js";
+import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, queryToolResult, requireString, rowPageFrom, rowPageNext, run, scoped, stableJson, toolResult, } from "./tool-runtime.js";
+export function registerLbbTools(server, client, options = {}) {
     registerRdfTool(server, client);
     server.registerTool("lbb_inspect", {
         description: "Read graph context and exact graph facts. Actions: guide, graphs, publication, ontology, ontology_conformance, schema, ontology_search, metadata, entity, state, history, transitions, why. graphs works before bootstrap; publication reports whether writes are queryable. ontology and schema return complete entries with page_size, section and cursor; follow next until absent. schema reads active native ontology/SHACL metadata without running validation. Query asserted RDF/OWL axioms separately with lbb_query. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's metadata, scalar attributes, bounded Base-backed edge neighborhood, history, and observations. Use lbb_query with SPARQL property paths for precise path selection.",
@@ -94,7 +95,7 @@ export function registerLbbTools(server, client) {
         });
     });
     server.registerTool("lbb_query", {
-        description: "Analytical and expert reads. Modes: structured (SPARQL-subset JSON body), sparql (SPARQL text), analyze. SPARQL is the only query surface. Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
+        description: "Analytical and expert reads. Modes: structured (SPARQL-subset JSON body), sparql (SPARQL text), search (instances by meaning over every searchable class; filter narrows by class and relationship; every hit checked against the graph), analyze. SPARQL is the query language; search finds what the words describe. To plan a search: lbb_embeddings action=list, then SPARQL for a class's relationships on a sample, then mode=search with explain=true to check the resolved filter before the real search (lbb_inspect action=guide has the queries). Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
         inputSchema: queryWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -121,6 +122,37 @@ export function registerLbbTools(server, client) {
                     const branch = cursor?.branch ?? args.branch;
                     const offset = cursor?.offset ?? 0;
                     const target = scoped(client, graph, branch);
+                    const timing = queryTiming(options, {
+                        mode: args.mode,
+                        continuation: cursor !== undefined,
+                        row_limit: rowLimit,
+                        offset,
+                    });
+                    const pin = (requested) => !cursor && requested === undefined
+                        ? timing.measureAsync("query_pin_metadata", () => queryCommitPin(target, requested, cursor))
+                        : queryCommitPin(target, requested, cursor);
+                    const buildEnvelope = (value, rowPage, next, cursorBase, notes) => timing.measure("query_envelope", () => {
+                        timing.counts({ received_rows: rowPage?.returned });
+                        const result = queryEnvelope(`lbb_query.${args.mode}`, value, detail, rowPage, next, cursorBase, { textFormat: options.queryTextFormat, notes });
+                        if (options.timing) {
+                            const nextCursor = result.next?.cursor;
+                            timing.counts({
+                                returned_rows: rowPageFrom(result)?.returned,
+                                cursor_bytes: typeof nextCursor === "string"
+                                    ? Buffer.byteLength(nextCursor, "utf8")
+                                    : 0,
+                            });
+                        }
+                        return result;
+                    });
+                    const render = (value) => timing.measure("query_render", () => {
+                        const result = queryToolResult(value, options.queryTextFormat);
+                        if (options.timing)
+                            timing.counts({
+                                text_bytes: Buffer.byteLength(result.content[0].text, "utf8"),
+                            });
+                        return result;
+                    });
                     for (const key of [
                         "entailment",
                         "consistency",
@@ -174,7 +206,7 @@ export function registerLbbTools(server, client) {
                             args.as_of_commit_seq !== cursor.as_of_commit_seq) {
                             throw new Error("cursor as_of_commit_seq does not match the supplied as_of_commit_seq argument");
                         }
-                        const asOfCommitSeq = await queryCommitPin(target, requestedCommitSeq, cursor);
+                        const asOfCommitSeq = await pin(requestedCommitSeq);
                         const request = {
                             ...body,
                             limit: rowLimit,
@@ -189,10 +221,10 @@ export function registerLbbTools(server, client) {
                             request.combinators.length > 0) {
                             throw new Error("`combinators` (UNION/OPTIONAL/MINUS/EXISTS) is no longer accepted by structured mode; the analytics route was removed. Express the same query as SPARQL text with mode=sparql.");
                         }
-                        const response = await target.sparql(request, {
+                        const response = await timing.measureAsync("query_http_total", () => target.sparql(request, {
                             consistency,
                             minIndexedSeq,
-                        });
+                        }));
                         const rowPage = rowPageFrom(response);
                         const cursorBase = {
                             v: 1,
@@ -207,7 +239,7 @@ export function registerLbbTools(server, client) {
                             as_of_commit_seq: asOfCommitSeq,
                         };
                         const next = rowPageNext(cursorBase, rowPage);
-                        return toolResult(queryEnvelope(`lbb_query.${args.mode}`, response, detail, rowPage, next, cursorBase));
+                        return render(buildEnvelope(response, rowPage, next, cursorBase));
                     }
                     // Canonicalize little big brain relation/class/property IRI local-name case up
                     // front, then use the normalized text everywhere (mismatch check,
@@ -229,16 +261,24 @@ export function registerLbbTools(server, client) {
                         args.as_of_commit_seq !== cursor.as_of_commit_seq) {
                         throw new Error("cursor as_of_commit_seq does not match the supplied as_of_commit_seq argument");
                     }
-                    const asOfCommitSeq = await queryCommitPin(target, args.as_of_commit_seq, cursor);
+                    const asOfCommitSeq = await pin(args.as_of_commit_seq);
                     const entailment = cursor?.entailment ?? args.entailment ?? "none";
-                    const response = await target.sparqlText({
+                    const response = await timing.measureAsync("query_http_total", () => target.sparqlText({
                         query,
                         entailment,
                         as_of_commit_seq: asOfCommitSeq ?? null,
                         limit: rowLimit,
                         offset,
-                    }, { consistency, minIndexedSeq });
-                    const data = JSON.parse(response.results);
+                        // Managed evals: the first page records a trace; a
+                        // continuation page re-reads the same rows and must not.
+                        ...(cursor === undefined && args.request
+                            ? { request: args.request }
+                            : {}),
+                    }, { consistency, minIndexedSeq }));
+                    if (response.trace_id) {
+                        notes.push(`eval trace ${response.trace_id}: to label rows, read their item ids with lbb_evals action=trace trace_id=${response.trace_id}, then call lbb_evals action=label trace_id=${response.trace_id} item=<id> valid=true|false (or items=[…]).`);
+                    }
+                    const data = timing.measure("query_results_parse", () => JSON.parse(response.results));
                     const rowPage = rowPageFrom(response);
                     const cursorBase = {
                         v: 1,
@@ -254,14 +294,30 @@ export function registerLbbTools(server, client) {
                         as_of_commit_seq: asOfCommitSeq,
                     };
                     const next = rowPageNext(cursorBase, rowPage);
-                    const sparqlEnvelope = queryEnvelope(`lbb_query.${args.mode}`, data, detail, rowPage, next, cursorBase);
-                    return toolResult(notes.length > 0 ? { ...sparqlEnvelope, notes } : sparqlEnvelope);
+                    const sparqlEnvelope = buildEnvelope(data, rowPage, next, cursorBase, notes);
+                    return render(sparqlEnvelope);
                 }
                 catch (error) {
                     return errorResult(await enrichError(client, error));
                 }
             })();
         }
+        if (args.mode === "search") {
+            const searchArgs = args;
+            return run(client, "lbb_query.search", undefined, async () => {
+                const target = scoped(client, searchArgs.graph, searchArgs.branch);
+                return target.embeddings.search({
+                    embedding: searchArgs.embedding,
+                    text: searchArgs.text,
+                    top_k: searchArgs.top_k,
+                    probe: searchArgs.probe,
+                    include: searchArgs.include,
+                    request: searchArgs.request,
+                    filter: searchArgs.filter,
+                    explain: searchArgs.explain,
+                });
+            });
+        }
         return run(client, `lbb_query.${args.mode}`, args.detail, async () => {
             const target = scoped(client, args.graph, args.branch);
             return analyze(target, {
@@ -311,6 +367,257 @@ export function registerLbbTools(server, client) {
                 return target.extractorDataset({ limit, splitSeq: split_seq });
         }
     }));
+    const embeddingSetup = {
+        class: z.string().optional().describe("preview/declare: the class IRI."),
+        from: z
+            .array(z.string())
+            .optional()
+            .describe('preview/declare: the fields, e.g. ["label", "description", "calls/label"]. Omit for the automatic choice; on an existing embedding, omit to keep its fields.'),
+        exclude: z
+            .array(z.string())
+            .optional()
+            .describe("preview/declare: fields to drop from the automatic choice."),
+        title: z
+            .string()
+            .optional()
+            .describe('preview/declare: the field that names each hit, e.g. "display_name". Omit for the ontology\'s name property (skos:prefLabel, a property declared rdfs:subPropertyOf rdfs:label, else rdfs:label); on an existing embedding, omit to keep its name. preview reports title_source and, when the labels read as keys, title_suggestion.'),
+        model: z
+            .string()
+            .optional()
+            .describe("model: the graph's new model. preview/declare: omit it; a graph has one model (the graph's, or the platform's default for the first embedding)."),
+        dim: z.number().int().positive().optional(),
+    };
+    const recipeOf = (args) => {
+        if (!args.class)
+            throw new Error("this action requires class");
+        return {
+            class: args.class,
+            ...(args.name ? { name: args.name } : {}),
+            ...(args.from ? { from: args.from } : {}),
+            ...(args.exclude ? { exclude: args.exclude } : {}),
+            ...(args.title ? { title: args.title } : {}),
+            ...(args.model ? { model: args.model } : {}),
+            ...(args.dim ? { dim: args.dim } : {}),
+        };
+    };
+    server.registerTool("lbb_embeddings", {
+        description: "Search setup, read only: embeddings declared on classes (an embedding on a class covers its subclasses; one model per graph). list shows each embedding's status (serving and building version, backfill progress, lag) and the graph's model; get shows one; preview shows every candidate fact of a class with its coverage and examples, and the exact text of sample instances, and stores nothing. Declare, refresh, or change the model with lbb_embeddings_manage; search with lbb_query mode=search. list is the first step of planning a search (lbb_inspect action=guide has the recipe).",
+        inputSchema: {
+            action: z.enum(["list", "get", "preview"]),
+            name: z.string().optional().describe("get: the embedding name."),
+            ...embeddingSetup,
+            sample: z.number().int().positive().max(50).optional(),
+            iris: z
+                .array(z.string())
+                .optional()
+                .describe("preview: the instances to show instead of a sample."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, (args) => run(client, `lbb_embeddings.${args.action}`, args.detail, () => {
+        const target = scoped(client, args.graph, args.branch);
+        switch (args.action) {
+            case "list":
+                return target.embeddings.list();
+            case "get":
+                if (!args.name)
+                    throw new Error("get requires name");
+                return target.embeddings.get(args.name);
+            case "preview":
+                return target.embeddings.preview({
+                    ...recipeOf(args),
+                    ...(args.sample ? { sample: args.sample } : {}),
+                    ...(args.iris ? { iris: args.iris } : {}),
+                });
+        }
+    }));
+    server.registerTool("lbb_embeddings_manage", {
+        description: "Declare or refresh an embedding, or change the graph's model. Run lbb_embeddings action=preview first and show the user the text it will embed. declare sets the class, the fields (one-hop property paths such as label, description, calls/label; omit for an automatic choice); a new embedding takes the graph's model, and another model is refused. On an existing embedding it changes only what you name, and a changed recipe builds a new version while the old one serves. model moves every embedding of the graph to `model`: each builds a new version, and the graph switches when all are ready (a search never mixes two models). refresh runs one step of the embed job now (it also runs by itself after each published commit).",
+        inputSchema: {
+            action: z.enum(["declare", "refresh", "model"]),
+            name: z
+                .string()
+                .optional()
+                .describe("The embedding name (refresh: required)."),
+            ...embeddingSetup,
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_embeddings_manage.${args.action}`, args.detail, () => {
+        const target = scoped(client, args.graph, args.branch);
+        switch (args.action) {
+            case "declare":
+                return target.embeddings.declare(recipeOf(args));
+            case "refresh":
+                if (!args.name)
+                    throw new Error("refresh requires name");
+                return target.embeddings.refresh(args.name);
+            case "model":
+                if (!args.model)
+                    throw new Error("model requires model");
+                return target.embeddings.setModel({
+                    model: args.model,
+                    ...(args.dim ? { dim: args.dim } : {}),
+                });
+        }
+    }));
+    server.registerTool("lbb_embeddings_delete", {
+        description: "Delete an embedding: its name and its vectors (index-gc removes the stored runs). Its class stops being searchable until it is declared and built again. Ask the user first; confirm must repeat the name.",
+        inputSchema: {
+            name: z.string().describe("The embedding name."),
+            confirm: z.string().describe("The same name again, to confirm."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: DESTRUCTIVE,
+    }, ({ name, confirm, detail, graph, branch }) => run(client, "lbb_embeddings_delete", detail, () => {
+        if (confirm !== name) {
+            throw new Error("confirm must repeat the embedding name");
+        }
+        return scoped(client, graph, branch).embeddings.delete(name);
+    }));
+    server.registerTool("lbb_evals", {
+        description: "Managed evals: the thumbs up / thumbs down of the graph, per result. A query run with `request` (lbb_query) records a trace with one item per result (hit or row); trace reads it back with the item ids. label marks one result (item + valid) or several (items) relevant or not; the labels become the golden's ground truth. golden freezes a query (every result it returns now is relevant). run replays every golden at the current commit: pass when every relevant result is back and no wrong one is; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state.",
+        inputSchema: {
+            action: z.enum([
+                "summary",
+                "traces",
+                "trace",
+                "label",
+                "judge",
+                "goldens",
+                "golden",
+                "accept",
+                "delete",
+                "run",
+                "results",
+                "settings",
+            ]),
+            trace_id: z
+                .string()
+                .optional()
+                .describe("trace / label / judge: the trace id from lbb_query."),
+            item: z
+                .string()
+                .optional()
+                .describe("label: the result id (a hit's `id`, or an item id from trace) to label with `valid`."),
+            valid: z
+                .boolean()
+                .optional()
+                .describe("label: true = the result answers the request (thumbs up), false = it does not."),
+            items: z
+                .array(z
+                .object({
+                id: z.string(),
+                valid: z.boolean(),
+                note: z.string().optional(),
+            })
+                .strict())
+                .optional()
+                .describe("label: several results at once."),
+            by: z
+                .string()
+                .optional()
+                .describe("label: who labels (an agent name)."),
+            note: z.string().optional(),
+            sparql: z
+                .string()
+                .optional()
+                .describe("golden: the query to freeze (the search text for surface=search)."),
+            surface: z
+                .enum(["sparql", "search"])
+                .optional()
+                .describe("golden: which surface the query runs on (default sparql)."),
+            embedding: z
+                .string()
+                .optional()
+                .describe("golden: the embedding, for surface=search."),
+            top_k: z
+                .number()
+                .int()
+                .positive()
+                .max(200)
+                .optional()
+                .describe("golden: the top_k of a search golden."),
+            request: z
+                .string()
+                .optional()
+                .describe("golden: the user's words the query answers."),
+            golden_id: z
+                .string()
+                .optional()
+                .describe("accept / delete: the golden id."),
+            limit: z.number().int().positive().optional(),
+            unlabeled: z
+                .boolean()
+                .optional()
+                .describe("traces: only traces without a label."),
+            consistency: z
+                .enum(["strong", "eventual"])
+                .optional()
+                .describe("run / accept: strong reads the head, eventual the last published commit."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, ({ action, trace_id, item, valid, items, by, note, sparql, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, detail, graph, branch, }) => run(client, `lbb_evals.${action}`, detail, () => {
+        const target = scoped(client, graph, branch);
+        switch (action) {
+            case "summary":
+                return target.evals.summary();
+            case "traces":
+                return target.evals.traces({ limit, unlabeled });
+            case "trace":
+                if (!trace_id)
+                    throw new Error("trace requires trace_id");
+                return target.evals.trace(trace_id);
+            case "label":
+                if (!trace_id)
+                    throw new Error("label requires trace_id");
+                if (!item && !items?.length)
+                    throw new Error("label requires item (with valid) or items");
+                if (item && valid === undefined)
+                    throw new Error("label requires valid with item");
+                return target.evals.label(trace_id, {
+                    ...(item ? { item, valid } : {}),
+                    ...(items?.length ? { items } : {}),
+                    by,
+                    note,
+                });
+            case "judge":
+                return target.evals.judge({ traceId: trace_id, limit });
+            case "goldens":
+                return target.evals.goldens();
+            case "golden":
+                if (!sparql)
+                    throw new Error("golden requires sparql");
+                if (surface === "search" && !embedding)
+                    throw new Error("a search golden requires embedding");
+                return target.evals.createGolden({
+                    sparql,
+                    request,
+                    ...(surface ? { surface } : {}),
+                    ...(embedding ? { embedding } : {}),
+                    ...(top_k ? { top_k } : {}),
+                });
+            case "accept":
+                if (!golden_id)
+                    throw new Error("accept requires golden_id");
+                return target.evals.acceptGolden(golden_id, { consistency });
+            case "delete":
+                if (!golden_id)
+                    throw new Error("delete requires golden_id");
+                return target.evals.deleteGolden(golden_id);
+            case "run":
+                return target.evals.run({ consistency });
+            case "results":
+                return target.evals.results({ limit });
+            case "settings":
+                return target.evals.settings();
+        }
+    }));
     server.registerTool("lbb_commit", {
         description: "Write graph facts, retract them, or label ranked results. mode=facts writes triplets/embeddings/properties; mode=retract removes a wrongly-added fact (by edge or by entity) without a full reset; mode=search_feedback stores query/result relevance labels (Feedback grades: 3=ideal/good, 1=partial, 0=bad; include query, search_id when available, target, rank, score). Explicit idempotency_key wins; when omitted, MCP derives a stable content hash so content-identical retries dedupe. Facts mode defaults edge_idempotency to append; pass skip_unchanged for re-runnable backfills.",
         inputSchema: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.5.0",
-  "description": "MCP server for little big brain — graph and hybrid search tools for agents",
+  "version": "0.5.2",
+  "description": "MCP server for little big brain: search, graph queries, and data import",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -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.13.1",
+    "@littlebigbrain/client": "^0.13.2",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },