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

package/dist/tools/doc-paginate.js

@@ -0,0 +1,153 @@
+/**
+ * `doc_paginate` — compute a Word document's real page layout.
+ *
+ * The capability nothing else here can substitute for. "How many pages is this?"
+ * and "which page is that heading on?" normally require Microsoft Word: the
+ * answer depends on line breaking, font metrics, widow/orphan control and table
+ * cell heights. This runs the layout engine and answers without Office
+ * installed, and without a rasteriser.
+ *
+ * It also updates computed field values — PAGE, NUMPAGES, PAGEREF, TOC entries —
+ * which otherwise only refresh when a human presses F9 in Word.
+ */
+import { Io, Layout, Query } from "documonster/word";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, resolveEditTarget, resolveInRoot } from "../sandbox.js";
+import { assertReadableSize, assertUnchanged, backupOnce, describeBackup, fingerprint, isSameFile, replaceAtomically, writeWithPolicy } from "./fs-helpers.js";
+import { textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Headings listed in one call. */
+const MAX_HEADINGS = 150;
+export const docPaginateTool = defineTool({
+    name: "doc_paginate",
+    group: "word",
+    title: "Compute a document's page layout",
+    description: "Compute how many pages a .docx really is, and which page each heading falls on, by running the layout engine — no Word installation needed. Optionally update computed fields (PAGE, NUMPAGES, PAGEREF) and regenerate the table of contents with correct page numbers, which otherwise only refresh when someone opens the document in Word.",
+    inputSchema: {
+        path: z.string().min(1).describe("Document path (.docx), relative to the server root."),
+        updateFields: z
+            .boolean()
+            .optional()
+            .describe("Recompute field values and the table of contents, then save. Requires a writable server. Defaults to false — pagination alone changes nothing on disk."),
+        out: z
+            .string()
+            .optional()
+            .describe("With updateFields, write below @output/. Required for input files unless --allow-in-place is enabled."),
+        overwrite: z.boolean().optional().describe("Replace an existing `out` file. Defaults to false.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+    },
+    // Pagination alone writes nothing; only `updateFields` does. Declared
+    // non-mutating so page counts stay available on a read-only server, with
+    // assertWritable guarding the write path.
+    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 doc = await Io.readFile(resolved).catch((cause) => {
+            throw toolError.unsupported(`could not read ${args.path} as a Word document`, "Run doc_inspect to check the real file type.", { cause });
+        });
+        // Page size always comes from the document's own section properties:
+        // Layout.document takes no geometry override, and exposing a parameter the
+        // engine ignores would be worse than not having one.
+        const layout = Layout.document(doc);
+        const lines = [
+            `# ${args.path} — page layout`,
+            "",
+            `- **pages: ${layout.pageCount}**`,
+            `- sections: ${layout.sectionPageCounts.length} (${layout.sectionPageCounts.join(", ")} page(s) each)`,
+            `- paragraphs: ${Query.paragraphCount(doc)}`,
+            `- words: ${Query.countWords(doc)}`,
+            "- page size: taken from the document's own section setup"
+        ];
+        // Walk the body directly rather than using Query.getHeadings: that reports a
+        // walk-order ordinal which counts paragraphs nested in tables, whereas
+        // contentPages is indexed by body position. Mixing the two misreports pages
+        // for any document containing a table.
+        const headings = collectHeadings(doc, layout.contentPages);
+        if (headings.length > 0) {
+            lines.push("", "## Headings by page", "", "| page | level | heading |", "| --- | --- | --- |", ...headings
+                .slice(0, MAX_HEADINGS)
+                .map(heading => `| ${heading.page} | H${heading.level} | ${heading.text} |`));
+            if (headings.length > MAX_HEADINGS) {
+                lines.push("", `[${headings.length - MAX_HEADINGS} more not listed]`);
+            }
+        }
+        else {
+            lines.push("", "This document has no headings, so there is no per-section page map.");
+        }
+        if (layout.bookmarkPages.size > 0) {
+            lines.push("", `Bookmarks: ${[...layout.bookmarkPages.entries()]
+                .slice(0, 20)
+                .map(([name, page]) => `\`${name}\` → page ${page}`)
+                .join(", ")}`);
+        }
+        if (args.updateFields !== true) {
+            lines.push("", "Nothing was written. Pass `updateFields: true` to recompute PAGE / NUMPAGES / PAGEREF fields and the table of contents.");
+            return textResult(config, lines.join("\n"));
+        }
+        assertWritable(config);
+        const withFields = Io.updateFields(doc);
+        const withToc = Io.updateTableOfContents(withFields);
+        await assertUnchanged(resolved, inputVersion);
+        const writeTarget = await resolveEditTarget(config, args.path, args.out);
+        const inPlace = isSameFile(writeTarget.path, resolved);
+        const backupPath = inPlace ? await backupOnce(writeTarget) : undefined;
+        if (inPlace) {
+            await replaceAtomically(writeTarget.path, temporary => Io.writeFile(withToc, temporary));
+        }
+        else {
+            await writeWithPolicy(writeTarget.path, args.overwrite === true, temporary => Io.writeFile(withToc, temporary));
+        }
+        lines.push("", `Fields and table of contents recomputed and written to ${writeTarget.display}${inPlace ? " (in place)" : ""}.`, ...describeBackup(writeTarget.display, backupPath), "", "Read it back with doc_read to verify before reporting success to the user.");
+        return textResult(config, lines.join("\n"));
+    }
+});
+/** Headings in body order, each with the page its paragraph starts on. */
+function collectHeadings(doc, contentPages) {
+    const found = [];
+    doc.body.forEach((item, index) => {
+        if (item.type !== "paragraph") {
+            return;
+        }
+        const style = item.properties?.style;
+        if (typeof style !== "string") {
+            return;
+        }
+        const match = /^Heading(\d)$/i.exec(style);
+        if (match === null) {
+            return;
+        }
+        const text = paragraphText(item);
+        if (text.length === 0) {
+            return;
+        }
+        found.push({
+            level: Number(match[1] ?? 1),
+            text: text.replace(/\|/g, "\\|").slice(0, 120),
+            page: contentPages[index] ?? 1
+        });
+    });
+    return found;
+}
+/** Concatenate a paragraph's text runs. */
+function paragraphText(paragraph) {
+    let out = "";
+    for (const child of paragraph.children ?? []) {
+        const content = child.content;
+        for (const item of content ?? []) {
+            if (typeof item.text === "string") {
+                out += item.text;
+            }
+        }
+    }
+    return out.trim();
+}
+//# sourceMappingURL=doc-paginate.js.map

package/dist/tools/doc-paginate.js.map

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

package/dist/tools/doc-read.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `doc_read` — read a document's text content.
+ *
+ * Covers Word, PDF, Markdown and plain text behind one tool because from the
+ * caller's point of view they are the same request: "what does this say". The
+ * differences that do matter are surfaced in the output — Word gains structure
+ * (headings, tables), PDF gains page boundaries — rather than in the schema.
+ *
+ * Word output is Markdown rather than flat text: headings, lists and tables
+ * survive, which is what lets a model answer questions about structure instead
+ * of only about words.
+ */
+export declare const docReadTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=doc-read.d.ts.map

package/dist/tools/doc-read.d.ts.map

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

package/dist/tools/doc-read.js

@@ -0,0 +1,175 @@
+/**
+ * `doc_read` — read a document's text content.
+ *
+ * Covers Word, PDF, Markdown and plain text behind one tool because from the
+ * caller's point of view they are the same request: "what does this say". The
+ * differences that do matter are surfaced in the output — Word gains structure
+ * (headings, tables), PDF gains page boundaries — rather than in the schema.
+ *
+ * Word output is Markdown rather than flat text: headings, lists and tables
+ * survive, which is what lets a model answer questions about structure instead
+ * of only about words.
+ */
+import { readFile } from "node:fs/promises";
+import { Pdf } from "documonster/pdf";
+import { Io, Query } from "documonster/word";
+import { renderToMarkdown } from "documonster/word/markdown";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { resolveInRoot } from "../sandbox.js";
+import { continuationNote, parsePages, requireFormat, takeLines } from "./document.js";
+import { assertReadableSize } from "./fs-helpers.js";
+import { formatBytes, textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Lines returned when the caller does not say. */
+const DEFAULT_MAX_LINES = 200;
+export const docReadTool = defineTool({
+    name: "doc_read",
+    group: ["word", "pdf"],
+    title: "Read a document's text",
+    description: "Read the text of a .docx, .pdf, .md or .txt file. Word documents come back as Markdown so headings, lists and tables survive; PDFs are reported page by page. Reads a bounded number of lines and always says what it omitted. Call doc_inspect first to learn the file's real type.",
+    inputSchema: {
+        path: z.string().min(1).describe("Document path, relative to the server root."),
+        pages: z
+            .union([z.array(z.number().int().positive()), z.string()])
+            .optional()
+            .describe('PDF only: pages to read, as [1,2,5] or "1-3,7". Omit for all pages.'),
+        maxLines: z
+            .number()
+            .int()
+            .positive()
+            .max(5000)
+            .optional()
+            .describe(`Line cap for this call. Defaults to ${DEFAULT_MAX_LINES}.`),
+        startLine: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("1-based line to resume from — use the value the previous call reported."),
+        outline: z
+            .boolean()
+            .optional()
+            .describe("Word only: return just the heading outline and document statistics instead of the body. Cheap way to decide what to read.")
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    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 format = requireFormat(args.path, "path");
+        switch (format) {
+            case "docx":
+                return textResult(config, await readWord(resolved, args));
+            case "pdf":
+                return textResult(config, await readPdf(resolved, args));
+            case "md":
+            case "txt":
+            case "html":
+                return textResult(config, await readPlainText(resolved, args, format));
+            default:
+                throw toolError.unsupported(`doc_read cannot read .${format} files`, format === "xlsx" || format === "csv"
+                    ? "Use sheet_read for spreadsheets and CSV files."
+                    : "Supported: .docx, .pdf, .md, .txt, .html");
+        }
+    }
+});
+async function readWord(resolved, args) {
+    const doc = await Io.readFile(resolved).catch((cause) => {
+        throw toolError.unsupported(`could not read ${args.path} as a Word document`, "If it is password-protected, that is not supported here yet. Run doc_inspect to confirm the container type — a CFB file is either a legacy .doc or an encrypted .docx.", { cause });
+    });
+    const headings = Query.getHeadings(doc);
+    const stats = [
+        `- paragraphs: ${Query.paragraphCount(doc)}`,
+        `- words: ${Query.countWords(doc)}`,
+        `- tables: ${Query.tableCount(doc)}`,
+        `- images: ${Query.listImages(doc).length}`
+    ];
+    if (args.outline === true) {
+        const lines = [`# ${args.path} — outline`, "", ...stats, ""];
+        if (headings.length === 0) {
+            lines.push("This document has no headings.", "", "Read the body with `outline: false`.");
+            return lines.join("\n");
+        }
+        lines.push("## Headings", "");
+        for (const heading of headings) {
+            lines.push(`${"  ".repeat(Math.max(0, heading.level - 1))}- H${heading.level}: ${heading.text}`);
+        }
+        lines.push("", "Read the body by calling again without `outline`.");
+        return lines.join("\n");
+    }
+    const markdown = renderToMarkdown(doc);
+    const window = takeLines(markdown, args.startLine ?? 1, args.maxLines ?? DEFAULT_MAX_LINES);
+    return [
+        `# ${args.path} (Word, as Markdown)`,
+        "",
+        ...stats,
+        `- showing lines ${window.startLine}–${window.endLine} of ${window.totalLines}`,
+        ...(headings.length > 0
+            ? [`- headings: ${headings.length} (use \`outline: true\` for just the outline)`]
+            : []),
+        ...continuationNote(window),
+        "",
+        window.text
+    ].join("\n");
+}
+async function readPdf(resolved, args) {
+    const bytes = await readFile(resolved);
+    const wanted = parsePages(args.pages);
+    const result = await Pdf.read(new Uint8Array(bytes), {
+        extractText: true,
+        extractImages: false,
+        extractTables: false,
+        extractAnnotations: false,
+        extractFormFields: false,
+        extractBookmarks: true,
+        ...(wanted === undefined ? {} : { pages: wanted })
+    }).catch((cause) => {
+        throw toolError.unsupported(`could not read ${args.path} as a PDF`, "If it is password-protected, this tool cannot open it yet.", { cause });
+    });
+    const pageCount = result.metadata?.pageCount ?? result.pages.length;
+    const header = [
+        `# ${args.path} (PDF)`,
+        "",
+        `- pages in file: ${pageCount}`,
+        `- pages read: ${result.pages.length}${wanted === undefined ? "" : ` (requested ${wanted.join(", ")})`}`,
+        `- size: ${formatBytes(bytes.byteLength)}`
+    ];
+    if (result.metadata?.title !== undefined && result.metadata.title.length > 0) {
+        header.push(`- title: ${result.metadata.title}`);
+    }
+    if (result.bookmarks !== undefined && result.bookmarks.length > 0) {
+        header.push(`- bookmarks: ${result.bookmarks.length}`);
+    }
+    // Page markers are load-bearing: without them a model cannot cite "page 4",
+    // and a heading split across a page break reads as two unrelated fragments.
+    const body = result.pages
+        .map(page => `\n## Page ${page.pageNumber}\n\n${page.text.trim().length === 0 ? "_(no extractable text — this page may be a scan)_" : page.text}`)
+        .join("\n");
+    const window = takeLines(body, args.startLine ?? 1, args.maxLines ?? DEFAULT_MAX_LINES);
+    const emptyPages = result.pages.filter(page => page.text.trim().length === 0).length;
+    if (emptyPages > 0) {
+        header.push(`- **${emptyPages} page(s) yielded no text.** There is no OCR here, so a scanned page reads as empty — say so rather than inferring content.`);
+    }
+    const warnings = result.pages.flatMap(page => page.warnings ?? []);
+    if (warnings.length > 0) {
+        header.push(`- parser warnings: ${warnings.slice(0, 3).join("; ")}`);
+    }
+    header.push(`- showing lines ${window.startLine}–${window.endLine} of ${window.totalLines}`);
+    header.push(...continuationNote(window));
+    return [...header, window.text].join("\n");
+}
+async function readPlainText(resolved, args, format) {
+    const raw = await readFile(resolved, "utf8");
+    const window = takeLines(raw, args.startLine ?? 1, args.maxLines ?? DEFAULT_MAX_LINES);
+    return [
+        `# ${args.path} (${format})`,
+        "",
+        `- showing lines ${window.startLine}–${window.endLine} of ${window.totalLines}`,
+        ...continuationNote(window),
+        "",
+        window.text
+    ].join("\n");
+}
+//# sourceMappingURL=doc-read.js.map

package/dist/tools/doc-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-read.js","sourceRoot":"","sources":["../../src/tools/doc-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,mDAAmD;AACnD,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;IACpC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC;IACtB,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,sRAAsR;IACxR,WAAW,EAAE;QACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAC/E,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aACzD,QAAQ,EAAE;aACV,QAAQ,CAAC,qEAAqE,CAAC;QAClF,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,EAAE;aACV,GAAG,CAAC,IAAI,CAAC;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,uCAAuC,iBAAiB,GAAG,CAAC;QACxE,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,EAAE;aACV,QAAQ,EAAE;aACV,QAAQ,CAAC,yEAAyE,CAAC;QACtF,OAAO,EAAE,CAAC;aACP,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CACP,2HAA2H,CAC5H;KACJ;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,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7E,MAAM,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAEhD,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,MAAM;gBACT,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC5D,KAAK,KAAK;gBACR,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC3D,KAAK,IAAI,CAAC;YACV,KAAK,KAAK,CAAC;YACX,KAAK,MAAM;gBACT,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACzE;gBACE,MAAM,SAAS,CAAC,WAAW,CACzB,yBAAyB,MAAM,QAAQ,EACvC,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK;oBACnC,CAAC,CAAC,gDAAgD;oBAClD,CAAC,CAAC,0CAA0C,CAC/C,CAAC;QACN,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,IAAiB;IACzD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC/D,MAAM,SAAS,CAAC,WAAW,CACzB,kBAAkB,IAAI,CAAC,IAAI,qBAAqB,EAChD,wKAAwK,EACxK,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG;QACZ,iBAAiB,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE;QAC5C,YAAY,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;QACnC,aAAa,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;QACpC,aAAa,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE;KAC5C,CAAC;IAEF,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,YAAY,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,EAAE,sCAAsC,CAAC,CAAC;YACzF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CACR,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,IAAI,EAAE,CACrF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,mDAAmD,CAAC,CAAC;QACpE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;IAE5F,OAAO;QACL,KAAK,IAAI,CAAC,IAAI,sBAAsB;QACpC,EAAE;QACF,GAAG,KAAK;QACR,mBAAmB,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,UAAU,EAAE;QAC/E,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YACrB,CAAC,CAAC,CAAC,eAAe,QAAQ,CAAC,MAAM,+CAA+C,CAAC;YACjF,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,gBAAgB,CAAC,MAAM,CAAC;QAC3B,EAAE;QACF,MAAM,CAAC,IAAI;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,QAAgB,EAAE,IAAiB;IACxD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEtC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE;QACnD,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,KAAK;QACpB,aAAa,EAAE,KAAK;QACpB,kBAAkB,EAAE,KAAK;QACzB,iBAAiB,EAAE,KAAK;QACxB,gBAAgB,EAAE,IAAI;QACtB,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;KACnD,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC1B,MAAM,SAAS,CAAC,WAAW,CACzB,kBAAkB,IAAI,CAAC,IAAI,WAAW,EACtC,4DAA4D,EAC5D,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;IACpE,MAAM,MAAM,GAAG;QACb,KAAK,IAAI,CAAC,IAAI,QAAQ;QACtB,EAAE;QACF,oBAAoB,SAAS,EAAE;QAC/B,iBAAiB,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;QACxG,WAAW,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE;KAC3C,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK;SACtB,GAAG,CACF,IAAI,CAAC,EAAE,CACL,aAAa,IAAI,CAAC,UAAU,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,mDAAmD,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CACvI;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;IAExF,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACrF,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,CAAC,IAAI,CACT,OAAO,UAAU,4HAA4H,CAC9I,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACnE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,sBAAsB,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7F,MAAM,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzC,OAAO,CAAC,GAAG,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,IAAiB,EAAE,MAAc;IAC9E,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;IAEvF,OAAO;QACL,KAAK,IAAI,CAAC,IAAI,KAAK,MAAM,GAAG;QAC5B,EAAE;QACF,mBAAmB,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,UAAU,EAAE;QAC/E,GAAG,gBAAgB,CAAC,MAAM,CAAC;QAC3B,EAAE;QACF,MAAM,CAAC,IAAI;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/tools/doc-review.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `doc_review` — compare two document versions, or work through one document's
+ * tracked changes.
+ *
+ * The one capability that justified a new tool rather than an operation on an
+ * existing one, for two reasons: it takes *two* inputs, which no other tool's
+ * shape allows, and contract review is the document task where a model's help is
+ * worth most — reading a redline is tedious, and the consequences of missing a
+ * changed amount are real.
+ *
+ * Both modes answer the same question — "what changed" — so they share a tool.
+ * Accepting or rejecting is opt-in and never implicit: the summary is what the
+ * caller usually wants, and applying a revision is a decision a person should
+ * make.
+ */
+export declare const docReviewTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=doc-review.d.ts.map

package/dist/tools/doc-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-review.d.ts","sourceRoot":"","sources":["../../src/tools/doc-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwBH,eAAO,MAAM,aAAa,wCA4DxB,CAAC"}

package/dist/tools/doc-review.js

@@ -0,0 +1,249 @@
+/**
+ * `doc_review` — compare two document versions, or work through one document's
+ * tracked changes.
+ *
+ * The one capability that justified a new tool rather than an operation on an
+ * existing one, for two reasons: it takes *two* inputs, which no other tool's
+ * shape allows, and contract review is the document task where a model's help is
+ * worth most — reading a redline is tedious, and the consequences of missing a
+ * changed amount are real.
+ *
+ * Both modes answer the same question — "what changed" — so they share a tool.
+ * Accepting or rejecting is opt-in and never implicit: the summary is what the
+ * caller usually wants, and applying a revision is a decision a person should
+ * make.
+ */
+import { Diff, Io, Query } from "documonster/word";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, resolveEditTarget, resolveInRoot } from "../sandbox.js";
+import { assertReadableSize, assertUnchanged, backupOnce, describeBackup, fingerprint, isSameFile, replaceAtomically, writeWithPolicy } from "./fs-helpers.js";
+import { textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Entries reported in one call. */
+const MAX_ENTRIES = 120;
+export const docReviewTool = defineTool({
+    name: "doc_review",
+    group: "word",
+    title: "Review document changes",
+    description: "Compare two .docx versions paragraph by paragraph, or list a document's tracked changes with their authors. Optionally accept or reject revisions. Give `path` and `against` to compare two files; give `path` alone to review tracked changes in one.",
+    inputSchema: {
+        path: z.string().min(1).describe("The document, or the earlier version when comparing."),
+        against: z
+            .string()
+            .optional()
+            .describe("The later version. Supply it to compare two files instead of reviewing revisions."),
+        apply: z
+            .enum(["accept-all", "reject-all"])
+            .optional()
+            .describe("Apply every tracked change. Omit to only report them — accepting a revision is a decision a person should usually make."),
+        out: z
+            .string()
+            .optional()
+            .describe("With `apply`, write below @output/. Required for input files unless --allow-in-place is enabled."),
+        backup: z
+            .boolean()
+            .optional()
+            .describe("When applying 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.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        // Conditional: listing/comparing is read-only, but `apply` can replace the
+        // input. MCP annotations cannot depend on arguments, so choose the safer
+        // hint and let clients ask for confirmation.
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+    },
+    // Comparing and listing are read-only; only `apply` writes. Declared
+    // non-mutating so a read-only server can still review changes, with
+    // assertWritable guarding the write path.
+    mutates: false,
+    handler: async (args, context) => {
+        const { config } = context;
+        if (args.against !== undefined) {
+            if (args.apply !== undefined) {
+                throw toolError.invalidInput("`apply` cannot be combined with `against`", "Comparing two files reports differences; there are no revisions in either to accept. Review one file's tracked changes instead.");
+            }
+            return textResult(config, await compare(config, args.path, args.against));
+        }
+        return textResult(config, await reviewRevisions(config, args));
+    }
+});
+async function compare(config, aPath, bPath) {
+    const [aResolved, bResolved] = await Promise.all([
+        resolveInRoot(config, aPath, { mustExist: true }),
+        resolveInRoot(config, bPath, { mustExist: true })
+    ]);
+    await Promise.all([
+        assertReadableSize(config, aResolved, aPath),
+        assertReadableSize(config, bResolved, bPath)
+    ]);
+    const [a, b] = await Promise.all([readWord(aResolved, aPath), readWord(bResolved, bPath)]);
+    const diff = Diff.documents(a, b);
+    if (diff.summary.added === 0 && diff.summary.deleted === 0 && diff.summary.modified === 0) {
+        return [
+            `# ${aPath} → ${bPath}`,
+            "",
+            "**No textual differences.** Every paragraph matches.",
+            "",
+            "This comparison covers body paragraphs only. Changes in headers, footers, footnotes, endnotes, comments, images and formatting are not detected — use doc_search with a `format` filter for appearance, and inspect those containers separately when they matter."
+        ].join("\n");
+    }
+    // Changed paragraphs first: a reviewer reading in document order wades through
+    // unchanged text to find the three lines that matter.
+    const changed = diff.entries.filter(entry => entry.type !== "unchanged");
+    const lines = [
+        `# ${aPath} → ${bPath}`,
+        "",
+        `- paragraphs compared: ${diff.summary.totalParagraphs}`,
+        `- **modified: ${diff.summary.modified} · added: ${diff.summary.added} · deleted: ${diff.summary.deleted}** · unchanged: ${diff.summary.unchanged}`,
+        ""
+    ];
+    for (const entry of changed.slice(0, MAX_ENTRIES)) {
+        const where = entry.newIndex !== undefined
+            ? `paragraph ${entry.newIndex + 1}`
+            : `was paragraph ${(entry.oldIndex ?? 0) + 1}`;
+        if (entry.type === "modified") {
+            lines.push(`## modified — ${where}`, "", `- before: ${quote(entry.oldText)}`, `- after: ${quote(entry.newText)}`, "");
+        }
+        else if (entry.type === "added") {
+            lines.push(`## added — ${where}`, "", `- ${quote(entry.newText)}`, "");
+        }
+        else {
+            lines.push(`## deleted — ${where}`, "", `- ${quote(entry.oldText)}`, "");
+        }
+    }
+    if (changed.length > MAX_ENTRIES) {
+        lines.push(`[${changed.length - MAX_ENTRIES} further change(s) not listed]`, "");
+    }
+    lines.push("This comparison covers body-paragraph text only. Headers, footers, footnotes, endnotes, comments, images and formatting are outside its scope.");
+    return lines.join("\n");
+}
+async function reviewRevisions(config, args) {
+    const resolved = await resolveInRoot(config, args.path, { mustExist: true });
+    await assertReadableSize(config, resolved, args.path);
+    const inputVersion = await fingerprint(resolved);
+    const doc = await readWord(resolved, args.path);
+    const revisions = Query.listRevisions(doc);
+    if (revisions.length === 0) {
+        return [
+            `# ${args.path}`,
+            "",
+            "This document contains no tracked changes.",
+            "",
+            "To compare it against another version, pass `against`."
+        ].join("\n");
+    }
+    // A revision's author and kind are optional in the model — Word permits an
+    // anonymous change — so both are normalised before counting.
+    const changes = collectRevisionText(doc);
+    const byAuthor = new Map();
+    const byType = new Map();
+    for (const revision of revisions) {
+        const author = revision.author ?? "(unattributed)";
+        const type = revision.type ?? "(unknown)";
+        byAuthor.set(author, (byAuthor.get(author) ?? 0) + 1);
+        byType.set(type, (byType.get(type) ?? 0) + 1);
+    }
+    const lines = [
+        `# ${args.path} — ${revisions.length} tracked change(s)`,
+        "",
+        `- by author: ${[...byAuthor].map(([author, count]) => `${author} (${count})`).join(", ")}`,
+        `- by kind: ${[...byType].map(([type, count]) => `${type} (${count})`).join(", ")}`,
+        "",
+        "| id | kind | author | text | date |",
+        "| --- | --- | --- | --- | --- |",
+        ...revisions.slice(0, MAX_ENTRIES).map(revision => {
+            const text = changes.get(revision.id);
+            return `| ${revision.id} | ${revision.type ?? "—"} | ${revision.author ?? "(unattributed)"} | ${text === undefined ? "—" : quote(text)} | ${revision.date ?? "—"} |`;
+        })
+    ];
+    if (revisions.length > MAX_ENTRIES) {
+        lines.push("", `[${revisions.length - MAX_ENTRIES} more not listed]`);
+    }
+    if (args.apply === undefined) {
+        lines.push("", 'Nothing was written. Pass `apply: "accept-all"` or `"reject-all"` to resolve them.', "", "Read the document with doc_read to see the text as it stands — inserted text is included, deleted text is not.");
+        return lines.join("\n");
+    }
+    assertWritable(config);
+    await assertUnchanged(resolved, inputVersion);
+    // Re-read: accept/reject mutate the document **in place** and return the
+    // number handled, so the listing's instance must not be reused.
+    const fresh = await readWord(resolved, args.path);
+    const handled = args.apply === "accept-all" ? Query.acceptAllRevisions(fresh) : Query.rejectAllRevisions(fresh);
+    const writeTarget = await resolveEditTarget(config, args.path, args.out);
+    const inPlace = isSameFile(writeTarget.path, resolved);
+    const backupPath = inPlace && (args.backup ?? true) ? await backupOnce(writeTarget) : undefined;
+    if (inPlace) {
+        await replaceAtomically(writeTarget.path, temporary => Io.writeFile(fresh, temporary));
+    }
+    else {
+        await writeWithPolicy(writeTarget.path, args.overwrite === true, temporary => Io.writeFile(fresh, temporary));
+    }
+    lines.push("", `**${args.apply === "accept-all" ? "Accepted" : "Rejected"} ${handled} revision(s)**, written to ${writeTarget.display}${inPlace ? " (in place)" : ""}.`, `- revisions remaining: ${countRevisions(fresh)}`, ...describeBackup(writeTarget.display, backupPath), "", "Read it back with doc_read to confirm the resulting text.");
+    return lines.join("\n");
+}
+/**
+ * Count remaining revisions, tolerating a failure to walk the document.
+ *
+ * Defensive on purpose: during development the document walker threw on one
+ * particular revision arrangement that could not afterwards be reproduced in
+ * isolation. Whatever the cause, a verification step must not be able to fail
+ * the write that already succeeded.
+ */
+function countRevisions(doc) {
+    try {
+        return String(Query.listRevisions(doc).length);
+    }
+    catch {
+        return "could not be counted — read the document to confirm";
+    }
+}
+/**
+ * Text covered by each revision, keyed by revision id.
+ *
+ * `listRevisions` reports who changed what *kind* of thing but not the words,
+ * which makes a redline summary useless on its own — a reviewer cannot approve
+ * "insert by Alice". The document is walked here to recover the runs, guarded
+ * because a malformed revision arrangement has been seen to break the walker and
+ * a listing must not fail for want of an annotation.
+ */
+function collectRevisionText(doc) {
+    const found = new Map();
+    const runText = (run) => (run.content ?? []).map(item => item.text ?? "").join("");
+    try {
+        Query.walkDocument(doc, {
+            visitInsertedRun(node) {
+                const id = node.revision?.id;
+                if (id !== undefined) {
+                    found.set(id, runText(node.run));
+                }
+            },
+            visitDeletedRun(node) {
+                const id = node.revision?.id;
+                if (id !== undefined) {
+                    found.set(id, runText(node.run));
+                }
+            }
+        });
+    }
+    catch {
+        // Annotation is best-effort; the id/kind/author listing stands without it.
+    }
+    return found;
+}
+function quote(text) {
+    if (text === undefined || text.length === 0) {
+        return "_(empty)_";
+    }
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 400 ? `${collapsed.slice(0, 400)}…` : collapsed;
+}
+async function readWord(resolved, displayPath) {
+    return await Io.readFile(resolved).catch((cause) => {
+        throw toolError.unsupported(`could not read ${displayPath} as a Word document`, "doc_review works with .docx only. Run doc_inspect to check the real file type.", { cause });
+    });
+}
+//# sourceMappingURL=doc-review.js.map