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

package/dist/tools/document.js

@@ -0,0 +1,157 @@
+/**
+ * Shared document helpers for the Word / PDF tools.
+ *
+ * Concentrates three things the document tools must not each re-derive: which
+ * format a path denotes, the awkward corners of the underlying API that were
+ * verified empirically, and paginating long text so a tool result never blows
+ * the caller's context.
+ */
+import path from "node:path";
+import { toolError } from "../errors.js";
+const EXTENSION_FORMATS = {
+    ".docx": "docx",
+    ".docm": "docx",
+    ".pdf": "pdf",
+    ".md": "md",
+    ".markdown": "md",
+    ".html": "html",
+    ".htm": "html",
+    ".txt": "txt",
+    ".xlsx": "xlsx",
+    ".xlsm": "xlsx",
+    ".csv": "csv",
+    ".odt": "odt"
+};
+/** Format implied by a path's extension, or `undefined` when unrecognised. */
+function formatFromPath(filePath) {
+    return EXTENSION_FORMATS[path.extname(filePath).toLowerCase()];
+}
+/**
+ * Format implied by a path, or a tool error naming what is supported.
+ *
+ * Listing the accepted extensions in the error matters: a model that guessed
+ * `.doc` can correct itself in one step instead of retrying variations.
+ */
+export function requireFormat(filePath, field) {
+    const format = formatFromPath(filePath);
+    if (format === undefined) {
+        throw toolError.invalidInput(`cannot tell the format of ${field} from its extension: ${JSON.stringify(filePath)}`, `Use one of: ${Object.keys(EXTENSION_FORMATS).join(", ")}`);
+    }
+    return format;
+}
+/**
+ * Reject macro-enabled extensions for newly generated output.
+ *
+ * The writer produces ordinary DOCX/XLSX content. Naming that package `.docm`
+ * or `.xlsm` does not make it macro-enabled; worse, rewriting an existing macro
+ * file through a path that cannot prove VBA preservation risks silent macro
+ * loss. Read operations may still inspect such files.
+ */
+export function assertNonMacroOutput(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === ".docm" || extension === ".xlsm") {
+        throw toolError.unsupported(`cannot write ${extension} output safely`, `Use ${extension === ".docm" ? ".docx" : ".xlsx"}. A normal OOXML package with a macro-enabled extension is invalid, and this tool does not create or verify a VBA project.`);
+    }
+}
+/**
+ * Take a line-bounded window of text.
+ *
+ * Line-based rather than character-based so the cursor a caller passes back is
+ * stable and meaningful: "continue from line 240" survives, whereas a character
+ * offset into re-extracted text does not.
+ */
+export function takeLines(text, startLine, maxLines) {
+    const lines = text.split("\n");
+    const from = Math.max(1, startLine);
+    const to = Math.min(lines.length, from + maxLines - 1);
+    return {
+        text: lines.slice(from - 1, to).join("\n"),
+        startLine: from,
+        endLine: to,
+        totalLines: lines.length,
+        truncated: to < lines.length
+    };
+}
+/**
+ * Render the standard "here is what I left out" footer.
+ *
+ * Always emitted when content was cut, because a model given a silent partial
+ * read will reason over it as though it were complete.
+ */
+export function continuationNote(window, cursorField = "startLine") {
+    if (!window.truncated) {
+        return [];
+    }
+    return [
+        `- **${window.totalLines - window.endLine} more line(s) not shown.** Continue with \`${cursorField}: ${window.endLine + 1}\`.`
+    ];
+}
+/**
+ * Normalize a page selection into 1-based page numbers.
+ *
+ * Accepts `[1,2,5]` or `"1-3,7"`, because a model reaches for both.
+ */
+export function parsePages(pages) {
+    if (pages === undefined) {
+        return undefined;
+    }
+    if (typeof pages !== "string") {
+        if (pages.length > MAX_SELECTABLE_PAGES) {
+            throw toolError.invalidInput(`page selection lists ${pages.length} pages, over the ${MAX_SELECTABLE_PAGES} limit`);
+        }
+        return pages.map(page => assertPage(page));
+    }
+    const out = [];
+    for (const part of pages.split(",")) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        const dash = trimmed.indexOf("-");
+        if (dash > 0) {
+            const from = assertPage(Number(trimmed.slice(0, dash)));
+            const to = assertPage(Number(trimmed.slice(dash + 1)));
+            if (to < from) {
+                throw toolError.invalidInput(`page range ${JSON.stringify(trimmed)} runs backwards`);
+            }
+            // Bound the span before expanding it: "1-1000000000" would otherwise
+            // allocate a billion entries before any page-count check could reject it.
+            if (to - from + 1 > MAX_SELECTABLE_PAGES ||
+                out.length + (to - from + 1) > MAX_SELECTABLE_PAGES) {
+                throw toolError.invalidInput(`page selection ${JSON.stringify(trimmed)} covers more than ${MAX_SELECTABLE_PAGES} pages`, "Name a narrower range; no document here has that many pages.");
+            }
+            for (let page = from; page <= to; page += 1) {
+                out.push(page);
+            }
+        }
+        else {
+            out.push(assertPage(Number(trimmed)));
+        }
+    }
+    if (out.length === 0) {
+        throw toolError.invalidInput(`could not parse ${JSON.stringify(pages)} as pages`, 'Use a list like [1,2,5] or a string like "1-3,7".');
+    }
+    return out;
+}
+function assertPage(value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw toolError.invalidInput(`${value} is not a 1-based page number`);
+    }
+    return value;
+}
+/**
+ * Whether a PDF can receive a genuine incremental update.
+ *
+ * `PdfEditor.saveIncremental()` silently falls back to a full rebuild for
+ * xref-stream files (PDF 1.5+ without a `trailer` keyword). A full rebuild
+ * renumbers objects and invalidates any existing signature, so a tool must not
+ * claim "signature preserved" without checking — and callers deserve to know
+ * when structure may be reorganised.
+ */
+export function supportsIncrementalUpdate(bytes) {
+    const tail = bytes.subarray(Math.max(0, bytes.length - 1024));
+    return new TextDecoder().decode(tail).includes("trailer");
+}
+/** Cap on how many pages a selector may name, before it is expanded. */
+export const MAX_SELECTABLE_PAGES = 10_000;
+//# sourceMappingURL=document.js.map

package/dist/tools/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/tools/document.ts"],"names":[],"mappings":"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"}

package/dist/tools/form-fill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `form_fill` — list and fill form fields in Word documents and PDFs.
+ *
+ * Another well-shaped task, for the same reason as templates: the document
+ * declares what it needs, so listing the fields *is* the schema and the model
+ * supplies only values. "Fill in this form" is also one of the most concrete
+ * requests a user can make, which makes it hard to get subtly wrong.
+ *
+ * One implementation detail is load-bearing. A PDF must be saved with
+ * `saveIncremental()`, not `save()`: the full rebuild path drops AcroForm
+ * values, so `save()` produces a document that looks fine and contains none of
+ * the answers. Verified empirically — do not "simplify" this.
+ *
+ * The corollary is that a PDF whose format cannot take an incremental update
+ * (a cross-reference stream file) cannot be filled correctly at all here. Such a
+ * file is refused rather than written, because the failure is invisible: the
+ * output opens, looks like the right form, and is blank.
+ */
+export declare const formFillTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=form-fill.d.ts.map

package/dist/tools/form-fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-fill.d.ts","sourceRoot":"","sources":["../../src/tools/form-fill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmCH,eAAO,MAAM,YAAY,wCA0FvB,CAAC"}

package/dist/tools/form-fill.js

