@documonster/mcp 0.8.0-canary.sha.09791dab

package/dist/tools/help.d.ts

@@ -0,0 +1,227 @@
+/**
+ * `documonster_help` — on-demand documentation.
+ *
+ * Exists to solve a budget problem. Every enabled tool's `inputSchema` is sent
+ * to the model on every request, so a schema that spelled out the full option
+ * surface of a spreadsheet write would cost thousands of tokens permanently.
+ * Instead, tool schemas stay lean and the detail lives here, fetched only when
+ * the model actually needs it.
+ */
+export interface HelpTopic {
+    readonly summary: string;
+    readonly body: string;
+}
+/**
+ * Topic registry. Add a topic whenever a tool schema has to stay lean but the
+ * detail is genuinely needed to use it correctly.
+ */
+export declare const HELP_TOPICS: {
+    readonly overview: {
+        readonly summary: "What this server can do and the order to do it in.";
+        readonly body: `# documonster MCP server
+
+Reads, writes and converts Excel, Word, PDF, CSV and ZIP documents on the local
+filesystem. All work happens server-side: you send structure and parameters,
+never document bytes.
+
+## Working discipline
+
+1. **Always \`doc_inspect\` first.** It is cheap and tells you the file type,
+   size, sheet list or page count, and CSV dialect. Reading blind wastes
+   context and usually picks the wrong sheet or column.
+2. **Then read a narrow range.** Reading a whole large sheet will exhaust your
+   context. Ask for the range you need and paginate.
+3. **Reference data by path, not by value.** Where a tool accepts a source
+   file, pass the path — do not copy rows through your own output. The server
+   moves the data without spending your tokens on it.
+4. **Reuse returned \`@output/...\` paths.** Plain paths are read-only input.
+   Every write returns a path below the separate output root; pass that exact
+   path to the next read, edit, convert or archive call.
+
+## Constraints
+
+- Plain paths resolve inside the read-only input root. \`@output/...\` paths
+  resolve inside the separate writable output root. Absolute paths and \`..\`
+  that escape either root are rejected.
+- The server may be running with writes disabled. If so, mutating tools are
+  simply absent from your tool list.
+- Results are truncated to a fixed character budget, and truncation is always
+  marked explicitly. If you see a truncation marker, narrow your request.`;
+    };
+    readonly sandbox: {
+        readonly summary: "How paths are resolved and why some are rejected.";
+        readonly body: `# Path rules
+
+- Relative paths resolve against the server's root directory.
+- Absolute paths are permitted only when they land inside that root.
+- Symlinks are followed and then re-checked, so a link pointing outside the
+  root is rejected even though it sits inside it.
+- URLs are rejected by path arguments. Fetching remote documents is a
+  separate, opt-in server capability.
+
+If you get \`[outside_root]\`, the file is genuinely unreachable — do not retry
+with a different spelling of the same path. Tell the user the root needs to be
+widened.`;
+    };
+    readonly roadmap: {
+        readonly summary: "Every tool, grouped by what it does.";
+        readonly body: `# Tools
+
+## Orientation
+- \`documonster_help\` — this documentation.
+- \`doc_inspect\` — identify a file or list a directory. Always first.
+
+## Spreadsheets
+- \`sheet_read\` — read a bounded window.
+- \`sheet_write\` — create an .xlsx from a spec.
+- \`sheet_edit\` — patch an existing .xlsx.
+- \`formula_evaluate\` — evaluate a formula against supplied values.
+
+## Documents
+- \`doc_read\` — read .docx / .pdf / .md / .txt.
+- \`doc_write\` — create a .docx or .pdf from Markdown.
+- \`doc_edit\` — find and replace text in a .docx.
+- \`doc_search\` — find text, or find text by its formatting.
+- \`doc_paginate\` — real page counts and per-heading page numbers.
+- \`doc_review\` — compare two versions, or review tracked changes.
+- \`doc_convert\` — convert between formats.
+- \`pdf_edit\` — watermark, number, stamp, rotate, delete/keep pages, append.
+
+## Forms and templates
+- \`template_inspect\` / \`template_fill\` — Word {{placeholder}} templates.
+- \`form_fill\` — Word form fields and PDF AcroForms.
+
+## Archives
+- \`archive_read\` — list or extract a .zip/.tar.
+- \`archive_write\` — package files into a .zip/.tar.
+
+## Not available — say so plainly rather than improvising
+- reading a password-protected document
+- PDF → Word, or any conversion with a PDF as the source
+- OCR: a scanned PDF page yields no text, and a scanned form has no fields
+- legacy binary .doc / .xls
+- pivot tables and image insertion (the library supports them; no tool does yet)
+
+## Choosing between similar tools
+- A Word file with \`{{placeholders}}\` → \`template_fill\`, not \`doc_edit\`.
+- A Word file with grey form fields → \`form_fill\`, not \`doc_edit\`.
+- Changing ordinary prose → \`doc_edit\`.
+- Producing a PDF → make a .docx or .xlsx first, then \`doc_convert\`.
+  \`pdf_edit\` changes an existing PDF; it does not create content.
+- Two versions of a document → \`doc_review\`, not two \`doc_read\` calls.
+- A chart → a \`charts\` entry in \`sheet_write\`, or an \`add_chart\` op in
+  \`sheet_edit\`. There is no separate chart tool.
+- Test data → \`generate\` in \`sheet_write\`. Never emit thousands of rows yourself.`;
+    };
+    readonly formulas: {
+        readonly summary: "Formula syntax notes and one engine limitation worth knowing.";
+        readonly body: `# Formulas
+
+Both \`sheet_write\` (the \`formulas\` map) and \`formula_evaluate\` accept a
+formula with or without a leading \`=\`; it is normalized for you.
+
+## Supported
+
+Around 450 functions, including \`XLOOKUP\`, \`XMATCH\`, \`SUMIFS\`, \`LET\`,
+dynamic arrays (\`FILTER\`, \`SORT\`, \`UNIQUE\`, \`SEQUENCE\`, \`TEXTSPLIT\`),
+statistical, financial (\`XIRR\`, \`PRICE\`, \`COUPNUM\`), engineering and
+database functions. Dynamic arrays spill into neighbouring cells, and
+\`formula_evaluate\` reports the spilled values.
+
+Higher-order functions work: \`MAP\`, \`REDUCE\`, \`SCAN\`, \`BYROW\`, \`BYCOL\`,
+\`MAKEARRAY\`.
+
+## Known limitation
+
+\`LAMBDA\` must be **bound to a name** before it is called. Excel accepts the
+immediately-invoked form, this engine does not:
+
+- \`LAMBDA(a,b,a+b)(2,3)\` → \`#NAME?\`
+- \`LET(f,LAMBDA(a,b,a+b),f(2,3))\` → \`5\` ✓
+- \`REDUCE(0,{1,2,3},LAMBDA(acc,x,acc+x))\` → \`6\` ✓
+
+## Errors are answers
+
+\`#DIV/0!\`, \`#N/A\`, \`#VALUE!\`, \`#NAME?\`, \`#SPILL!\` come back as results,
+not tool failures — usually you asked precisely in order to find out. \`#NAME?\`
+most often means a misspelled function or an unsupported one.
+
+## Cross-sheet references
+
+In \`sheet_write\`, a formula may reference another sheet in the same spec:
+\`SUM('2026-06'!D:D)\`. Quote a sheet name that contains spaces or digits-only.`;
+    };
+    readonly documents: {
+        readonly summary: "How the Word / PDF / template / form tools fit together.";
+        readonly body: `# Documents
+
+## Reading
+
+\`doc_read\` handles .docx, .pdf, .md and .txt. Word comes back as **Markdown**, so
+headings, lists and tables survive. Use \`outline: true\` on a long Word file to
+get just the headings before deciding what to read.
+
+PDFs are reported page by page with \`## Page N\` markers, so you can cite a page.
+There is **no OCR**: a scanned page reports no extractable text. \`doc_inspect\`
+tells you up front whether a PDF has any text at all.
+
+## Writing
+
+\`doc_write\` takes **Markdown** and produces .docx or .pdf. Write the content as
+Markdown — that is the input language.
+
+## Converting
+
+\`doc_convert\` moves between formats. PDF is terminal: nothing converts *from* a
+PDF, because a faithful PDF→Word conversion does not exist. Lossy conversions
+state their loss in the result.
+
+## Which tool for which .docx
+
+Call \`doc_inspect\` and it will tell you, but the rule is:
+
+- \`{{placeholder}}\` tags → \`template_inspect\` then \`template_fill\`
+- grey form fields → \`form_fill\`
+- tracked changes → \`doc_review\`
+- ordinary prose → \`doc_read\` and \`doc_edit\`
+
+Filling a template beats writing a document from scratch whenever one exists:
+the styling is the template author's and you cannot break it.`;
+    };
+    readonly editing: {
+        readonly summary: "How to change an existing file safely.";
+        readonly body: `# Editing existing files
+
+\`sheet_edit\`, \`doc_edit\`, \`pdf_edit\`, \`form_fill\`, \`doc_review\` and
+\`doc_paginate\` all change a file someone already has.
+
+## Always read before you edit
+
+Call \`sheet_read\` or \`doc_search\` first. The common failure is not a broken
+edit but a **correct edit in the wrong place** — the wrong column, an off-by-one
+row, a phrase that also occurs in a footer. Nothing looks wrong afterwards, which
+is what makes it dangerous.
+
+## Use dryRun on anything that matters
+
+\`sheet_edit\`, \`doc_edit\` and \`pdf_edit\` accept \`dryRun: true\`: it reports
+exactly what would change and writes nothing. Do that whenever the file is the
+user's own work rather than something you produced in this session.
+
+## What the tools guarantee
+
+- **Atomic.** \`sheet_edit\` applies every operation in memory first; if one
+  fails, the file on disk is untouched.
+- **Backed up.** An in-place edit copies the original to \`<name>.bak\`.
+- **Narrow.** Only what you name changes.
+- **No silent no-ops.** Replacing a phrase that does not occur reports that,
+  rather than rewriting the file unchanged.
+
+## Prefer writing a new file
+
+Most of these tools accept \`out\`. An edit that never touches the original
+cannot go wrong.`;
+    };
+};
+export declare const helpTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=help.d.ts.map

