@littlebigbrain/mcp 0.13.0 → 0.15.0

package/README.md

@@ -155,10 +155,10 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | `lbb_fit_sources` | Inspect fit from text and preview the text the fit reads. |
 | `lbb_fit_sources_manage` | Declare, dry-run or refresh a fit source. |
 | `lbb_fit_sources_delete` | Delete a fit source; its suggestions stay. |
-| `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. |
-| `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. |
-| `lbb_workflows_delete` | Delete a triggered workflow. 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_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, 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/dist/tools.js

@@ -613,7 +613,7 @@ export function registerLbbTools(server, client, options = {}) {
         starter: z
             .string()
             .optional()
-            .describe("The starter workflow's catalog id from action=starters, e.g. search.embed (embeddings on a class), ontology.fit (fit from text) or workflow (a developer workflow: your worker's workflow gets the instances). get/preview/use/refresh/pause/resume: required."),
+            .describe("The starter workflow's catalog id from action=starters, e.g. search.embed (embeddings on a class), ontology.fit (fit from text) or workflow (a developer workflow: your worker's workflow gets the instances). get/preview/use/refresh: required. pause/resume: omit to name a workflow with triggers."),
         class: z
             .string()
             .optional()
@@ -690,15 +690,90 @@ export function registerLbbTools(server, client, options = {}) {
         }
         return { starter: args.starter, name: args.name };
     };
