datanotes 2.0.1 → 3.0.0

package/dist/api/mcp.d.cts

@@ -0,0 +1,108 @@
+/**
+ * `datanotes/mcp`: the engine's operations as Model Context Protocol (MCP) tools, for people who
+ * build their own MCP server on Datanotes: list some of them next to tools of their own, call them
+ * through a `DatanotesClient`, and start the server's instructions with the engine's.
+ *
+ *   const tools = [...engineTools({ only: ["select_rows", "insert_row"] }), myTool];
+ *   if (isEngineTool(name)) return callEngineTool(client, name, args);
+ *
+ * The definitions come from the catalogue (`catalog.ts`), so they always match the engine's
+ * routes; `datanotes mcp` (src/mcp) serves the same ones. Next to them, the docs tools (list_docs,
+ * read_docs, search_docs: docsTools, callDocsTool) read the docs of this version that the package
+ * ships (src/api/docs.ts, Node only), with no engine; given a client, search_docs also asks the
+ * engine for its ranking of the docs by meaning, and fuses it with its own (hybrid search). Plain
+ * data and functions: no dependency, not even the MCP SDK, which only the server that uses them
+ * needs.
+ */
+import { type OperationDef } from "./catalog.cjs";
+import { type ActorInfo, type DatanotesClient } from "./client.cjs";
+import { type DocsLibrary } from "./docs.cjs";
+/** What an agent needs to know before it uses the engine's tools: `datanotes mcp` sends it as its instructions. */
+export declare const ENGINE_INSTRUCTIONS = "Database of Markdown notes: tables defined in metastore.yaml, a row is a note whose front matter key `table` names its table, and each front matter key is a column. Use list_tables / describe_table first, select_rows to read, insert_row / update_row / update_rows / batch to write (validated, journaled, undo with undo_migration). Change the schema only with its operations (create_table, add_column, alter_column, create_view, ...); never edit metastore.yaml. Every table and column needs a `description` of what it holds, or it is refused: descriptions are how agents and people understand the schema. Fill those describe_table lists in `missing_descriptions` with alter_table / alter_column. A body you write links the notes it mentions by name (a one-word name only with a capital, inside a sentence): when a write returns ambiguous_mentions, read the candidate notes and link the right one with update_row and autolink: false, or leave the text. Read the docs of this version with search_docs and read_docs.";
+/** An engine operation as an MCP tool definition (`tools/list`). */
+export interface EngineTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: OperationDef["annotations"];
+}
+/** Which engine tools to keep: only these names, and none of those. Unknown names throw, so a typo shows at once. */
+export interface EngineToolFilter {
+    only?: readonly string[];
+    except?: readonly string[];
+}
+/** MCP content of a tool's result (`tools/call`): what a server returns to the agent. */
+export interface ToolContent {
+    [key: string]: unknown;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/**
+ * The engine's operations as MCP tool definitions, in the catalogue's order. Each one is a fresh
+ * copy (name, description, input schema, annotations), safe to change.
+ */
+export declare function engineTools(filter?: EngineToolFilter): EngineTool[];
+/** Is this the name of an engine tool (kept by the filter, when one is given)? */
+export declare function isEngineTool(name: string, filter?: EngineToolFilter): boolean;
+/** MCP content of a result: the text, and the object itself when it is one. */
+export declare function toolContent(ok: boolean, value: unknown): ToolContent;
+/**
+ * An error result as the agents of a server that serves the docs tools read it: each `Docs:` line
+ * names only the read_docs call that reads its section offline, with no web address to fetch, as
+ * `datanotes mcp` answers. A docs line that is not a page of the docs, and any other result, stay
+ * as they are.
+ */
+export declare function offlineDocs(content: ToolContent): ToolContent;
+/**
+ * What is wrong with a call before it reaches the engine, as the text the agent reads: a tool that
+ * does not exist (or that the filter leaves out), arguments the tool does not take, a required
+ * one missing, a value of the wrong type. Each with the closest real name, the tool's arguments
+ * and its docs. Null when the call can be sent.
+ */
+export declare function callProblem(name: string, args: Record<string, unknown>, filter?: EngineToolFilter): string | null;
+/**
+ * Call an engine tool for an agent and answer its MCP content. A refusal, bad arguments, a name
+ * the filter leaves out and an engine that does not answer come back as an error result
+ * (`isError`), never as a throw: the agent reads why, how to fix it and where to read more.
+ * `actor` names the agent in the journal (default: the client's own actor).
+ */
+export declare function callEngineTool(client: DatanotesClient, name: string, args?: Record<string, unknown>, opts?: EngineToolFilter & {
+    actor?: ActorInfo;
+}): Promise<ToolContent>;
+/** The names of the docs tools. */
+export declare const DOCS_TOOL_NAMES: readonly ["list_docs", "read_docs", "search_docs"];
+/**
+ * The tools that read the Datanotes documentation of this version, shipped in the package
+ * (`list_docs`, `read_docs`, `search_docs`), as MCP tool definitions: fresh copies, kept by the
+ * same filter as engineTools (unknown names throw). They need no engine: callDocsTool answers them.
+ */
+export declare function docsTools(filter?: EngineToolFilter): EngineTool[];
+/** Is this the name of a docs tool (kept by the filter, when one is given)? */
+export declare function isDocsTool(name: string, filter?: EngineToolFilter): boolean;
+/** How long search_docs waits for the engine's ranking of the docs by meaning, before it ranks by words alone. */
+export declare const SEMANTIC_DOCS_TIMEOUT_MS = 10000;
+/** After an engine did not answer (or not in time), how long search_docs ranks by words alone before it asks it again. */
+export declare const SEMANTIC_DOCS_RETRY_MS = 60000;
+/** How search_docs reaches the engine for its ranking by meaning (hybrid search). */
+export interface DocsSearchOptions {
+    /** The engine: with semantic search on, search_docs fuses its ranking by meaning with the ranking by words. */
+    client?: DatanotesClient;
+    /** Who asks, as for engine tools (default: the client's own actor). */
+    actor?: ActorInfo;
+    /** How long to wait for the engine (default SEMANTIC_DOCS_TIMEOUT_MS). */
+    semanticTimeoutMs?: number;
+}
+/**
+ * Answer a docs tool for an agent (MCP content): text, or an error result (`isError`) that says
+ * what is wrong (an unknown page or section, with the closest real ones), how to fix it and where
+ * to read more; never a throw. `docs`: the docs to read (default: the package's own, `openDocs()`).
+ * `client`: the engine, for search_docs' hybrid search (without it, or when the engine has no
+ * ranking by meaning to give, search_docs ranks by words alone).
+ */
+export declare function callDocsTool(name: string, args?: Record<string, unknown>, opts?: EngineToolFilter & DocsSearchOptions & {
+    docs?: DocsLibrary;
+}): Promise<ToolContent>;

package/dist/api/mcp.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `datanotes/mcp`: the engine's operations as Model Context Protocol (MCP) tools, for people who
+ * build their own MCP server on Datanotes: list some of them next to tools of their own, call them
+ * through a `DatanotesClient`, and start the server's instructions with the engine's.
+ *
+ *   const tools = [...engineTools({ only: ["select_rows", "insert_row"] }), myTool];
+ *   if (isEngineTool(name)) return callEngineTool(client, name, args);
+ *
+ * The definitions come from the catalogue (`catalog.ts`), so they always match the engine's
+ * routes; `datanotes mcp` (src/mcp) serves the same ones. Next to them, the docs tools (list_docs,
+ * read_docs, search_docs: docsTools, callDocsTool) read the docs of this version that the package
+ * ships (src/api/docs.ts, Node only), with no engine; given a client, search_docs also asks the
+ * engine for its ranking of the docs by meaning, and fuses it with its own (hybrid search). Plain
+ * data and functions: no dependency, not even the MCP SDK, which only the server that uses them
+ * needs.
+ */
+import { type OperationDef } from "./catalog.js";
+import { type ActorInfo, type DatanotesClient } from "./client.js";
+import { type DocsLibrary } from "./docs.js";
+/** What an agent needs to know before it uses the engine's tools: `datanotes mcp` sends it as its instructions. */
+export declare const ENGINE_INSTRUCTIONS = "Database of Markdown notes: tables defined in metastore.yaml, a row is a note whose front matter key `table` names its table, and each front matter key is a column. Use list_tables / describe_table first, select_rows to read, insert_row / update_row / update_rows / batch to write (validated, journaled, undo with undo_migration). Change the schema only with its operations (create_table, add_column, alter_column, create_view, ...); never edit metastore.yaml. Every table and column needs a `description` of what it holds, or it is refused: descriptions are how agents and people understand the schema. Fill those describe_table lists in `missing_descriptions` with alter_table / alter_column. A body you write links the notes it mentions by name (a one-word name only with a capital, inside a sentence): when a write returns ambiguous_mentions, read the candidate notes and link the right one with update_row and autolink: false, or leave the text. Read the docs of this version with search_docs and read_docs.";
+/** An engine operation as an MCP tool definition (`tools/list`). */
+export interface EngineTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: OperationDef["annotations"];
+}
+/** Which engine tools to keep: only these names, and none of those. Unknown names throw, so a typo shows at once. */
+export interface EngineToolFilter {
+    only?: readonly string[];
+    except?: readonly string[];
+}
+/** MCP content of a tool's result (`tools/call`): what a server returns to the agent. */
+export interface ToolContent {
+    [key: string]: unknown;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/**
+ * The engine's operations as MCP tool definitions, in the catalogue's order. Each one is a fresh
+ * copy (name, description, input schema, annotations), safe to change.
+ */
+export declare function engineTools(filter?: EngineToolFilter): EngineTool[];
+/** Is this the name of an engine tool (kept by the filter, when one is given)? */
+export declare function isEngineTool(name: string, filter?: EngineToolFilter): boolean;
+/** MCP content of a result: the text, and the object itself when it is one. */
+export declare function toolContent(ok: boolean, value: unknown): ToolContent;
+/**
+ * An error result as the agents of a server that serves the docs tools read it: each `Docs:` line
+ * names only the read_docs call that reads its section offline, with no web address to fetch, as
+ * `datanotes mcp` answers. A docs line that is not a page of the docs, and any other result, stay
+ * as they are.
+ */
+export declare function offlineDocs(content: ToolContent): ToolContent;
+/**
+ * What is wrong with a call before it reaches the engine, as the text the agent reads: a tool that
+ * does not exist (or that the filter leaves out), arguments the tool does not take, a required
+ * one missing, a value of the wrong type. Each with the closest real name, the tool's arguments
+ * and its docs. Null when the call can be sent.
+ */
+export declare function callProblem(name: string, args: Record<string, unknown>, filter?: EngineToolFilter): string | null;
+/**
+ * Call an engine tool for an agent and answer its MCP content. A refusal, bad arguments, a name
+ * the filter leaves out and an engine that does not answer come back as an error result
+ * (`isError`), never as a throw: the agent reads why, how to fix it and where to read more.
+ * `actor` names the agent in the journal (default: the client's own actor).
+ */
+export declare function callEngineTool(client: DatanotesClient, name: string, args?: Record<string, unknown>, opts?: EngineToolFilter & {
+    actor?: ActorInfo;
+}): Promise<ToolContent>;
+/** The names of the docs tools. */
+export declare const DOCS_TOOL_NAMES: readonly ["list_docs", "read_docs", "search_docs"];
+/**
+ * The tools that read the Datanotes documentation of this version, shipped in the package
+ * (`list_docs`, `read_docs`, `search_docs`), as MCP tool definitions: fresh copies, kept by the
+ * same filter as engineTools (unknown names throw). They need no engine: callDocsTool answers them.
+ */
+export declare function docsTools(filter?: EngineToolFilter): EngineTool[];
+/** Is this the name of a docs tool (kept by the filter, when one is given)? */
+export declare function isDocsTool(name: string, filter?: EngineToolFilter): boolean;
+/** How long search_docs waits for the engine's ranking of the docs by meaning, before it ranks by words alone. */
+export declare const SEMANTIC_DOCS_TIMEOUT_MS = 10000;
+/** After an engine did not answer (or not in time), how long search_docs ranks by words alone before it asks it again. */
+export declare const SEMANTIC_DOCS_RETRY_MS = 60000;
+/** How search_docs reaches the engine for its ranking by meaning (hybrid search). */
+export interface DocsSearchOptions {
+    /** The engine: with semantic search on, search_docs fuses its ranking by meaning with the ranking by words. */
+    client?: DatanotesClient;
+    /** Who asks, as for engine tools (default: the client's own actor). */
+    actor?: ActorInfo;
+    /** How long to wait for the engine (default SEMANTIC_DOCS_TIMEOUT_MS). */
+    semanticTimeoutMs?: number;
+}
+/**
+ * Answer a docs tool for an agent (MCP content): text, or an error result (`isError`) that says
+ * what is wrong (an unknown page or section, with the closest real ones), how to fix it and where
+ * to read more; never a throw. `docs`: the docs to read (default: the package's own, `openDocs()`).
+ * `client`: the engine, for search_docs' hybrid search (without it, or when the engine has no
+ * ranking by meaning to give, search_docs ranks by words alone).
+ */
+export declare function callDocsTool(name: string, args?: Record<string, unknown>, opts?: EngineToolFilter & DocsSearchOptions & {
+    docs?: DocsLibrary;
+}): Promise<ToolContent>;