@littlebigbrain/mcp 0.15.1 → 0.17.0

package/dist/files-tool.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolHost } from "./approval.js";
 import type { LbbClient, Schemas } from "@littlebigbrain/client";
 /** Files one `list` call returns: one page, newest upload first. */
 export declare const FILES_PER_LIST = 50;
@@ -33,6 +33,8 @@ export interface PageLinesAnswer {
         height: number;
         lines_total: number;
         lines_matching: number;
+        /** The page is mostly image and has fewer than 16 characters of text: the parse read almost none, and OCR is not built. */
+        ocr_required?: true;
         lines: string[];
     }>;
     shown: number;
@@ -48,5 +50,5 @@ export interface PageLinesAnswer {
  * `next` names the page and the offset of the first line left out.
  */
 export declare function pageLines(pages: FilePage[], window: PageLinesWindow): PageLinesAnswer;
-export declare function registerFilesTool(server: McpServer, client: LbbClient): void;
+export declare function registerFilesTool(host: ToolHost, client: LbbClient): void;
 export {};

package/dist/files-tool.js

@@ -66,6 +66,7 @@ export function pageLines(pages, window) {
             height: page.height,
             lines_total: page.lines.length,
             lines_matching: matching,
+            ...(page.ocr_required ? { ocr_required: true } : {}),
             lines: shown,
         });
         if (stoppedAt !== undefined) {
@@ -112,9 +113,9 @@ async function fileSha(target, args) {
     const names = files.slice(0, 20).map((file) => file.name);
     throw new Error(`no file is named ${args.name}${names.length ? `; the graph has ${names.join(", ")}` : "; the graph has no files"}`);
 }
-export function registerFilesTool(server, client) {
-    server.registerTool("lbb_files", {
-        description: "Files of the graph, read only. A file is a document the graph holds (its bytes and a Document entity); the documents.parse workflow (lbb_workflows) reads the text layer of each PDF into pages with every line and its box. list shows 50 files a call, newest upload first, with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count); when more follow, next names the after of the next call (with the same filters). parse_status keeps the files of one parse status; waiting is a file not parsed yet. name keeps the files whose name holds a text, in any case. A filtered list reads the Documents of the published generation and names its commit (as_of_commit_seq). A file uploaded, renamed or parsed a moment ago can be missing from it until publication. pages reads parsed pages of one file (sha256, or name for an exact file name): from is the first 0-based page index (the page of a region and of a DocEntry or DocMention), to the page after the last one (default from+1). Each line comes as `<line id> [x0,y0,x1,y1] <text>`: the id is p<page number>-l<line number>, both from 1, and the box is normalized to the page (0 to 1, origin top left). contains keeps the lines that hold a text; max_lines caps the lines (default 200). When lines were left out, next names the from and line_offset of the next call. A file not parsed yet answers file_not_parsed.",
+export function registerFilesTool(host, client) {
+    host.register("lbb_files", {
+        description: "Files of the graph, read only. A file is a document the graph holds (its bytes and a Document entity). A file a workflow run wrote (a generated file, with an origin and an expires_at) has no Document and no Document IRI. It expires unless a person keeps it, so the list shows it only after that, and it is never evidence for a fact. The documents.parse workflow (lbb_workflows) reads the text layer of each PDF into pages with every line and its box. list shows 50 files a call, newest upload first, with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count); when more follow, next names the after of the next call (with the same filters). parse_status keeps the files of one parse status; waiting is a file not parsed yet. name keeps the files whose name holds a text, in any case. A filtered list reads the Documents of the published generation and names its commit (as_of_commit_seq). A file uploaded, renamed or parsed a moment ago can be missing from it until publication. pages reads parsed pages of one file (sha256, or name for an exact file name): from is the first 0-based page index (the page of a region and of a DocEntry or DocMention), to the page after the last one (default from+1). Each line comes as `<line id> [x0,y0,x1,y1] <text>`: the id is p<page number>-l<line number>, both from 1, and the box is normalized to the page (0 to 1, origin top left). contains keeps the lines that hold a text; max_lines caps the lines (default 200). When lines were left out, next names the from and line_offset of the next call. A file not parsed yet answers file_not_parsed.",
         inputSchema: {
             action: z.enum(["list", "pages"]),
             after: z
@@ -212,8 +213,12 @@ export function registerFilesTool(server, client) {
             const range = answer.to - answer.from > 1
                 ? `pages ${answer.from} to ${answer.to - 1}`
                 : `page ${answer.from}`;
+            const scanned = lines.pages.filter((entry) => entry.ocr_required).length;
+            const needsOcr = scanned
+                ? `; ${scanned === 1 ? "1 page needs" : `${scanned} pages need`} OCR, almost no text was read`
+                : "";
             return toolResult({
-                summary: `${label}, ${range} of ${answer.page_count} (0-based): ${lines.shown} lines${lines.next ? ", more after next" : ""}`,
+                summary: `${label}, ${range} of ${answer.page_count} (0-based): ${lines.shown} lines${needsOcr}${lines.next ? ", more after next" : ""}`,
                 data: {
                     sha256: answer.sha256,
                     parser: answer.parser,

package/dist/index.d.ts

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

package/dist/query-observer.d.ts

@@ -13,7 +13,44 @@ export interface McpQueryStageEvent {
     cursor_bytes?: number;
     text_bytes?: number;
 }
+/** What the approval step of a destructive call decided. */
+export type McpApprovalDecision = 
+/** The person ticked the box. */
+"approved"
+/** The person declined, or left the box unticked. */
+ | "declined" | "cancelled"
+/** The approval request itself failed. */
+ | "failed"
+/** The client cannot show the question, so the call was refused. */
+ | "unavailable"
+/** The client cannot show the question; LBB_MCP_DESTRUCTIVE=allow let it run. */
+ | "allowed_by_setting";
+/**
+ * One tool call, for the server's log. It holds no arguments, texts or
+ * keys: the tool, its action, the outcome and the JSON-RPC request id.
+ */
+export interface McpToolCallEvent {
+    event: "mcp_tool_call";
+    tool: string;
+    /** The call's `action` (or `mode`), when it names one. */
+    action?: string;
+    outcome: "ok" | "error";
+    /** The error code of a failed call, for example approval_declined. */
+    code?: string;
+    /** What the approval step decided, when the call is destructive. */
+    approval?: McpApprovalDecision;
+    request_id: string | number;
+}
 export interface LbbServerOptions {
+    /**
+     * A destructive call when the client cannot ask the person (no MCP form
+     * elicitation): "refuse" returns approval_required and sends nothing;
+     * "allow" sends it without a question. Default: "allow" when the
+     * environment sets LBB_MCP_DESTRUCTIVE=allow, else "refuse".
+     */
+    destructiveWithoutApproval?: "refuse" | "allow";
+    /** Receives one event per tool call. Default: a JSON line on stderr. */
+    log?: (event: Readonly<McpToolCallEvent>) => void;
     /** Query text only; fitting and rendering always use this same format. */
     queryTextFormat?: "compact" | "pretty";
     timing?: {

package/dist/rdf-tool.d.ts

@@ -1,3 +1,3 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { LbbClient } from "@littlebigbrain/client";
-export declare function registerRdfTool(server: McpServer, client: LbbClient): void;
+import { type ToolHost } from "./approval.js";
+export declare function registerRdfTool(host: ToolHost, client: LbbClient): void;

package/dist/rdf-tool.js

@@ -1,6 +1,13 @@
 import { z } from "zod";
 import { graphScope, detailSchema, advertiseUnion } from "./tool-contracts.js";
 import { contentHashKey, errorResult, run, scoped } from "./tool-runtime.js";
+import { APPROVAL_TEXT, graphLabel, sparqlUpdateMessage, } from "./approval.js";
+/**
+ * An update form that can remove statements: DELETE (DATA, WHERE, or with
+ * INSERT), CLEAR, DROP, and MOVE and COPY, which empty their target first.
+ * A word in a literal or an IRI also matches; that only asks once more.
+ */
+const REMOVING_UPDATE = /\b(DELETE|CLEAR|DROP|MOVE|COPY)\b/i;
 const input = z.discriminatedUnion("action", [
     z
         .object({
@@ -33,9 +40,9 @@ const input = z.discriminatedUnion("action", [
     })
         .strict(),
 ]);
-export function registerRdfTool(server, client) {
-    server.registerTool("lbb_rdf", {
-        description: "Store and extend complete RDF/OWL documents through MCP. import accepts Turtle/N-Triples/N-Quads/TriG without conversion; update executes INSERT DATA for additive edits. Replacing/removing axioms is unsupported; use a new versioned LBB graph for a revised document. Named RDF graphs are unsupported; Turtle/N-Triples use the default graph, and dataset formats must contain only default-graph quads. These write graph facts, distinct from lbb_configure's native schema metadata. A first RDF write selects RDF-native storage, which refuses later property-graph commits; choose the write workflow before bootstrap. Retries deduplicate by content unless idempotency_key is supplied. A completed write schedules publication; inspect action=publication and verify using lbb_query entailment=owl.",
+export function registerRdfTool(host, client) {
+    host.register("lbb_rdf", {
+        description: `Store and extend complete RDF/OWL documents through MCP. import accepts Turtle/N-Triples/N-Quads/TriG without conversion; update executes INSERT DATA for additive edits. Replacing/removing axioms is unsupported; use a new versioned LBB graph for a revised document. Named RDF graphs are unsupported; Turtle/N-Triples use the default graph, and dataset formats must contain only default-graph quads. These write graph facts, distinct from lbb_configure's native schema metadata. A first RDF write selects RDF-native storage, which refuses later property-graph commits; choose the write workflow before bootstrap. Retries deduplicate by content unless idempotency_key is supplied. A completed write schedules publication; inspect action=publication and verify using lbb_query entailment=owl. An update with DELETE, CLEAR, DROP, MOVE or COPY asks the person to approve it first; the question quotes the operations that remove. ${APPROVAL_TEXT}`,
         inputSchema: advertiseUnion("action", input),
         annotations: {
             readOnlyHint: false,
@@ -43,11 +50,18 @@ export function registerRdfTool(server, client) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, (raw) => {
+    }, async (raw, extra) => {
         const parsed = input.safeParse(raw);
         if (!parsed.success)
             return errorResult(parsed.error);
         const args = parsed.data;
+        if (args.action === "update" && REMOVING_UPDATE.test(args.update)) {
+            const refused = await host.approve(extra, {
+                message: sparqlUpdateMessage(graphLabel(client, args.graph), args.update),
+            });
+            if (refused)
+                return refused;
+        }
         return run(client, `lbb_rdf.${args.action}`, args.detail, async () => {
             const target = scoped(client, args.graph);
             const { idempotency_key } = args;

package/dist/records-write.d.ts

@@ -0,0 +1,101 @@
+import { type LbbClient } from "@littlebigbrain/client";
+import { type ToolExtra, type ToolHost } from "./approval.js";
+type Args = {
+    records?: Record<string, unknown>;
+    idempotencyKey?: string;
+    expectedGraphEpoch?: string;
+    graph?: string;
+    legacyInputs: boolean;
+};
+export declare function commitRecordsTool(host: ToolHost, client: LbbClient, extra: ToolExtra, args: Args): Promise<{
+    structuredContent: {
+        error: {
+            idempotency_key: string;
+            type: string;
+            code: string;
+            message: string;
+            outcome: string;
+            param: null;
+            request_id: null;
+            doc_url: null;
+            status: null;
+        } | {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            param: string | null;
+            request_id: string | null;
+            doc_url: string | null;
+            status: number;
+            outcome?: undefined;
+        } | {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            param: null;
+            request_id: null;
+            doc_url: null;
+            status: null;
+            outcome?: undefined;
+        };
+    };
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            message_truncated: boolean;
+            status: number | null;
+            param: string | null;
+            request_id: string | null;
+            doc_url: string | null;
+        };
+    };
+} | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            type: string;
+            code: string;
+            message: string;
+            outcome: string;
+            idempotency_key: string;
+            epoch: string;
+            commit_seq: number;
+        };
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        summary: string;
+        data: {
+            idempotent_replay: boolean;
+            object: import("@littlebigbrain/client").components["schemas"]["RecordCommitObject"];
+            receipt: import("@littlebigbrain/client").components["schemas"]["RecordCommitReceipt"];
+            version: import("@littlebigbrain/client").components["schemas"]["RecordsVersion"];
+        };
+    };
+    isError?: undefined;
+}>;
+export {};

package/dist/records-write.js

@@ -0,0 +1,150 @@
+/** Records-specific MCP framing; semantic admission belongs to the server. */
+import { Buffer } from "node:buffer";
+import { LbbCapabilityError, } from "@littlebigbrain/client";
+import { graphLabel, oneLine, } from "./approval.js";
+import { HARD_OUTPUT_CHARS } from "./tool-contracts.js";
+import { contentHashKey, enrichError, errorResult, scoped, ToolError, } from "./tool-runtime.js";
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const nonempty = (value) => isObject(value)
+    ? Object.keys(value).length > 0
+    : Array.isArray(value) && value.length > 0;
+function mayRemove(body) {
+    if (body.replace_scope === true)
+        return true;
+    for (const rows of [body.entities, body.relationships]) {
+        if (!Array.isArray(rows))
+            continue;
+        for (const row of rows) {
+            if (isObject(row) &&
+                (row.delete === true ||
+                    row.asserted === false ||
+                    nonempty(row.set) ||
+                    nonempty(row.unset) ||
+                    nonempty(row.remove)))
+                return true;
+        }
+    }
+    return false;
+}
+function approvalMessage(client, graph, body) {
+    const entities = Array.isArray(body.entities) ? body.entities.length : 0;
+    const relationships = Array.isArray(body.relationships)
+        ? body.relationships.length
+        : 0;
+    const action = body.replace_scope === true
+        ? "Replace the complete desired support"
+        : "Apply record edits that may replace or remove support";
+    return `${action} in ${graphLabel(client, graph)}, owner "${oneLine(body.owner ?? "application")}", scope "${oneLine(body.scope ?? "default")}" (${entities} entities, ${relationships} relationships)? Other owners' support is retained. This does not erase retained history.`;
+}
+function boundedError(value, key) {
+    const original = errorResult(value);
+    // A typed server error can also need receipt recovery. Keep its code/status
+    // unchanged, but retain the derived key rather than making callers guess it.
+    const identity = {
+        ...original.structuredContent.error,
+        ...(key !== undefined ? { idempotency_key: key } : {}),
+    };
+    const result = {
+        ...original,
+        structuredContent: { error: identity },
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: identity }, null, 2),
+            },
+        ],
+    };
+    if (Buffer.byteLength(result.content[0].text, "utf8") <= HARD_OUTPUT_CHARS)
+        return result;
+    const source = result.structuredContent.error;
+    const short = (value, max = 512) => typeof value === "string" &&
+        Buffer.byteLength(JSON.stringify(value), "utf8") <= max
+        ? value
+        : null;
+    const error = {
+        type: short(source.type) ?? "tool_error",
+        code: short(source.code) ?? "record_error_output_limit",
+        message: "The complete server error exceeds the MCP output budget. Its code/status are retained; inspect the SDK or HTTP response for the full message. No complete commit receipt was returned.",
+        message_truncated: true,
+        status: typeof source.status === "number" && Number.isSafeInteger(source.status)
+            ? source.status
+            : null,
+        param: short(source.param),
+        request_id: short(source.request_id),
+        doc_url: short(source.doc_url),
+        ...(key !== undefined ? { idempotency_key: key } : {}),
+    };
+    const payload = { error };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        structuredContent: payload,
+    };
+}
+export async function commitRecordsTool(host, client, extra, args) {
+    let requestKey;
+    try {
+        if (args.legacyInputs)
+            throw new ToolError("record_payload_ambiguous", "mode=records cannot include legacy facts, feedback, retract, dry_run, observed_at or edge_idempotency arguments, even when empty or false");
+        if (!isObject(args.records) || args.records.version !== "records/1") {
+            throw new ToolError("record_version_unsupported", "mode=records requires a records object with explicit version records/1");
+        }
+        // Capture before approval/capability I/O. Do not strip unknown fields,
+        // normalize IRIs, bind friendly keys or copy the server's source policy.
+        const raw = JSON.stringify(args.records);
+        if (Buffer.byteLength(raw, "utf8") > 1024 * 1024)
+            throw new ToolError("record_payload_budget", "The records body exceeds the MCP one MiB request budget; use a bounded SDK request");
+        const body = JSON.parse(raw);
+        if (!isObject(body) || body.version !== "records/1")
+            throw new ToolError("record_version_unsupported", "the encoded records object must retain version records/1");
+        const graph = args.graph;
+        const epoch = args.expectedGraphEpoch;
+        const key = args.idempotencyKey ??
+            contentHashKey({ graph: graph ?? client.graphName }, { mode: "records", expected_graph_epoch: epoch, body });
+        if (key.trim().length === 0)
+            throw new ToolError("record_payload_invalid", "records idempotency_key must not be empty");
+        // This is an output-identity allowance, not a duplicate of HTTP key syntax.
+        // It leaves room to return the FULL original key if receipt recovery fails.
+        if (Buffer.byteLength(JSON.stringify(key), "utf8") > 8192)
+            throw new ToolError("record_payload_budget", "The idempotency key exceeds the MCP recovery-identity budget");
+        requestKey = key;
+        if (mayRemove(body)) {
+            const refused = await host.approve(extra, {
+                message: approvalMessage(client, graph, body),
+            });
+            if (refused)
+                return refused;
+        }
+        const result = await scoped(client, graph).records.commit(body, { idempotencyKey: key, expectedGraphEpoch: epoch });
+        const envelope = { summary: "lbb_commit.records", data: result };
+        const text = JSON.stringify(envelope);
+        if (Buffer.byteLength(text, "utf8") > HARD_OUTPUT_CHARS) {
+            // Acceptance is already known; do not relabel it as a failed mutation or
+            // an unknown outcome just because the full result cannot fit this tool.
+            const error = {
+                type: "tool_error",
+                code: "record_accepted_output_limit",
+                message: "The record commit was accepted, but its complete receipt exceeds the MCP output budget. Recover the original receipt with the same body/key through the SDK or HTTP API.",
+                outcome: "accepted",
+                idempotency_key: key,
+                epoch: result.receipt.epoch,
+                commit_seq: result.receipt.commit_seq,
+            };
+            const payload = { error };
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                structuredContent: payload,
+            };
+        }
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: envelope,
+        };
+    }
+    catch (error) {
+        return boundedError(error instanceof LbbCapabilityError
+            ? new ToolError("record_capability_unavailable", error.message)
+            : await enrichError(client, error), requestKey);
+    }
+}

package/dist/reviews-tool.d.ts

@@ -0,0 +1,3 @@
+import type { LbbClient } from "@littlebigbrain/client";
+import { type ToolHost } from "./approval.js";
+export declare function registerReviewsTools(host: ToolHost, client: LbbClient): void;