@littlebigbrain/mcp 0.14.0 → 0.15.1

package/README.md

@@ -158,7 +158,7 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | `lbb_workflows` | List the starter workflows this server offers and the workflows created from them on a graph (triggered workflows), read one with its status, and preview a new one. Read the workflows with triggers (target type, shards, routing, window, trigger) and what each watch has not sent yet, with origins. |
 | `lbb_workflows_manage` | Create a workflow from a starter workflow on a class (a developer workflow with its workflow type, owned outputs and batch), ask it to run now, or pause and resume a developer workflow. Define a workflow with triggers of your worker (shards, routing field, window) and run it now. |
 | `lbb_workflows_delete` | Delete a triggered workflow, or a workflow with triggers by its name. What it wrote stays. |
-| `lbb_files` | List the files of a graph, and read the parsed pages of one: each line with its id, its box on the page and its text. |
+| `lbb_files` | List the files of a graph, all or by parse status or a part of the name, and read the parsed pages of one: each line with its id, its box on the page and its text. |
 | `lbb_commit` | Write or retract JSON facts, or record search feedback. |
 | `lbb_configure` | Define record types and relationships, list and apply ontology starters (CRM, documents, work), publish validation rules, or keep the graph's notes and worked examples for questions in plain words (`get_rewrite_profile`, `set_rewrite_profile`). |
 | `lbb_evals` | Label query results and check whether later queries return the expected answers. Read the model checks of a graph, and agree with or correct a check that the user confirmed. |

package/dist/files-tool.d.ts

@@ -1,5 +1,14 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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;
+/**
+ * Files `pages` reads to find a name: one page of the list filtered by the
+ * name, the most one page holds.
+ */
+export declare const FILES_PER_NAME_LOOKUP = 1000;
+/** The parse statuses `list` filters by; `waiting` is a file without one. */
+export declare const FILE_PARSE_STATUSES: readonly ["parsed", "waiting", "unsupported", "failed"];
 /** Lines one `pages` call returns by default, and at most. */
 export declare const FILE_LINES_DEFAULT = 200;
 export declare const FILE_LINES_MAX = 1000;

package/dist/files-tool.js

@@ -1,6 +1,20 @@
 import { z } from "zod";
 import { READ_ONLY, detailSchema, graphScope } from "./tool-contracts.js";
 import { enrichError, errorResult, run, scoped, toolResult, } from "./tool-runtime.js";
+/** Files one `list` call returns: one page, newest upload first. */
+export const FILES_PER_LIST = 50;
+/**
+ * Files `pages` reads to find a name: one page of the list filtered by the
+ * name, the most one page holds.
+ */
+export const FILES_PER_NAME_LOOKUP = 1_000;
+/** The parse statuses `list` filters by; `waiting` is a file without one. */
+export const FILE_PARSE_STATUSES = [
+    "parsed",
+    "waiting",
+    "unsupported",
+    "failed",
+];
 /** Lines one `pages` call returns by default, and at most. */
 export const FILE_LINES_DEFAULT = 200;
 export const FILE_LINES_MAX = 1_000;
@@ -62,7 +76,17 @@ export function pageLines(pages, window) {
     return answer;
 }
 const SHA256 = /^[0-9a-fA-F]{64}$/;
-/** The SHA-256 of the file a call names, by `sha256` or by its exact name. */
+/** The files of `files` named `name` exactly (both composed, NFC). */
+function namedExactly(files, name) {
+    const wanted = name.normalize("NFC");
+    return files.filter((file) => file.name.normalize("NFC") === wanted);
+}
+/**
+ * The SHA-256 of the file a call names, by `sha256` or by its exact name.
+ * A name is looked up in the list filtered by it, which finds a file of any
+ * age; that list reads the published generation, so a file uploaded since
+ * is looked up in the newest files of the plain list.
+ */
 async function fileSha(target, args) {
     if (args.sha256) {
         if (!SHA256.test(args.sha256.trim()))
@@ -71,8 +95,16 @@ async function fileSha(target, args) {
     }
     if (!args.name)
         throw new Error("pages needs sha256 or name");
-    const { files } = await target.files.list();
-    const named = files.filter((file) => file.name === args.name);
+    const filtered = await target.files.list({
+        name: args.name,
+        limit: FILES_PER_NAME_LOOKUP,
+    });
+    let files = filtered.files;
+    let named = namedExactly(files, args.name);
+    if (named.length === 0) {
+        ({ files } = await target.files.list({ limit: FILES_PER_LIST }));
+        named = namedExactly(files, args.name);
+    }
     if (named.length === 1)
         return { sha256: named[0].sha256, name: named[0].name };
     if (named.length > 1)
@@ -82,9 +114,17 @@ async function fileSha(target, args) {
 }
 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 the files with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count). 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.",
+        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.",
         inputSchema: {
             action: z.enum(["list", "pages"]),
+            after: z
+                .string()
+                .optional()
+                .describe("list: the next 50 files, from a previous call's next (pass the same parse_status and name)."),
+            parse_status: z
+                .enum(FILE_PARSE_STATUSES)
+                .optional()
+                .describe("list: only the files of this parse status; waiting is a file not parsed yet."),
             sha256: z
                 .string()
                 .optional()
@@ -92,7 +132,7 @@ export function registerFilesTool(server, client) {
             name: z
                 .string()
                 .optional()
-                .describe("pages: the file's exact name, when you do not have its sha256."),
+                .describe("list: only the files whose name holds this text, in any case. pages: the file's exact name, when you do not have its sha256."),
             from: z
                 .number()
                 .int()
@@ -129,10 +169,32 @@ export function registerFilesTool(server, client) {
     }, async (args) => {
         const target = scoped(client, args.graph);
         if (args.action === "list") {
+            // The server binds a cursor to its filters: the next call repeats them.
+            const filters = {
+                ...(args.parse_status ? { parse_status: args.parse_status } : {}),
+                ...(args.name ? { name: args.name } : {}),
+            };
+            let next;
             return run(client, "lbb_files.list", args.detail, async () => {
-                const { files } = await target.files.list();
-                return { files };
-            });
+                const page = await target.files.list({
+                    limit: FILES_PER_LIST,
+                    ...(args.after ? { after: args.after } : {}),
+                    ...(args.parse_status ? { parseStatus: args.parse_status } : {}),
+                    ...(args.name ? { name: args.name } : {}),
+                });
+                next = page.next ?? undefined;
+                return {
+                    files: page.files,
+                    ...(page.as_of_commit_seq != null
+                        ? { as_of_commit_seq: page.as_of_commit_seq }
+                        : {}),
+                };
+            }, () => next
+                ? {
+                    truncated: true,
+                    next: { action: "list", ...filters, after: next },
+                }
+                : {});
         }
         try {
             const file = await fileSha(target, args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "MCP server for little big brain: search, graph queries, and data import",
   "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.26.0",
+    "@littlebigbrain/client": "^0.28.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },