@littlebigbrain/mcp 0.3.0 → 0.4.1

package/README.md

@@ -58,11 +58,8 @@ missing.
 
 | Tool | Use it for |
 | --- | --- |
-| `lbb_search` | hybrid retrieval, multi-query fusion, and semantic graph results |
-| `lbb_decode` | constrained relation decoding |
-| `lbb_ground` | vocabulary completion and resolution |
 | `lbb_inspect` | ontology, schema, entity, state, history, and provenance |
-| `lbb_query` | SPARQL and structured analytics |
+| `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 |

package/dist/tool-contracts.js

@@ -382,7 +382,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         mode: z.literal("structured"),
         body: jsonObjectSchema
             .optional()
-            .describe('Structured SPARQL-subset or analytics request body. Shape: { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having?, order_by?, select?, limit?, distinct? }. Each pattern term is { var: "x" } or a fixed { entity: { entity_type, name } }; `predicate` is a relation name and is case-insensitive here (FOR_CLIENT and for_client both resolve — unlike SPARQL text, which needs the lowercased IRI local name). ' +
+            .describe('Structured SPARQL-subset request body. Shape: { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having?, order_by?, select?, limit?, distinct? }. Each pattern term is { var: "x" } or a fixed { entity: { entity_type, name } }; `predicate` is a relation name and is case-insensitive here (FOR_CLIENT and for_client both resolve — unlike SPARQL text, which needs the lowercased IRI local name). ' +
             "FILTER — `filters` is a list of conditions, each of exact shape " +
             '{ "compare": { "op": <op>, "left": <term>, "right": <term> } } (or { "and": [<filter>…] }, { "or": [<filter>…] }, { "not": <filter> }). ' +
             "`op` is one of eq | ne | lt | le | gt | ge (NOT the symbols =,<,>). Each <term> is exactly one of " +
@@ -390,7 +390,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             '{ "value": <typed> } — and <typed> is exactly one wrapper: { "str": "…" }, { "i64": 5 }, { "f64": 0.9 }, { "bool": true }, { "date_time": "2026-01-01" } (RFC3339), or { "entity": { "entity_type": "T", "name": "N" } }. ' +
             'Complete runnable example — deals whose amount ≥ 1000000: { "patterns": [{ "subject": { "var": "d" }, "predicate": "for_client", "object": { "var": "c" } }], "filters": [{ "compare": { "op": "ge", "left": { "property": { "var": "d", "field": "amount" } }, "right": { "value": { "f64": 1000000 } } } }] }. ' +
             "Comparisons use the field's real declared type (numbers as numbers, datetimes as instants), so they run server-side. " +
-            'GROUP BY supports both entity-identity keys (group_by: ["s"]) and typed scalar keys via group_keys: a property value ({ property: { var, field, as } }) or a calendar bucket of a datetime property ({ date_bucket: { var, field, granularity: year|month|week|day|hour, as } }). Scalar keys come back per group under value_keys[as] — so a per-area breakdown or a commits-per-month time series is one server-side query, no client-side bucketing. Worked example -- commits per area per month in one query: { "patterns": [{ "subject": { "var": "c" }, "predicate": "committed_to", "object": { "var": "repo" } }], "group_keys": [{ "date_bucket": { "var": "c", "field": "committed_at", "granularity": "month", "as": "m" } }, { "property": { "var": "c", "field": "area", "as": "area" } }], "aggregates": [{ "func": "count", "as": "n" }], "order_by": [{ "var": "m" }] } -- area and committed_at are typed entity attributes (set via entity_properties; readable flat under attributes, never a nested metadata blob), and each group returns value_keys.m + value_keys.area + aggregates.n. `having: [...]` takes the same filter shape over the aggregated groups (e.g. { "compare": { "op": "gt", "left": { "var": "n" }, "right": { "value": { "i64": 10 } } } }); it is evaluated only on this grouped path, NOT alongside `combinators` (UNION/OPTIONAL/MINUS), which route to the analytics engine. Cheap aggregate count: pair an equality having (e.g. { "compare": { "op": "eq", "left": { "var": "n" }, "right": { "value": { "i64": 4 } } } }) with row_limit: 1 -- the response row_page.total reports how many groups match without materializing them all, so you read the count off row_page.total instead of paging every matching row. For snapshot pinning prefer the top-level `as_of` / `as_of_commit_seq` arguments below; a bare `as_of` key inside the body is rejected (the body\'s valid-time field is `as_of_valid_time`).'),
+            'GROUP BY supports both entity-identity keys (group_by: ["s"]) and typed scalar keys via group_keys: a property value ({ property: { var, field, as } }) or a calendar bucket of a datetime property ({ date_bucket: { var, field, granularity: year|month|week|day|hour, as } }). Scalar keys come back per group under value_keys[as] — so a per-area breakdown or a commits-per-month time series is one server-side query, no client-side bucketing. Worked example -- commits per area per month in one query: { "patterns": [{ "subject": { "var": "c" }, "predicate": "committed_to", "object": { "var": "repo" } }], "group_keys": [{ "date_bucket": { "var": "c", "field": "committed_at", "granularity": "month", "as": "m" } }, { "property": { "var": "c", "field": "area", "as": "area" } }], "aggregates": [{ "func": "count", "as": "n" }], "order_by": [{ "var": "m" }] } -- area and committed_at are typed entity attributes (set via entity_properties; readable flat under attributes, never a nested metadata blob), and each group returns value_keys.m + value_keys.area + aggregates.n. `having: [...]` takes the same filter shape over the aggregated groups (e.g. { "compare": { "op": "gt", "left": { "var": "n" }, "right": { "value": { "i64": 10 } } } }). A `combinators` key (UNION/OPTIONAL/MINUS/EXISTS) is rejected here; express those with SPARQL text under mode=sparql. Cheap aggregate count: pair an equality having (e.g. { "compare": { "op": "eq", "left": { "var": "n" }, "right": { "value": { "i64": 4 } } } }) with row_limit: 1 -- the response row_page.total reports how many groups match without materializing them all, so you read the count off row_page.total instead of paging every matching row. For snapshot pinning prefer the top-level `as_of` / `as_of_commit_seq` arguments below; a bare `as_of` key inside the body is rejected (the body\'s valid-time field is `as_of_valid_time`).'),
         as_of: z
             .string()
             .optional()
@@ -429,7 +429,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         .object({
         mode: z.literal("analyze"),
         metric: z
-            .enum(["entity_types", "relations", "overview", "facets", "sparql"])
+            .enum(["entity_types", "relations", "overview", "sparql"])
             .optional(),
         chart: z.enum(["bar", "pie"]).optional(),
         top_k: z.number().int().positive().optional(),

package/dist/tool-runtime.js

@@ -523,81 +523,6 @@ export async function run(client, label, detail, fn, augment) {
         return errorResult(await enrichError(client, error));
     }
 }
-/**
- * Point-of-use feedback affordance attached to every `lbb_search` result: an
- * agent looking at results it can judge gets a ready-to-run
- * `lbb_commit mode=search_feedback` template (the standout "guide ships runnable
- * possibilities" pattern, applied to the moment of judgment). The `search_id` is
- * pre-filled from the response when present so the label set ties back to this
- * exact ranked run.
- */
-export function searchFeedbackHint(data, ctx) {
-    const searchId = data &&
-        typeof data === "object" &&
-        typeof data.search_id === "string"
-        ? data.search_id
-        : undefined;
-    return {
-        how: "If you can judge these results, rate them with lbb_commit mode=search_feedback. Little Big Brain stores the labels as customer-specific qrels (in __lbb_feedback) and exports them as training/eval data for embedding fine-tuning — they improve retrieval, and are kept separate from customer facts. Skip it when you have no basis to judge.",
-        grades: { ideal_or_good: 3, partially_relevant: 1, bad: 0 },
-        example: {
-            tool: "lbb_commit",
-            args: {
-                mode: "search_feedback",
-                ...(ctx.graph !== undefined ? { graph: ctx.graph } : {}),
-                ...(ctx.branch !== undefined ? { branch: ctx.branch } : {}),
-                search_feedback: {
-                    query: ctx.query ?? ctx.queries?.[0] ?? "<the query you ran>",
-                    ...(searchId !== undefined ? { search_id: searchId } : {}),
-                    labels: [
-                        {
-                            target: {
-                                kind: "entity",
-                                entity: { entity_type: "<type>", name: "<name>" },
-                            },
-                            rank: 1,
-                            score: 0.0,
-                            grade: 3,
-                        },
-                    ],
-                    split: "unspecified",
-                },
-            },
-        },
-    };
-}
-export function resolveProfile(profile) {
-    switch (profile) {
-        case "ndcg_v1":
-        case "graph_aware_v1":
-        case "scored_atom_v1":
-        case "baseline":
-            return profile;
-        default:
-            return undefined;
-    }
-}
-export function searchBody(p) {
-    const mode = p.mode ?? "hybrid";
-    return {
-        query: p.query,
-        targets: ["concepts", "entities", "assertions", "paths", "observations"],
-        search: {
-            lexical: mode === "hybrid" || mode === "lexical",
-            bm25: mode === "hybrid" || mode === "bm25",
-            vector: mode === "hybrid" || mode === "vector",
-            consistency: "strong",
-            profile: resolveProfile(p.profile),
-        },
-        max_hops: 2,
-        top_k: p.top_k ?? 10,
-        ...(p.as_of !== undefined ? { as_of_valid_time: p.as_of } : {}),
-        ...(p.as_of_commit_seq !== undefined
-            ? { as_of_commit_seq: p.as_of_commit_seq }
-            : {}),
-        explain: false,
-    };
-}
 export function vegaChart(kind, title, points, categoryTitle, valueTitle) {
     const base = {
         $schema: "https://vega.github.io/schema/vega-lite/v5.json",
@@ -754,16 +679,15 @@ export async function guide(scopedClient) {
         entity_types: entityTypes,
         relations,
         capability: {
-            search: "Use lbb_search for natural-language retrieval and optional multi-query fusion. Semantic graph search may include internally scored paths in its result set.",
-            search_feedback: "After a lbb_search 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.",
+            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.",
-            query: "Use lbb_query for structured SPARQL-subset bodies, SPARQL text, and canned analysis. 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 search 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.",
+            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 to define a new ontology, evolve an existing one in place, or atomically publish ontology/SHACL bundle metadata. Conformance validation runs durably after publication.",
         },
         possibilities: buildPossibilities(relations),
-        how_to: "Ground with lbb_inspect action=guide, retrieve with lbb_search, rate useful/partial/bad retrieval results when you have a judgment, inspect exact entities/schema with lbb_inspect, run analysis with lbb_query, then write graph facts with lbb_commit or configuration with lbb_configure only when intended.",
+        how_to: "Ground with lbb_inspect action=guide, query with lbb_query (structured bodies or SPARQL text), rate useful/partial/bad result sets when you have a judgment, inspect exact entities/schema with lbb_inspect, then write graph facts with lbb_commit or configuration with lbb_configure only when intended.",
     };
 }
 export async function analyze(scopedClient, p) {
@@ -804,31 +728,6 @@ export async function analyze(scopedClient, p) {
             ];
         }
     }
-    else if (metric === "facets") {
-        const field = requireString(p.field, "field");
-        const res = (await scopedClient.graphSearch({
-            query: p.query ?? "",
-            targets: ["entities", "assertions", "observations"],
-            search: {
-                lexical: true,
-                bm25: true,
-                vector: true,
-                consistency: "strong",
-            },
-            facets: [{ field }],
-            max_hops: 1,
-            top_k: 50,
-            explain: false,
-        }));
-        const facet = (res.facets ?? []).find((f) => f.field === field) ??
-            (res.facets ?? [])[0];
-        title = `${p.query ? `"${p.query}"` : "All"} by ${field}`;
-        categoryTitle = field;
-        points = (facet?.buckets ?? []).map((b) => ({
-            label: b.value,
-            value: b.count,
-        }));
-    }
     else if (metric === "sparql") {
         const body = requireObject(p.sparql, "sparql");
         const res = (await scopedClient.sparql(body));
@@ -855,7 +754,7 @@ export async function analyze(scopedClient, p) {
         }));
     }
     else {
-        throw new Error("metric must be one of entity_types, relations, overview, facets, sparql");
+        throw new Error("metric must be one of entity_types, relations, overview, sparql");
     }
     points.sort((a, b) => b.value - a.value);
     if (typeof p.top_k === "number" && p.top_k > 0)

package/dist/tools.js

@@ -1,151 +1,7 @@
 import { z } from "zod";
 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, searchBody, searchFeedbackHint, stableJson, toolResult, } from "./tool-runtime.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) {
-    server.registerTool("lbb_search", {
-        description: "Natural-language retrieval over Little Big Brain. Use `query` for one phrasing or `queries` for reciprocal-rank fusion across phrasings. Semantic graph search can return internally scored paths alongside entity and assertion results. When you can judge returned results, call lbb_commit mode=search_feedback with good=3, partial=1, bad=0 so Little Big Brain can build customer-specific qrels for embedding training.",
-        inputSchema: {
-            query: z.string().optional().describe("Natural-language query"),
-            queries: z
-                .array(z.string())
-                .min(1)
-                .optional()
-                .describe("Multiple phrasings to fuse"),
-            mode: z.enum(["hybrid", "bm25", "vector", "lexical"]).optional(),
-            top_k: z.number().int().positive().optional(),
-            profile: z
-                .enum(["ndcg_v1", "graph_aware_v1", "baseline", "scored_atom_v1"])
-                .optional(),
-            as_of: z
-                .string()
-                .optional()
-                .describe("Valid-time cursor (RFC 3339): results reflect facts true at this instant"),
-            as_of_commit_seq: z
-                .number()
-                .int()
-                .nonnegative()
-                .optional()
-                .describe("Snapshot pin: results reproduce the graph as of this commit sequence (echoed back in snapshot.as_of_commit_seq); a pin past head is an error"),
-            detail: detailSchema,
-            ...graphScope,
-        },
-        annotations: READ_ONLY,
-    }, ({ query, queries, mode, top_k, profile, as_of, as_of_commit_seq, detail, graph, branch, }) => run(client, "lbb_search", detail, () => {
-        const target = scoped(client, graph, branch);
-        if (queries?.length) {
-            return target.multiSearch({
-                subqueries: queries.map((q, index) => ({
-                    id: `q${index}`,
-                    weight: 1.0,
-                    request: searchBody({
-                        query: q,
-                        mode,
-                        top_k,
-                        profile,
-                        as_of,
-                        as_of_commit_seq,
-                    }),
-                })),
-                top_k: top_k ?? 10,
-                explain: false,
-            });
-        }
-        const q = requireString(query, "query");
-        return target.graphSearch(searchBody({
-            query: q,
-            mode,
-            top_k,
-            profile,
-            as_of,
-            as_of_commit_seq,
-        }));
-    }, (data) => ({
-        feedback: searchFeedbackHint(data, { query, queries, graph, branch }),
-    })));
-    server.registerTool("lbb_decode", {
-        description: "Name the relation between two entities from the admissible published vocabulary. Types may be omitted and resolved from entity names.",
-        inputSchema: {
-            source_name: z.string(),
-            source_type: z.string().optional(),
-            target_name: z.string(),
-            target_type: z.string().optional(),
-            use_model_when_forced: z.boolean().optional(),
-            detail: detailSchema,
-            ...graphScope,
-        },
-        annotations: READ_ONLY,
-    }, ({ source_name, source_type, target_name, target_type, use_model_when_forced, detail, graph, branch, }) => run(client, "lbb_decode", detail, () => scoped(client, graph, branch).decode({
-        source: { name: source_name, type: source_type },
-        target: { name: target_name, type: target_type },
-        use_model_when_forced,
-    })));
-    server.registerTool("lbb_ground", {
-        description: "Ground terms to the graph's published vocabulary. complete autocompletes a prefix, resolve snaps free text to real vocabulary, and audit reports graph groundability.",
-        inputSchema: {
-            action: z.enum(["complete", "resolve", "audit"]),
-            prefix: z
-                .string()
-                .optional()
-                .describe("[complete] Text prefix to complete against the real vocabulary"),
-            text: z.string().optional().describe("[resolve] Free text to resolve"),
-            src_type: z
-                .string()
-                .optional()
-                .describe("[complete] Narrow relation completions to those admitted FROM this source type"),
-            dst_type: z
-                .string()
-                .optional()
-                .describe("[complete] Narrow relation completions to those admitted INTO this target type"),
-            kinds: z
-                .array(z.enum([
-                "term",
-                "attribute_value",
-                "attribute_field",
-                "class",
-                "relation",
-                "property",
-            ]))
-                .optional()
-                .describe("Restrict to these vocabulary kinds (default: all)"),
-            top_k: z
-                .number()
-                .int()
-                .positive()
-                .max(50)
-                .optional()
-                .describe("Max results (default 8)"),
-            sample: z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .describe("[audit] Entities sampled for narrowing recall"),
-            detail: detailSchema,
-            ...graphScope,
-        },
-        annotations: READ_ONLY,
-    }, ({ action, prefix, text, src_type, dst_type, kinds, top_k, sample, detail, graph, branch, }) => run(client, "lbb_ground", detail, () => {
-        const target = scoped(client, graph, branch);
-        if (action === "resolve") {
-            return target.resolveTerm({
-                text: requireString(text, "text"),
-                kinds: (kinds ?? ["class", "relation", "property"]),
-                top_k,
-            });
-        }
-        if (action === "audit") {
-            return target.groundability(sample == null ? {} : { sample });
-        }
-        const context = src_type !== undefined || dst_type !== undefined
-            ? { src_type, dst_type }
-            : undefined;
-        return target.suggest({
-            prefix: requireString(prefix, "prefix"),
-            kinds: kinds,
-            context,
-            limit: top_k,
-        });
-    }));
     server.registerTool("lbb_inspect", {
         description: "Read graph context and exact graph facts. Actions: guide, ontology, ontology_conformance, schema, ontology_search, metadata, entity, state, history, transitions, why. schema reads active ontology/SHACL bundle metadata without running validation. 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.",
         inputSchema: inspectWireSchema,
@@ -232,7 +88,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. 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), 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.",
         inputSchema: queryWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -301,19 +157,15 @@ export function registerLbbTools(server, client) {
                             as_of_commit_seq: asOfCommitSeq,
                             as_of_valid_time: asOfValidTime ?? null,
                         };
-                        const combinators = request.combinators;
-                        const hasCombinators = Array.isArray(combinators) && combinators.length > 0;
-                        // HAVING runs on the SPARQL-select path; the combinator/analytics
-                        // path does not evaluate it. Routing a having+combinators body to
-                        // analytics would silently drop the filter, so reject it loudly
-                        // instead (the schema/runtime mismatch the feedback hit).
-                        const hasHaving = Array.isArray(request.having) && request.having.length > 0;
-                        if (hasCombinators && hasHaving) {
-                            throw new Error("HAVING is not evaluated alongside UNION/OPTIONAL/MINUS combinators — remove the combinators to use HAVING (grouped aggregation), or apply the threshold client-side.");
+                        // The analytics route is gone; structured bodies run only on the
+                        // SPARQL-select path, which rejects unknown fields. Name the
+                        // removal here so a `combinators` body fails with an actionable
+                        // message instead of an opaque schema rejection.
+                        if (Array.isArray(request.combinators) &&
+                            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 = hasCombinators
-                            ? await target.analytics(request)
-                            : await target.sparql(request);
+                        const response = await target.sparql(request);
                         const rowPage = rowPageFrom(response);
                         const cursorBase = {
                             v: 1,
@@ -432,7 +284,7 @@ export function registerLbbTools(server, client) {
         }
     }));
     server.registerTool("lbb_commit", {
-        description: "Write graph facts, retract them, or label search 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 labels query/result relevance after lbb_search (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.",
+        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: {
             idempotency_key: z.string().optional(),
             mode: z.enum(["facts", "retract", "search_feedback"]).optional(),

package/package.json

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