@@ -0,0 +1,270 @@
+/**
+ * `form_fill` — list and fill form fields in Word documents and PDFs.
+ *
+ * Another well-shaped task, for the same reason as templates: the document
+ * declares what it needs, so listing the fields *is* the schema and the model
+ * supplies only values. "Fill in this form" is also one of the most concrete
+ * requests a user can make, which makes it hard to get subtly wrong.
+ *
+ * One implementation detail is load-bearing. A PDF must be saved with
+ * `saveIncremental()`, not `save()`: the full rebuild path drops AcroForm
+ * values, so `save()` produces a document that looks fine and contains none of
+ * the answers. Verified empirically — do not "simplify" this.
+ *
+ * The corollary is that a PDF whose format cannot take an incremental update
+ * (a cross-reference stream file) cannot be filled correctly at all here. Such a
+ * file is refused rather than written, because the failure is invisible: the
+ * output opens, looks like the right form, and is blank.
+ */
+import { readFile } from "node:fs/promises";
+import { Pdf } from "documonster/pdf";
+import { Io, Query } from "documonster/word";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, resolveEditTarget, resolveInRoot } from "../sandbox.js";
+import { requireFormat, supportsIncrementalUpdate } from "./document.js";
+import { assertReadableSize, assertUnchanged, backupOnce, describeBackup, exists, fingerprint, isSameFile, replaceAtomically, writeFileAtomic } from "./fs-helpers.js";
+import { textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Fields listed in one call. */
+const MAX_FIELDS = 200;
+export const formFillTool = defineTool({
+    name: "form_fill",
+    group: "forms",
+    title: "List or fill form fields",
+    description: "List the fillable fields in a .docx or .pdf form, or fill them from supplied values. Call it without `values` first: the field list tells you exactly what names and types the form expects, so there is nothing to guess. Works with Word legacy form fields and PDF AcroForms.",
+    inputSchema: {
+        path: z.string().min(1).describe("Form path (.docx or .pdf), relative to the server root."),
+        values: z
+            .record(z.string(), z.union([z.string(), z.boolean(), z.number()]))
+            .optional()
+            .describe('Values keyed by field name, e.g. { "fullName": "Jane Doe", "agree": true }. Omit to list the fields without changing anything.'),
+        out: z
+            .string()
+            .optional()
+            .describe("Write the filled form below @output/. Required for input files unless --allow-in-place is enabled."),
+        backup: z
+            .boolean()
+            .optional()
+            .describe("When filling in place, copy the original to <name>.bak first. Defaults to true."),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Replace an existing `out` file. Defaults to false. Does not apply in place.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+    },
+    // Listing is read-only; only filling writes. Declared non-mutating so the
+    // tool stays visible under --readonly — a read-only server should still be
+    // able to report what fields a form has — and the write path calls
+    // assertWritable itself.
+    mutates: false,
+    handler: async (args, context) => {
+        const { config } = context;
+        const resolved = await resolveInRoot(config, args.path, { mustExist: true });
+        await assertReadableSize(config, resolved, args.path);
+        const inputVersion = await fingerprint(resolved);
+        const format = requireFormat(args.path, "path");
+        if (format !== "docx" && format !== "pdf") {
+            throw toolError.unsupported(`form_fill works with .docx and .pdf, not .${format}`, "For spreadsheets use sheet_edit; for Word templates with {{placeholders}} use template_fill.");
+        }
+        if (args.values === undefined) {
+            return textResult(config, format === "docx"
+                ? await listWordFields(resolved, args.path)
+                : await listPdfFields(resolved, args.path));
+        }
+        assertWritable(config);
+        if (args.out !== undefined && requireFormat(args.out, "out") !== format) {
+            throw toolError.invalidInput(`out must have the same format as the source (.${format})`, "form_fill fills a form; use doc_convert afterwards to change format.");
+        }
+        await assertUnchanged(resolved, inputVersion);
+        const writeTarget = await resolveEditTarget(config, args.path, args.out);
+        const inPlace = isSameFile(writeTarget.path, resolved);
+        if (!inPlace && args.overwrite !== true && (await exists(writeTarget.path))) {
+            throw toolError.invalidInput(`${writeTarget.display} already exists`, "Pass overwrite: true to replace it, or choose a different output.");
+        }
+        const write = { target: writeTarget, inPlace, takeBackup: inPlace && (args.backup ?? true) };
+        return textResult(config, format === "docx"
+            ? await fillWordFields(resolved, write, args)
+            : await fillPdfFields(resolved, write, args));
+    }
+});
+async function listWordFields(resolved, displayPath) {
+    const doc = await readWord(resolved, displayPath);
+    const fields = Query.extractFormFields(doc);
+    if (fields.length === 0) {
+        return [
+            `# ${displayPath}`,
+            "",
+            "This document has no legacy form fields.",
+            "",
+            "If it uses `{{placeholder}}` syntax instead, use template_inspect and template_fill. If it is an ordinary document, use doc_edit to change text."
+        ].join("\n");
+    }
+    return [
+        `# ${displayPath} — ${fields.length} form field(s)`,
+        "",
+        "| field | type | current value | choices |",
+        "| --- | --- | --- | --- |",
+        ...fields
+            .slice(0, MAX_FIELDS)
+            .map(field => `| \`${field.name}\` | ${field.type} | ${JSON.stringify(field.value)} | ${field.entries === undefined ? "—" : field.entries.join(", ")} |`),
+        ...(fields.length > MAX_FIELDS ? ["", `[${fields.length - MAX_FIELDS} more not listed]`] : []),
+        "",
+        "## Values shape",
+        "",
+        "```json",
+        JSON.stringify(Object.fromEntries(fields.slice(0, 40).map(field => [field.name, field.type === "checkBox" ? true : "…"])), null, 2),
+        "```",
+        "",
+        "Pass that as `values` to fill the form."
+    ].join("\n");
+}
+async function fillWordFields(resolved, write, args) {
+    const doc = await readWord(resolved, args.path);
+    const before = Query.extractFormFields(doc);
+    if (before.length === 0) {
+        throw toolError.invalidInput(`${args.path} has no form fields to fill`, "Call form_fill without `values` to confirm, or use template_fill if the document uses {{placeholders}}.");
+    }
+    const known = new Set(before.map(field => field.name));
+    const supplied = Object.entries(args.values ?? {});
+    const unknown = supplied.filter(([name]) => !known.has(name)).map(([name]) => name);
+    if (unknown.length > 0) {
+        // Naming the real fields turns a wrong guess into a one-step correction.
+        throw toolError.invalidInput(`no such field(s): ${unknown.map(name => JSON.stringify(name)).join(", ")}`, `The form's fields are: ${[...known].map(name => JSON.stringify(name)).join(", ")}. Nothing was written.`);
+    }
+    const filled = Query.fillFormFields(doc, new Map(supplied.map(([name, value]) => [name, value])));
+    const backupPath = write.takeBackup ? await backupOnce(write.target) : undefined;
+    await replaceAtomically(write.target.path, temporary => Io.writeFile(filled, temporary));
+    const after = Query.extractFormFields(filled);
+    const untouched = after.filter(field => !known.has(field.name) || !(field.name in (args.values ?? {})));
+    return [
+        `Filled **${supplied.length}** of ${before.length} field(s) in ${args.path}.`,
+        `- written to ${write.target.display}${write.inPlace ? " (in place)" : ""}`,
+        ...describeBackup(write.target.display, backupPath),
+        "",
+        "| field | value now |",
+        "| --- | --- |",
+        ...after
+            .slice(0, MAX_FIELDS)
+            .map(field => `| \`${field.name}\` | ${JSON.stringify(field.value)} |`),
+        ...(untouched.length > 0
+            ? ["", `${untouched.length} field(s) were left at their existing value.`]
+            : []),
+        "",
+        "Read it back with form_fill (no `values`) to verify."
+    ].join("\n");
+}
+async function listPdfFields(resolved, displayPath) {
+    const bytes = await readFile(resolved);
+    const result = await Pdf.read(new Uint8Array(bytes), {
+        extractFormFields: true,
+        extractText: false,
+        extractImages: false
+    }).catch((cause) => {
+        throw toolError.unsupported(`could not read ${displayPath} as a PDF`, undefined, { cause });
+    });
+    const fields = result.formFields ?? [];
+    if (fields.length === 0) {
+        return [
+            `# ${displayPath}`,
+            "",
+            "This PDF has no AcroForm fields — it is not a fillable form.",
+            "",
+            "A scanned or flattened form has no fields to fill; there is no OCR here, so say so rather than guessing where the blanks are."
+        ].join("\n");
+    }
+    return [
+        `# ${displayPath} — ${fields.length} form field(s)`,
+        "",
+        "| field | type | current value | choices | required |",
+        "| --- | --- | --- | --- | --- |",
+        ...fields
+            .slice(0, MAX_FIELDS)
+            .map(field => `| \`${field.name}\` | ${field.type} | ${JSON.stringify(field.value)} | ${field.options !== undefined && field.options.length > 0 ? field.options.join(", ") : "—"} | ${field.required ? "yes" : "no"} |`),
+        ...(fields.length > MAX_FIELDS ? ["", `[${fields.length - MAX_FIELDS} more not listed]`] : []),
+        "",
+        "Checkbox fields take their export value (often `Yes`) to tick and `Off` to clear.",
+        "",
+        "Pass `values` keyed by these names to fill the form."
+    ].join("\n");
+}
+async function fillPdfFields(resolved, write, args) {
+    const bytes = new Uint8Array(await readFile(resolved));
+    // Refuse rather than write a blank form: filling depends on the incremental
+    // save path, and this format cannot take one.
+    if (!supportsIncrementalUpdate(bytes)) {
+        throw toolError.unsupported(`${args.path} uses a cross-reference stream, which cannot be filled without discarding the values`, "Saving such a file rebuilds it, and the rebuild drops AcroForm values — the result would open as an empty form. Nothing was written. Ask the user for a form saved in the classic format, or fill it in a PDF viewer.");
+    }
+    // Editor.load is synchronous.
+    let editor;
+    try {
+        editor = Pdf.Editor.load(bytes);
+    }
+    catch (cause) {
+        throw toolError.unsupported(`could not open ${args.path} for editing`, "A password-protected PDF cannot be filled here.", { cause });
+    }
+    const existing = editor.getFormFields();
+    if (existing.length === 0) {
+        throw toolError.invalidInput(`${args.path} has no AcroForm fields to fill`, "Call form_fill without `values` to confirm. A flattened or scanned form has no fields.");
+    }
+    const known = new Set(existing.map(field => field.name));
+    const supplied = Object.entries(args.values ?? {});
+    const unknown = supplied.filter(([name]) => !known.has(name)).map(([name]) => name);
+    if (unknown.length > 0) {
+        throw toolError.invalidInput(`no such field(s): ${unknown.map(name => JSON.stringify(name)).join(", ")}`, `The form's fields are: ${[...known].map(name => JSON.stringify(name)).join(", ")}. Nothing was written.`);
+    }
+    editor.setFormFields(Object.fromEntries(supplied.map(([name, value]) => [name, stringifyPdfValue(value)])));
+    // saveIncremental, never save: the full rebuild drops AcroForm values, so
+    // save() would write a form that still contains none of the answers.
+    const out = await editor.saveIncremental();
+    // Verify in memory before either backing up or writing. A silently unfilled
+    // form is the failure this path exists to avoid, and a failed verification
+    // must have no filesystem side effects.
+    const verified = await Pdf.read(new Uint8Array(out), {
+        extractFormFields: true,
+        extractText: false,
+        extractImages: false
+    });
+    const after = verified.formFields ?? [];
+    const missed = supplied.filter(([name, value]) => {
+        const field = after.find(candidate => candidate.name === name);
+        return field === undefined || field.value !== stringifyPdfValue(value);
+    });
+    if (missed.length > 0) {
+        throw toolError.unsupported(`the saved PDF did not retain ${missed.length} supplied field value(s): ${missed.map(([name]) => JSON.stringify(name)).join(", ")}`, "Nothing was written. For a checkbox, supply true/false or its export value.");
+    }
+    const backupPath = write.takeBackup ? await backupOnce(write.target) : undefined;
+    await writeFileAtomic(write.target.path, out);
+    return [
+        `Filled **${supplied.length - missed.length}** of ${supplied.length} supplied field(s) in ${args.path}.`,
+        `- written to ${write.target.display}${write.inPlace ? " (in place)" : ""}`,
+        ...describeBackup(write.target.display, backupPath),
+        "- saved as an incremental update, so original signature bytes are preserved; a certified signature may still report the form as modified if its DocMDP permissions forbid filling fields",
+        "",
+        "| field | value now |",
+        "| --- | --- |",
+        ...after
+            .slice(0, MAX_FIELDS)
+            .map(field => `| \`${field.name}\` | ${JSON.stringify(field.value)} |`),
+        "",
+        "Verified by re-reading the saved file."
+    ].join("\n");
+}
+/** PDF field values are strings; booleans map to a checkbox's on/off states. */
+function stringifyPdfValue(value) {
+    if (typeof value === "boolean") {
+        return value ? "Yes" : "Off";
+    }
+    return String(value);
+}
+async function readWord(resolved, displayPath) {
+    return await Io.readFile(resolved).catch((cause) => {
+        throw toolError.unsupported(`could not read ${displayPath} as a Word document`, "Run doc_inspect to check the real file type.", { cause });
+    });
+}
+//# sourceMappingURL=form-fill.js.map

package/dist/tools/form-fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-fill.js","sourceRoot":"","sources":["../../src/tools/form-fill.ts"],"names":[],"mappings":"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"}

package/dist/tools/formula-evaluate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `formula_evaluate` — run a spreadsheet formula against a supplied cell context.
+ *
+ * The most distinctive tool here. A model asked "is this XLOOKUP right?" can
+ * only answer from memory of Excel semantics, and it is often confidently wrong
+ * about match modes, error propagation and date serials. This turns the
+ * question into an execution: build a throwaway workbook, populate the context,
+ * evaluate with the real engine (450-odd functions, spill support), read back
+ * what Excel would actually show.
+ *
+ * Touches no files, so it is safe under --readonly.
+ */
+export declare const formulaEvaluateTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=formula-evaluate.d.ts.map

package/dist/tools/formula-evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formula-evaluate.d.ts","sourceRoot":"","sources":["../../src/tools/formula-evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH,eAAO,MAAM,mBAAmB,wCAiH9B,CAAC"}