package/dist/tools/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/tools/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW;;iBAEpB,OAAO,EAAE,oDAAoD;iBAC7D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EA4BgE;;;iBAItE,OAAO,EAAE,mDAAmD;iBAC5D,IAAI,EAAE;;;;;;;;;;;SAWD;;;iBAIL,OAAO,EAAE,sCAAsC;iBAC/C,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sFA8C4E;;;iBAIlF,OAAO,EAAE,+DAA+D;iBACxE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gFAkCsE;;;iBAI5E,OAAO,EAAE,0DAA0D;iBACnE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8DAiCoD;;;iBAI1D,OAAO,EAAE,wCAAwC;iBACjD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BO;;CAE6B,CAAC;AAe/C,eAAO,MAAM,QAAQ,wCA8BnB,CAAC"}

package/dist/tools/help.js

@@ -0,0 +1,262 @@
+/**
+ * `documonster_help` — on-demand documentation.
+ *
+ * Exists to solve a budget problem. Every enabled tool's `inputSchema` is sent
+ * to the model on every request, so a schema that spelled out the full option
+ * surface of a spreadsheet write would cost thousands of tokens permanently.
+ * Instead, tool schemas stay lean and the detail lives here, fetched only when
+ * the model actually needs it.
+ */
+import { z } from "zod";
+import { textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/**
+ * Topic registry. Add a topic whenever a tool schema has to stay lean but the
+ * detail is genuinely needed to use it correctly.
+ */
+export const HELP_TOPICS = {
+    overview: {
+        summary: "What this server can do and the order to do it in.",
+        body: `# documonster MCP server
+
+Reads, writes and converts Excel, Word, PDF, CSV and ZIP documents on the local
+filesystem. All work happens server-side: you send structure and parameters,
+never document bytes.
+
+## Working discipline
+
+1. **Always \`doc_inspect\` first.** It is cheap and tells you the file type,
+   size, sheet list or page count, and CSV dialect. Reading blind wastes
+   context and usually picks the wrong sheet or column.
+2. **Then read a narrow range.** Reading a whole large sheet will exhaust your
+   context. Ask for the range you need and paginate.
+3. **Reference data by path, not by value.** Where a tool accepts a source
+   file, pass the path — do not copy rows through your own output. The server
+   moves the data without spending your tokens on it.
+4. **Reuse returned \`@output/...\` paths.** Plain paths are read-only input.
+   Every write returns a path below the separate output root; pass that exact
+   path to the next read, edit, convert or archive call.
+
+## Constraints
+
+- Plain paths resolve inside the read-only input root. \`@output/...\` paths
+  resolve inside the separate writable output root. Absolute paths and \`..\`
+  that escape either root are rejected.
+- The server may be running with writes disabled. If so, mutating tools are
+  simply absent from your tool list.
+- Results are truncated to a fixed character budget, and truncation is always
+  marked explicitly. If you see a truncation marker, narrow your request.`
+    },
+    sandbox: {
+        summary: "How paths are resolved and why some are rejected.",
+        body: `# Path rules
+
+- Relative paths resolve against the server's root directory.
+- Absolute paths are permitted only when they land inside that root.
+- Symlinks are followed and then re-checked, so a link pointing outside the
+  root is rejected even though it sits inside it.
+- URLs are rejected by path arguments. Fetching remote documents is a
+  separate, opt-in server capability.
+
+If you get \`[outside_root]\`, the file is genuinely unreachable — do not retry
+with a different spelling of the same path. Tell the user the root needs to be
+widened.`
+    },
+    roadmap: {
+        summary: "Every tool, grouped by what it does.",
+        body: `# Tools
+
+## Orientation
+- \`documonster_help\` — this documentation.
+- \`doc_inspect\` — identify a file or list a directory. Always first.
+
+## Spreadsheets
+- \`sheet_read\` — read a bounded window.
+- \`sheet_write\` — create an .xlsx from a spec.
+- \`sheet_edit\` — patch an existing .xlsx.
+- \`formula_evaluate\` — evaluate a formula against supplied values.
+
+## Documents
+- \`doc_read\` — read .docx / .pdf / .md / .txt.
+- \`doc_write\` — create a .docx or .pdf from Markdown.
+- \`doc_edit\` — find and replace text in a .docx.
+- \`doc_search\` — find text, or find text by its formatting.
+- \`doc_paginate\` — real page counts and per-heading page numbers.
+- \`doc_review\` — compare two versions, or review tracked changes.
+- \`doc_convert\` — convert between formats.
+- \`pdf_edit\` — watermark, number, stamp, rotate, delete/keep pages, append.
+
+## Forms and templates
+- \`template_inspect\` / \`template_fill\` — Word {{placeholder}} templates.
+- \`form_fill\` — Word form fields and PDF AcroForms.
+
+## Archives
+- \`archive_read\` — list or extract a .zip/.tar.
+- \`archive_write\` — package files into a .zip/.tar.
+
+## Not available — say so plainly rather than improvising
+- reading a password-protected document
+- PDF → Word, or any conversion with a PDF as the source
+- OCR: a scanned PDF page yields no text, and a scanned form has no fields
+- legacy binary .doc / .xls
+- pivot tables and image insertion (the library supports them; no tool does yet)
+
+## Choosing between similar tools
+- A Word file with \`{{placeholders}}\` → \`template_fill\`, not \`doc_edit\`.
+- A Word file with grey form fields → \`form_fill\`, not \`doc_edit\`.
+- Changing ordinary prose → \`doc_edit\`.
+- Producing a PDF → make a .docx or .xlsx first, then \`doc_convert\`.
+  \`pdf_edit\` changes an existing PDF; it does not create content.
+- Two versions of a document → \`doc_review\`, not two \`doc_read\` calls.
+- A chart → a \`charts\` entry in \`sheet_write\`, or an \`add_chart\` op in
+  \`sheet_edit\`. There is no separate chart tool.
+- Test data → \`generate\` in \`sheet_write\`. Never emit thousands of rows yourself.`
+    },
+    formulas: {
+        summary: "Formula syntax notes and one engine limitation worth knowing.",
+        body: `# Formulas
+
+Both \`sheet_write\` (the \`formulas\` map) and \`formula_evaluate\` accept a
+formula with or without a leading \`=\`; it is normalized for you.
+
+## Supported
+
+Around 450 functions, including \`XLOOKUP\`, \`XMATCH\`, \`SUMIFS\`, \`LET\`,
+dynamic arrays (\`FILTER\`, \`SORT\`, \`UNIQUE\`, \`SEQUENCE\`, \`TEXTSPLIT\`),
+statistical, financial (\`XIRR\`, \`PRICE\`, \`COUPNUM\`), engineering and
+database functions. Dynamic arrays spill into neighbouring cells, and
+\`formula_evaluate\` reports the spilled values.
+
+Higher-order functions work: \`MAP\`, \`REDUCE\`, \`SCAN\`, \`BYROW\`, \`BYCOL\`,
+\`MAKEARRAY\`.
+
+## Known limitation
+
+\`LAMBDA\` must be **bound to a name** before it is called. Excel accepts the
+immediately-invoked form, this engine does not:
+
+- \`LAMBDA(a,b,a+b)(2,3)\` → \`#NAME?\`
+- \`LET(f,LAMBDA(a,b,a+b),f(2,3))\` → \`5\` ✓
+- \`REDUCE(0,{1,2,3},LAMBDA(acc,x,acc+x))\` → \`6\` ✓
+
+## Errors are answers
+
+\`#DIV/0!\`, \`#N/A\`, \`#VALUE!\`, \`#NAME?\`, \`#SPILL!\` come back as results,
+not tool failures — usually you asked precisely in order to find out. \`#NAME?\`
+most often means a misspelled function or an unsupported one.
+
+## Cross-sheet references
+
+In \`sheet_write\`, a formula may reference another sheet in the same spec:
+\`SUM('2026-06'!D:D)\`. Quote a sheet name that contains spaces or digits-only.`
+    },
+    documents: {
+        summary: "How the Word / PDF / template / form tools fit together.",
+        body: `# Documents
+
+## Reading
+
+\`doc_read\` handles .docx, .pdf, .md and .txt. Word comes back as **Markdown**, so
+headings, lists and tables survive. Use \`outline: true\` on a long Word file to
+get just the headings before deciding what to read.
+
+PDFs are reported page by page with \`## Page N\` markers, so you can cite a page.
+There is **no OCR**: a scanned page reports no extractable text. \`doc_inspect\`
+tells you up front whether a PDF has any text at all.
+
+## Writing
+
+\`doc_write\` takes **Markdown** and produces .docx or .pdf. Write the content as
+Markdown — that is the input language.
+
+## Converting
+
+\`doc_convert\` moves between formats. PDF is terminal: nothing converts *from* a
+PDF, because a faithful PDF→Word conversion does not exist. Lossy conversions
+state their loss in the result.
+
+## Which tool for which .docx
+
+Call \`doc_inspect\` and it will tell you, but the rule is:
+
+- \`{{placeholder}}\` tags → \`template_inspect\` then \`template_fill\`
+- grey form fields → \`form_fill\`
+- tracked changes → \`doc_review\`
+- ordinary prose → \`doc_read\` and \`doc_edit\`
+
+Filling a template beats writing a document from scratch whenever one exists:
+the styling is the template author's and you cannot break it.`
+    },
+    editing: {
+        summary: "How to change an existing file safely.",
+        body: `# Editing existing files
+
+\`sheet_edit\`, \`doc_edit\`, \`pdf_edit\`, \`form_fill\`, \`doc_review\` and
+\`doc_paginate\` all change a file someone already has.
+
+## Always read before you edit
+
+Call \`sheet_read\` or \`doc_search\` first. The common failure is not a broken
+edit but a **correct edit in the wrong place** — the wrong column, an off-by-one
+row, a phrase that also occurs in a footer. Nothing looks wrong afterwards, which
+is what makes it dangerous.
+
+## Use dryRun on anything that matters
+
+\`sheet_edit\`, \`doc_edit\` and \`pdf_edit\` accept \`dryRun: true\`: it reports
+exactly what would change and writes nothing. Do that whenever the file is the
+user's own work rather than something you produced in this session.
+
+## What the tools guarantee
+
+- **Atomic.** \`sheet_edit\` applies every operation in memory first; if one
+  fails, the file on disk is untouched.
+- **Backed up.** An in-place edit copies the original to \`<name>.bak\`.
+- **Narrow.** Only what you name changes.
+- **No silent no-ops.** Replacing a phrase that does not occur reports that,
+  rather than rewriting the file unchanged.
+
+## Prefer writing a new file
+
+Most of these tools accept \`out\`. An edit that never touches the original
+cannot go wrong.`
+    }
+};
+/** Alias kept short for use inside this module. */
+const TOPICS = HELP_TOPICS;
+/**
+ * `z.enum` needs a non-empty tuple. `Object.keys` erases the literal key types,
+ * so one cast is unavoidable; it is sound because `TOPICS` is a non-empty
+ * object literal, and typing it as `TopicName` (rather than `string`) means a
+ * renamed topic breaks the handler lookup at compile time.
+ */
+const TOPIC_NAMES = Object.keys(TOPICS);
+export const helpTool = defineTool({
+    name: "documonster_help",
+    group: "core",
+    title: "documonster help",
+    description: "Read documentation for this server: usage conventions, path rules, and detailed parameter guidance that is deliberately kept out of tool schemas. Call with no topic to list available topics.",
+    inputSchema: {
+        topic: z
+            .enum(TOPIC_NAMES)
+            .optional()
+            .describe("Topic to read. Omit to list all topics with one-line summaries.")
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    mutates: false,
+    handler: async (args, context) => {
+        const { topic } = args;
+        if (topic === undefined) {
+            const lines = ["# Available topics", ""];
+            for (const [name, entry] of Object.entries(TOPICS)) {
+                lines.push(`- \`${name}\` — ${entry.summary}`);
+            }
+            lines.push("", 'Read one with `documonster_help({ topic: "overview" })`.');
+            return textResult(context.config, lines.join("\n"));
+        }
+        // `z.enum` already rejected unknown topics, so this lookup cannot miss.
+        const entry = TOPICS[topic];
+        return textResult(context.config, entry?.body ?? "");
+    }
+});
+//# sourceMappingURL=help.js.map

package/dist/tools/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/tools/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAOxC;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE;QACR,OAAO,EAAE,oDAAoD;QAC7D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;0EA4BgE;KACvE;IAED,OAAO,EAAE;QACP,OAAO,EAAE,mDAAmD;QAC5D,IAAI,EAAE;;;;;;;;;;;SAWD;KACN;IAED,OAAO,EAAE;QACP,OAAO,EAAE,sCAAsC;QAC/C,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sFA8C4E;KACnF;IAED,QAAQ,EAAE;QACR,OAAO,EAAE,+DAA+D;QACxE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gFAkCsE;KAC7E;IAED,SAAS,EAAE;QACT,OAAO,EAAE,0DAA0D;QACnE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8DAiCoD;KAC3D;IAED,OAAO,EAAE;QACP,OAAO,EAAE,wCAAwC;QACjD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BO;KACd;CAC2C,CAAC;AAE/C,mDAAmD;AACnD,MAAM,MAAM,GAAG,WAAW,CAAC;AAI3B;;;;;GAKG;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAgC,CAAC;AAEvE,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,CAAC;IACjC,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,kBAAkB;IACzB,WAAW,EACT,gMAAgM;IAClM,WAAW,EAAE;QACX,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,WAAW,CAAC;aACjB,QAAQ,EAAE;aACV,QAAQ,CAAC,iEAAiE,CAAC;KAC/E;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACzD,OAAO,EAAE,KAAK;IACd,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAC/B,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAEvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;YACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnD,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,QAAQ,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,0DAA0D,CAAC,CAAC;YAC3E,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtD,CAAC;QAED,wEAAwE;QACxE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tool registry.
+ *
+ * The single list of every tool the server knows about. Selection is pure data
+ * filtering, which keeps `--enable` / `--readonly` behaviour testable without
+ * starting a transport.
+ */
+import type { ServerConfig } from "../config.js";
+import type { AnyToolDefinition } from "./types.js";
+/**
+ * All tools, in the order they are registered.
+ *
+ * Keep this list short. Every enabled tool's name, description and JSON Schema
+ * is sent to the model on every single request, and the probability of the
+ * model picking the wrong tool rises with the count. A capability that only
+ * varies by a parameter belongs as a parameter, not as another tool.
+ */
+export declare const ALL_TOOLS: readonly AnyToolDefinition[];
+/**
+ * The tools a given configuration exposes.
+ *
+ * Always-mutating tools are removed under `--readonly`. Conditionally-writing
+ * tools remain visible so their read-only mode (list fields, compare versions,
+ * compute pages) still works; their write branch enforces `assertWritable`.
+ *
+ * @param tools - Defaults to {@link ALL_TOOLS}. Overridable so the filter can
+ *   be tested against fixtures covering groups that no shipped tool uses yet —
+ *   otherwise the only reachable path would be "nothing was filtered", which
+ *   passes however broken the predicate is.
+ */
+export declare function selectTools(config: ServerConfig, tools?: readonly AnyToolDefinition[]): readonly AnyToolDefinition[];
+export type { AnyToolDefinition, ToolContext, ToolDefinition } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkBjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,iBAAiB,EAoBjD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,SAAS,iBAAiB,EAAc,GAC9C,SAAS,iBAAiB,EAAE,CAW9B;AAED,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,78 @@
+/**
+ * Tool registry.
+ *
+ * The single list of every tool the server knows about. Selection is pure data
+ * filtering, which keeps `--enable` / `--readonly` behaviour testable without
+ * starting a transport.
+ */
+import { archiveReadTool } from "./archive-read.js";
+import { archiveWriteTool } from "./archive-write.js";
+import { docConvertTool } from "./doc-convert.js";
+import { docPaginateTool } from "./doc-paginate.js";
+import { docReadTool } from "./doc-read.js";
+import { docReviewTool } from "./doc-review.js";
+import { docEditTool, docSearchTool } from "./doc-search.js";
+import { docWriteTool } from "./doc-write.js";
+import { formFillTool } from "./form-fill.js";
+import { formulaEvaluateTool } from "./formula-evaluate.js";
+import { helpTool } from "./help.js";
+import { inspectTool } from "./inspect.js";
+import { pdfEditTool } from "./pdf-edit.js";
+import { sheetEditTool } from "./sheet-edit.js";
+import { sheetReadTool } from "./sheet-read.js";
+import { sheetWriteTool } from "./sheet-write.js";
+import { templateFillTool, templateInspectTool } from "./template.js";
+/**
+ * All tools, in the order they are registered.
+ *
+ * Keep this list short. Every enabled tool's name, description and JSON Schema
+ * is sent to the model on every single request, and the probability of the
+ * model picking the wrong tool rises with the count. A capability that only
+ * varies by a parameter belongs as a parameter, not as another tool.
+ */
+export const ALL_TOOLS = [
+    helpTool,
+    inspectTool,
+    sheetReadTool,
+    sheetWriteTool,
+    sheetEditTool,
+    formulaEvaluateTool,
+    docReadTool,
+    docWriteTool,
+    docConvertTool,
+    docSearchTool,
+    docEditTool,
+    docPaginateTool,
+    docReviewTool,
+    pdfEditTool,
+    templateInspectTool,
+    templateFillTool,
+    formFillTool,
+    archiveReadTool,
+    archiveWriteTool
+];
+/**
+ * The tools a given configuration exposes.
+ *
+ * Always-mutating tools are removed under `--readonly`. Conditionally-writing
+ * tools remain visible so their read-only mode (list fields, compare versions,
+ * compute pages) still works; their write branch enforces `assertWritable`.
+ *
+ * @param tools - Defaults to {@link ALL_TOOLS}. Overridable so the filter can
+ *   be tested against fixtures covering groups that no shipped tool uses yet —
+ *   otherwise the only reachable path would be "nothing was filtered", which
+ *   passes however broken the predicate is.
+ */
+export function selectTools(config, tools = ALL_TOOLS) {
+    return tools.filter(tool => {
+        const groups = Array.isArray(tool.group) ? tool.group : [tool.group];
+        if (!groups.some(group => config.groups.has(group))) {
+            return false;
+        }
+        if (tool.mutates && config.readonly) {
+            return false;
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGtE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAiC;IACrD,QAAQ;IACR,WAAW;IACX,aAAa;IACb,cAAc;IACd,aAAa;IACb,mBAAmB;IACnB,WAAW;IACX,YAAY;IACZ,cAAc;IACd,aAAa;IACb,WAAW;IACX,eAAe;IACf,aAAa;IACb,WAAW;IACX,mBAAmB;IACnB,gBAAgB;IAChB,YAAY;IACZ,eAAe;IACf,gBAAgB;CACjB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,MAAoB,EACpB,KAAK,GAAiC,SAAS;IAE/C,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;QACzB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACpD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/inspect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `doc_inspect` — the cheap first call.
+ *
+ * Every other tool is expensive in context: reading a sheet or a document body
+ * spends thousands of tokens. This one spends a few dozen and answers the
+ * questions that stop the model guessing — what kind of file is this, how big,
+ * and for CSV, which delimiter and line ending is it actually using.
+ *
+ * The CSV dialect fields are why this tool imports from the core package: a
+ * model has no way to know that a "csv" is semicolon-separated with a BOM,
+ * and getting it wrong silently produces a one-column table.
+ */
+export declare const inspectTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/tools/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/tools/inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwCH,eAAO,MAAM,WAAW,wCAoCtB,CAAC"}