+    const workflowName = (args) => {
+        if (!args.name)
+            throw new Error("this action requires name");
+        return args.name;
+    };
+    // A workflow with triggers (`/v1/workflows/named`): your worker's
+    // workflow type, one watch trigger, shards, routing and window.
+    const namedSetup = {
+        shards: z
+            .number()
+            .int()
+            .min(1)
+            .max(16)
+            .optional()
+            .describe("define: engine identities that receive the messages, 1 to 16 (default 1). A change needs every shard's inbox empty."),
+        route_by: z
+            .string()
+            .optional()
+            .describe("define: a field of the class whose value keeps work in order: the changes of one value go to one shard. Default: the instance."),
+        window: z
+            .number()
+            .int()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("define: messages the watch keeps queued per shard, 1 to 128 (default 4)."),
+        trigger: z
+            .string()
+            .optional()
+            .describe("define: the watch trigger's id (default watch). queue: the trigger whose queue to read."),
+    };
+    const namedRequest = (args) => {
+        if (!args.name || !args.class || !args.workflow) {
+            throw new Error("define requires name, class and workflow");
+        }
+        return {
+            name: args.name,
+            workflow: args.workflow,
+            triggers: [
+                {
+                    ...(args.trigger ? { id: args.trigger } : {}),
+                    watch: {
+                        class: args.class,
+                        ...(args.fields ? { fields: args.fields } : {}),
+                    },
+                },
+            ],
+            ...(args.owns ? { owns: args.owns } : {}),
+            ...(args.batch !== undefined ? { batch: args.batch } : {}),
+            ...(args.shards !== undefined ? { shards: args.shards } : {}),
+            ...(args.route_by ? { route_by: args.route_by } : {}),
+            ...(args.window !== undefined ? { window: args.window } : {}),
+        };
+    };
     server.registerTool("lbb_workflows", {
-        description: "Starter workflows and triggered workflows, read only. A starter workflow is a template; a triggered workflow is a workflow created from one on the graph. It watches a class: when a published commit adds or changes instances of the class (or changes the watched fields), the workflow reads them and does its work. search.embed keeps an embedding of the class (the same as lbb_embeddings); ontology.fit reads text fields and files ontology suggestions (the same as lbb_fit_sources); workflow (a developer workflow) sends the new and changed instances to a workflow of the developer's worker as trigger messages, and that code writes the facts the workflow owns. documents.parse reads uploaded PDF files into pages with line boxes, documents.link connects mentions of the same thing across the documents (it writes DocEntry and DocMention instances and links each mention to the entry that defines or describes it), documents.map proposes each link as a FactProposal in the graph's own ontology (fact_subject, fact_predicate, fact_object, fact_confidence, fact_evidence) for a review workflow, and values.extract fills chosen properties from text, each value with a quote; read the files and their pages with lbb_files. starters lists the starter workflows this server offers with their group, settings and whether each can run here. list shows every triggered workflow of the graph with its state (backfilling, ready, paused, failed, unavailable), lag, counters, this month's spend and last error; get shows one (starter and name) with its own status in details (for workflow: the messages sent, the instances waiting, the message in flight and whether it is paused). preview shows what creating one would do (the resolved watch, the instance count and the workflow's own preview; for workflow, the first messages it would send), calls no model and stores nothing. Message workflows of the workflow engine are not listed here. Create, refresh, pause or resume with lbb_workflows_manage; delete with lbb_workflows_delete.",
+        description: "Starter workflows and triggered workflows, read only. A starter workflow is a template; a triggered workflow is a workflow created from one on the graph. It watches a class: when a published commit adds or changes instances of the class (or changes the watched fields), the workflow reads them and does its work. search.embed keeps an embedding of the class (the same as lbb_embeddings); ontology.fit reads text fields and files ontology suggestions (the same as lbb_fit_sources); workflow (a developer workflow) sends the new and changed instances to a workflow of the developer's worker as trigger messages, and that code writes the facts the workflow owns. documents.parse reads uploaded PDF files into pages with line boxes, documents.link connects mentions of the same thing across the documents (it writes DocEntry and DocMention instances and links each mention to the entry that defines or describes it), documents.map proposes each link as a FactProposal in the graph's own ontology (fact_subject, fact_predicate, fact_object, fact_confidence, fact_evidence) for a review workflow, and values.extract fills chosen properties from text, each value with a quote; read the files and their pages with lbb_files. starters lists the starter workflows this server offers with their group, settings and whether each can run here. list shows every triggered workflow of the graph with its state (backfilling, ready, paused, failed, unavailable), lag, counters, this month's spend and last error; get shows one (starter and name) with its own status in details (for workflow: the messages sent, the instances waiting, the message in flight and whether it is paused). preview shows what creating one would do (the resolved watch, the instance count and the workflow's own preview; for workflow, the first messages it would send), calls no model and stores nothing. workflows lists the same workflows as workflows with triggers (/v1/workflows/named): each one's target workflow type (LBB's own are lbb.* types), its shards (engine identities starter.<name> and starter.<name>.<k>), its routing field, its window, its one watch trigger, its status and each shard's inbox; name for one. queue (name) shows what a workflow's watch has not sent yet: each waiting instance with its shard and its origin (a backfill, a commit range with the watched fields and the requests that changed it, a run now, a schema change), the pass in progress, and per shard its message in flight and its first unfinished turns with their origins; page with after and limit. Message workflows of the workflow engine are not listed here. Create, refresh, pause or resume with lbb_workflows_manage; delete with lbb_workflows_delete.",
         inputSchema: {
-            action: z.enum(["starters", "list", "get", "preview"]),
+            action: z.enum([
+                "starters",
+                "list",
+                "get",
+                "preview",
+                "workflows",
+                "queue",
+            ]),
             name: z
                 .string()
                 .optional()
-                .describe("get: the triggered workflow's name. preview: the name a new workflow would get."),
+                .describe("get: the triggered workflow's name. preview: the name a new workflow would get. workflows: one workflow's name (omit for all). queue: required."),
             ...workflowSetup,
+            trigger: namedSetup.trigger,
+            after: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("queue: the position to start from (next_after)."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("queue: items per page, 1 to 100 (default 50)."),
             sample: z
                 .number()
                 .int()
@@ -729,12 +804,22 @@ export function registerLbbTools(server, client, options = {}) {
                     ...(args.sample ? { sample: args.sample } : {}),
                     ...(args.iris ? { iris: args.iris } : {}),
                 });
+            case "workflows":
+                return args.name
+                    ? workflows.named.get(args.name)
+                    : workflows.named.list();
+            case "queue":
+                return workflows.named.queue(workflowName(args), {
+                    ...(args.trigger ? { trigger: args.trigger } : {}),
+                    ...(args.after !== undefined ? { after: args.after } : {}),
+                    ...(args.limit !== undefined ? { limit: args.limit } : {}),
+                });
         }
     }));
     server.registerTool("lbb_workflows_manage", {
-        description: "Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. A workflow that calls models (ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending; resume lets it catch up. search.embed and ontology.fit cannot be paused.",
+        description: "Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. A workflow that calls models (ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending, and stops the claims of a developer workflow's shards; resume lets it catch up. Without starter, pause and resume name a workflow with triggers. search.embed and ontology.fit cannot be paused. define creates or changes a workflow with triggers of the developer's worker (/v1/workflows/named): name, workflow, class and fields (its watch trigger), owns, batch, and shards (engine identities, 1 to 16), route_by (a field that keeps work in order) and window (messages queued per shard, default 4); it needs a server with the workflow engine, and a change of shards waits for empty inboxes. run (name) runs a workflow with triggers now: its watch sends every instance again.",
         inputSchema: {
-            action: z.enum(["use", "refresh", "pause", "resume"]),
+            action: z.enum(["use", "refresh", "pause", "resume", "define", "run"]),
             name: z
                 .string()
                 .optional()
@@ -751,6 +836,7 @@ export function registerLbbTools(server, client, options = {}) {
                 .nonnegative()
                 .optional()
                 .describe("use: a monthly model budget in USD for this workflow, below the stack's own."),
+            ...namedSetup,
             detail: detailSchema,
             ...graphScope,
         },
@@ -763,17 +849,26 @@ export function registerLbbTools(server, client, options = {}) {
             case "refresh":
                 return workflows.triggered.refresh(workflowRef(args));
             case "pause":
-                return workflows.triggered.pause(workflowRef(args), true);
+                return args.starter
+                    ? workflows.triggered.pause(workflowRef(args), true)
+                    : workflows.named.pause(workflowName(args), true);
             case "resume":
-                return workflows.triggered.pause(workflowRef(args), false);
+                return args.starter
+                    ? workflows.triggered.pause(workflowRef(args), false)
+                    : workflows.named.pause(workflowName(args), false);
+            case "define":
+                return workflows.named.put(namedRequest(args));
+            case "run":
+                return workflows.named.run(workflowName(args));
         }
     }));
     server.registerTool("lbb_workflows_delete", {
-        description: "Delete a triggered workflow: it stops following its class, and what it wrote stays. Deleting search.embed deletes the embedding and its vectors, so its class stops being searchable; the suggestions an ontology.fit filed stay; a developer workflow leaves its workflow instance and the facts its code wrote. Ask the user first; confirm must repeat the name.",
+        description: "Delete a triggered workflow: it stops following its class, and what it wrote stays. Deleting search.embed deletes the embedding and its vectors, so its class stops being searchable; the suggestions an ontology.fit filed stay; a developer workflow leaves its workflow instance and the facts its code wrote. Without starter it deletes a workflow with triggers by its name, and its shards stay. Ask the user first; confirm must repeat the name.",
         inputSchema: {
             starter: z
                 .string()
-                .describe("The starter workflow's catalog id, e.g. search.embed."),
+                .optional()
+                .describe("The starter workflow's catalog id, e.g. search.embed. Omit for a workflow with triggers."),
             name: z.string().describe("The triggered workflow's name."),
             confirm: z.string().describe("The same name again, to confirm."),
             detail: detailSchema,
@@ -784,10 +879,10 @@ export function registerLbbTools(server, client, options = {}) {
         if (confirm !== name) {
             throw new Error("confirm must repeat the workflow name");
         }
-        return scoped(client, graph).workflows.triggered.delete({
-            starter,
-            name,
-        });
+        const workflows = scoped(client, graph).workflows;
+        return starter
+            ? workflows.triggered.delete({ starter, name })
+            : workflows.named.delete(name);
     }));
     const modelUse = z
         .enum(["ask", "route", "rerank", "fit", "label"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "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.25.0",
+    "@littlebigbrain/client": "^0.27.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },