@littlebigbrain/mcp 0.4.3 → 0.4.4

package/README.md

@@ -68,6 +68,12 @@ missing.
 
 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.
+
 ## Embed the server
 
 For self-hosting behind your own auth, the package also serves the tools over HTTP:

package/dist/tool-contracts.js

@@ -390,11 +390,11 @@ 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 } } } }). 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`).'),
+            '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 use the top-level `as_of_commit_seq` argument or the same body field. Valid-time `as_of` and `as_of_valid_time` selectors are unsupported and rejected before HTTP.'),
         as_of: z
             .string()
             .optional()
-            .describe("Snapshot pin (valid-time, RFC3339): evaluate the body as of this instant. Folded into the request's `as_of_valid_time`. Top-level here is the supported spelling — a bare `as_of` inside the body is rejected, since the server silently ignores it."),
+            .describe("Unsupported in structured and SPARQL text modes; use as_of_commit_seq for a retained commit snapshot."),
         as_of_commit_seq: z
             .number()
             .int()
@@ -412,8 +412,12 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         query: z
             .string()
             .optional()
-            .describe(`SPARQL 1.1 query text (SELECT or ASK). ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10`),
-        as_of: z.string().optional(),
+            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10`),
+        // Kept for an actionable error when an older connector sends this field.
+        as_of: z
+            .string()
+            .optional()
+            .describe("Unsupported in SPARQL text mode; use as_of_commit_seq."),
         as_of_commit_seq: z
             .number()
             .int()

package/dist/tools.js

@@ -124,38 +124,36 @@ export function registerLbbTools(server, client) {
                             stableJson(args.body) !== stableJson(cursor.body)) {
                             throw new Error("cursor body does not match the supplied body argument");
                         }
-                        // The body's valid-time field is `as_of_valid_time`; the server
-                        // ignores a bare `as_of` key, so a naive caller would chart
-                        // head-snapshot data and never know. Turn that silent no-op into a
-                        // clear error pointing at the right spelling.
-                        if (body.as_of !== undefined) {
-                            throw new Error("the structured body has an `as_of` key, which the server ignores — use the top-level `as_of` argument (valid-time, RFC3339) or rename it to `as_of_valid_time` inside the body");
+                        if (args.as_of !== undefined ||
+                            cursor?.as_of !== undefined ||
+                            body.as_of !== undefined ||
+                            body.as_of_valid_time !== undefined) {
+                            throw new Error("structured SPARQL valid-time selectors are not supported; use as_of_commit_seq for a retained commit snapshot, or start a new query without the valid-time selector");
                         }
-                        if (cursor &&
-                            args.as_of !== undefined &&
-                            args.as_of !== cursor.as_of) {
-                            throw new Error("cursor as_of does not match the supplied as_of argument");
+                        // Resolve the top-level or body commit pin once and retain it
+                        // across cursor pages. The API validates its exact RDF lineage.
+                        if (body.as_of_commit_seq !== undefined &&
+                            body.as_of_commit_seq !== null &&
+                            (typeof body.as_of_commit_seq !== "number" ||
+                                !Number.isSafeInteger(body.as_of_commit_seq) ||
+                                body.as_of_commit_seq < 0)) {
+                            throw new Error("body as_of_commit_seq must be a nonnegative safe integer");
                         }
-                        // Commit-seq pin: top-level arg, else the body field, pinned for
-                        // continuation. Valid-time pin: cursor, else top-level arg, else the
-                        // body's `as_of_valid_time`. Both are resolved here and set
-                        // explicitly so the request never depends on the body's spelling.
                         const requestedCommitSeq = args.as_of_commit_seq ??
                             (typeof body.as_of_commit_seq === "number"
                                 ? body.as_of_commit_seq
                                 : undefined);
+                        if (cursor &&
+                            args.as_of_commit_seq !== undefined &&
+                            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 asOfValidTime = cursor?.as_of ??
-                            args.as_of ??
-                            (typeof body.as_of_valid_time === "string"
-                                ? body.as_of_valid_time
-                                : undefined);
                         const request = {
                             ...body,
                             limit: rowLimit,
                             offset,
                             as_of_commit_seq: asOfCommitSeq,
-                            as_of_valid_time: asOfValidTime ?? null,
                         };
                         // The analytics route is gone; structured bodies run only on the
                         // SPARQL-select path, which rejects unknown fields. Name the
@@ -175,7 +173,6 @@ export function registerLbbTools(server, client) {
                             detail,
                             row_limit: rowLimit,
                             body,
-                            as_of: asOfValidTime,
                             as_of_commit_seq: asOfCommitSeq,
                         };
                         const next = rowPageNext(cursorBase, rowPage);
@@ -193,21 +190,17 @@ export function registerLbbTools(server, client) {
                         normalizeLbbIris(args.query).query !== cursor.query) {
                         throw new Error("cursor query does not match the supplied query argument");
                     }
-                    if (cursor &&
-                        args.as_of !== undefined &&
-                        args.as_of !== cursor.as_of) {
-                        throw new Error("cursor as_of does not match the supplied as_of argument");
+                    if (args.as_of !== undefined || cursor?.as_of !== undefined) {
+                        throw new Error("SPARQL text valid-time as_of is not supported; use as_of_commit_seq for a retained commit snapshot, or start a new query without as_of");
                     }
                     if (cursor &&
                         args.as_of_commit_seq !== undefined &&
                         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 asOf = cursor?.as_of ?? args.as_of;
                     const asOfCommitSeq = await queryCommitPin(target, args.as_of_commit_seq, cursor);
                     const response = await target.sparqlText({
                         query,
-                        as_of_valid_time: asOf ?? null,
                         as_of_commit_seq: asOfCommitSeq ?? null,
                         limit: rowLimit,
                         offset,
@@ -222,7 +215,6 @@ export function registerLbbTools(server, client) {
                         detail,
                         row_limit: rowLimit,
                         query,
-                        as_of: asOf,
                         as_of_commit_seq: asOfCommitSeq,
                     };
                     const next = rowPageNext(cursorBase, rowPage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "MCP server for little big brain — graph and hybrid search tools for agents",
   "license": "Apache-2.0",
   "repository": {