@littlebigbrain/mcp 0.5.1 → 0.6.0

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()
@@ -34,10 +40,6 @@ export const graphScope = {
         .string()
         .optional()
         .describe("Graph to target; defaults to the connection's graph"),
-    branch: z
-        .string()
-        .optional()
-        .describe("Branch to target; defaults to the connection's branch"),
 };
 export const jsonObjectSchema = z.record(z.string(), z.unknown());
 export const jsonObjectArraySchema = z.array(jsonObjectSchema);
@@ -481,11 +483,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"),
@@ -510,7 +572,6 @@ export const configureInputSchema = z.discriminatedUnion("action", [
             .optional()
             .describe("Preview the exact definition without creating a graph or writing metadata."),
         graph: z.string().describe("Graph to create or redefine"),
-        branch: graphScope.branch,
         entity_types: z.array(z.union([z.string(), jsonObjectSchema])).optional(),
         relations: z.array(z.union([z.string(), jsonObjectSchema])).optional(),
         source: z.string().optional(),
@@ -561,7 +622,7 @@ export const configureInputSchema = z.discriminatedUnion("action", [
  * rejects as `Expected object, received string`.
  *
  * Flatten the union into a single ZodObject purely for advertisement and
- * transport: the discriminant becomes an enum, every branch field is merged in
+ * transport: the discriminant becomes an enum, every variant field is merged in
  * as optional, and unknown keys pass through. Each handler still `safeParse`s the
  * raw args against the original strict union before dispatching, so per-variant
  * required/forbidden fields are enforced exactly as before.

package/dist/tool-runtime.js

@@ -2,9 +2,7 @@ import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
 import { LbbError } from "@littlebigbrain/client";
 import { DEFAULT_DETAIL, HARD_OUTPUT_CHARS, MAX_QUERY_ROW_LIMIT, } from "./tool-contracts.js";
-export const scoped = (client, graph, branch) => graph !== undefined || branch !== undefined
-    ? client.withScope({ graph, branch })
-    : client;
+export const scoped = (client, graph) => graph !== undefined ? client.withScope({ graph }) : client;
 export function normalizeDetail(detail) {
     return detail === "standard" || detail === "full" ? detail : DEFAULT_DETAIL;
 }
@@ -50,9 +48,6 @@ export function assertCursorScope(args, cursor) {
     if (args.graph !== undefined && args.graph !== cursor.graph) {
         throw new Error("cursor graph does not match the supplied graph argument");
     }
-    if (args.branch !== undefined && args.branch !== cursor.branch) {
-        throw new Error("cursor branch does not match the supplied branch argument");
-    }
 }
 export function rowPageFrom(value) {
     if (!value || typeof value !== "object")
@@ -190,7 +185,7 @@ export function normalizeLbbIris(query) {
 export function contentHashKey(scope, payload) {
     const digest = createHash("sha256")
         .update(stableJson({
-        scope: { graph: scope.graph ?? null, branch: scope.branch ?? null },
+        scope: { graph: scope.graph ?? null },
         payload,
     }))
         .digest("hex");
@@ -311,7 +306,7 @@ export function envelope(label, value, detailArg, next) {
         next: { ...(next ?? {}), detail: "full" },
     };
 }
-export function queryEnvelope(label, value, detailArg, rowPage, next, repage) {
+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.
@@ -326,7 +321,11 @@ export function queryEnvelope(label, value, detailArg, rowPage, next, repage) {
                 : undefined;
     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 };
+        return {
+            ...envelope(label, value, detailArg, next),
+            row_page: rowPage,
+            ...(options.notes?.length ? { notes: options.notes } : {}),
+        };
     }
     if (rows.length !== rowPage.returned) {
         throw new Error("Query row count does not match its page; refusing a cursor that could skip rows.");
@@ -354,11 +353,13 @@ export function queryEnvelope(label, value, detailArg, rowPage, next, repage) {
             next: hasMore
                 ? continuationNext(repage, page.offset + count, repage.row_limit)
                 : undefined,
+            ...(options.notes?.length ? { notes: options.notes } : {}),
         };
     };
-    // Leave room for tool-level normalization notes added by the caller. Count
-    // UTF-8 bytes, including multibyte literals, not JavaScript code units.
-    const fits = (page) => Buffer.byteLength(JSON.stringify(page, null, 2), "utf8") <=
+    // 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))
@@ -373,10 +374,28 @@ export function queryEnvelope(label, value, detailArg, rowPage, next, repage) {
             hi = mid - 1;
     }
     if (lo === 0) {
-        throw new Error("One query row exceeds the MCP output budget. Project fewer fields or use the SPARQL HTTP API for this value; no rows were skipped.");
+        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) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -416,60 +435,38 @@ export function errorResult(error) {
     };
 }
 /**
- * A graph-scope 404 surfaces as a raw object-storage key
- * (`not found: tenants/<t>/graphs/<g>/branches/<b>/heads/current.json`), which
- * only means something if you already know the graph's real name. Rewrite it
- * into an actionable message: name the graph/branch this request targeted, and —
- * via the tenant-scoped `GET /v1/graphs`, which resolves even when the scoped
- * graph is absent — list the graphs (or branches) that do exist and tell the
- * caller to pass `graph=`/`branch=`. Every other error passes through untouched.
+ * A graph-scope 404 surfaces as a raw object-storage key ending in
+ * `heads/current.json`, which only means something if you already know the
+ * graph's real name. Rewrite it into an actionable message: name the graph this
+ * request targeted and — via the tenant-scoped `GET /v1/graphs`, which resolves
+ * even when the scoped graph is absent — list the graphs that do exist and tell
+ * the caller to pass `graph=`. Every other error passes through untouched,
+ * including a head 404 on a graph the listing still reports.
  */
 export async function enrichError(client, error) {
     if (!(error instanceof LbbError) || error.status !== 404)
         return error;
-    const match = /graphs\/([^/]+)\/branches\/([^/]+)\/heads\/current\.json/.exec(error.message);
+    const match = /graphs\/([^/\s]+)\/(?:[^/\s]+\/)*heads\/current\.json/.exec(error.message);
     if (!match)
         return error;
-    const [, graph, branch] = match;
-    let graphs = [];
+    const [, graph] = match;
+    let names = [];
     try {
         const listed = (await client.listGraphs());
-        graphs = (listed.data ?? []).flatMap((g) => typeof g.graph_id === "string"
-            ? [
-                {
-                    graph_id: g.graph_id,
-                    branches: Array.isArray(g.branches)
-                        ? g.branches
-                        : undefined,
-                },
-            ]
-            : []);
+        names = (listed.data ?? []).flatMap((g) => typeof g.graph_id === "string" ? [g.graph_id] : []);
     }
     catch {
         // Listing failed too (auth, transport); fall back to the generic-but-actionable hint.
     }
-    const existing = graphs.find((g) => g.graph_id === graph);
-    let message;
-    if (existing) {
-        const branches = existing.branches ?? [];
-        const list = branches.length > 0
-            ? ` Existing branches: ${branches.slice(0, 50).join(", ")}.`
-            : "";
-        message =
-            `branch "${branch}" was not found on graph "${graph}" in this tenant.${list} ` +
-                "Pass an existing branch as the `branch` argument.";
-    }
-    else {
-        const names = graphs.map((g) => g.graph_id);
-        const list = names.length > 0
-            ? ` Available graphs in this tenant: ${names.slice(0, 50).join(", ")}.`
-            : "";
-        const example = names.length > 0 ? ` (e.g. graph="${names[0]}")` : "";
-        message =
-            `graph "${graph}" was not found in this tenant — this request targeted graph "${graph}", branch "${branch}" ` +
-                `(either you passed it or it is the connection default).${list} ` +
-                `Pass an existing graph as the \`graph\` argument${example}.`;
-    }
+    if (names.includes(graph))
+        return error;
+    const list = names.length > 0
+        ? ` Available graphs in this tenant: ${names.slice(0, 50).join(", ")}.`
+        : "";
+    const example = names.length > 0 ? ` (e.g. graph="${names[0]}")` : "";
+    const message = `graph "${graph}" was not found in this tenant — this request targeted graph "${graph}" ` +
+        `(either you passed it or it is the connection default).${list} ` +
+        `Pass an existing graph as the \`graph\` argument${example}.`;
     return new LbbError(error.status, error.body, {
         type: error.type,
         code: error.code,
@@ -660,7 +657,8 @@ export async function guide(scopedClient) {
         capability: {
             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.",
+            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 graph'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;