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

package/dist/capabilities.js

@@ -0,0 +1,188 @@
+/**
+ * MCP resources and prompts.
+ *
+ * Both exist to move cost out of the model's context.
+ *
+ * **Resources** publish the help topics at stable URIs, so a client can show
+ * them and a model can read one without spending a tool call. The same content
+ * is still reachable through `documonster_help`, because not every client
+ * supports resources.
+ *
+ * **Prompts** are workflow templates the *user* invokes. They matter because the
+ * hardest part of using this server well is knowing the order to do things in —
+ * inspect, then read narrowly, then write, then verify. A prompt encodes that
+ * sequence once instead of relying on the user to describe it.
+ */
+import { z } from "zod";
+import { HELP_TOPICS } from "./tools/help.js";
+/** URI scheme for help topics. */
+const HELP_URI_PREFIX = "documonster://help/";
+/** Register one resource per help topic. */
+export function registerResources(server) {
+    for (const [name, topic] of Object.entries(HELP_TOPICS)) {
+        server.registerResource(`help-${name}`, `${HELP_URI_PREFIX}${name}`, {
+            title: `documonster: ${name}`,
+            description: topic.summary,
+            mimeType: "text/markdown"
+        }, uri => ({
+            contents: [{ uri: uri.href, mimeType: "text/markdown", text: topic.body }]
+        }));
+    }
+}
+/**
+ * Register workflow prompts.
+ *
+ * Each returns a single user message that states the goal *and* the discipline —
+ * inspect first, keep data server-side, verify by reading back. Those three
+ * habits are what separate a cheap correct run from an expensive wrong one, and
+ * a prompt is the only place to establish them before the model starts.
+ */
+export function registerPrompts(server, config) {
+    const has = (group) => config.groups.has(group);
+    if (has("excel")) {
+        server.registerPrompt("summarise-spreadsheet", {
+            title: "Summarise a spreadsheet",
+            description: "Inspect a workbook and answer a question about it without reading it all.",
+            argsSchema: {
+                path: z.string().describe("Workbook path, relative to the server root."),
+                question: z.string().describe("What you want to know about it.")
+            }
+        }, ({ path, question }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Answer this question about ${path}: ${question}
+
+Work in this order:
+1. Call doc_inspect on ${path} to learn its sheets and their sizes.
+2. Read only the range you need. If a summary sheet already holds the answer, use it rather than re-deriving it from the detail sheets.
+3. If the answer requires a calculation, verify your arithmetic with formula_evaluate before stating it.
+4. Quote the cell addresses your answer comes from.
+
+Do not read a whole large sheet. If a read reports omitted rows, narrow the range instead of paging through everything.`
+                    }
+                }
+            ]
+        }));
+    }
+    if (has("excel") && !config.readonly) {
+        server.registerPrompt("build-report", {
+            title: "Build a report from data files",
+            description: "Turn one or more CSV/Excel files into a formatted workbook.",
+            argsSchema: {
+                sources: z
+                    .string()
+                    .describe("The data files or archive to use, as a comma-separated list."),
+                out: z.string().describe("Output .xlsx path."),
+                goal: z.string().describe("What the report should show.")
+            }
+        }, ({ sources, out, goal }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Build ${out} from ${sources}. It should show: ${goal}
+
+Work in this order:
+1. If a source is an archive, list it with archive_read and extract only what you need.
+2. doc_inspect each data file — CSV delimiters and encodings vary, and guessing wrong silently produces one column.
+3. Build the workbook with a single sheet_write call. Use \`fromCsv\` to load source data server-side; do not copy rows into your reply.
+4. Add formulas rather than pre-computed numbers, so the workbook stays live.
+5. The write result returns an @output/... path. Read that path back with sheet_read and confirm the computed values before telling me it is done.`
+                    }
+                }
+            ]
+        }));
+    }
+    if (has("forms") && !config.readonly) {
+        server.registerPrompt("fill-document", {
+            title: "Fill a template or form",
+            description: "Populate a Word template or a fillable form, then deliver a PDF.",
+            argsSchema: {
+                path: z.string().describe("Template or form path."),
+                data: z.string().describe("The values to put in it, in any readable form."),
+                pdf: z.string().optional().describe("Optional PDF output path.")
+            }
+        }, ({ path, data, pdf }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Fill ${path} with this data:
+
+${data}
+
+Work in this order:
+1. doc_inspect ${path} — it will tell you whether this is a {{placeholder}} template or a form with fields, and name the tool to use.
+2. List the placeholders (template_inspect) or the fields (form_fill with no values) before filling anything. Do not guess field names.
+3. Fill it. If a required value is missing, stop and ask me — never invent an identifier, reference number, date or amount.
+4. The fill result returns an @output/... path. Read it back and confirm no placeholder text survived.${pdf === undefined
+                            ? ""
+                            : `\n5. Convert that @output path to ${pdf} with doc_convert.`}`
+                    }
+                }
+            ]
+        }));
+    }
+    if (has("word")) {
+        server.registerPrompt("review-changes", {
+            title: "Review document changes",
+            description: "Compare two versions of a document, or review its tracked changes.",
+            argsSchema: {
+                a: z.string().describe("The document, or the earlier version."),
+                b: z.string().optional().describe("The later version, if comparing two files.")
+            }
+        }, ({ a, b }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: b === undefined
+                            ? `Review the tracked changes in ${a}.
+
+1. Call doc_review on it to list every revision with its author.
+2. Summarise what changed, grouped by intent rather than by paragraph order.
+3. Flag anything that changes an obligation, amount, date or party name — those need a human decision.
+4. Do not accept or reject anything unless I ask.`
+                            : `Compare ${a} with ${b} and tell me what changed.
+
+1. Call doc_review with both paths.
+2. Summarise the differences by significance, not in document order.
+3. Flag any change to an amount, date, party name or obligation.
+4. If a paragraph was reworded without changing meaning, say so rather than quoting both versions in full.`
+                    }
+                }
+            ]
+        }));
+    }
+    if ((has("word") || has("pdf") || has("excel")) && !config.readonly) {
+        server.registerPrompt("convert-document", {
+            title: "Convert a document",
+            description: "Convert a file to another format, with its limitations stated.",
+            argsSchema: {
+                from: z.string().describe("Source path."),
+                to: z.string().describe("Destination path; its extension picks the format.")
+            }
+        }, ({ from, to }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Convert ${from} to ${to}.
+
+1. doc_inspect the source first — an extension can lie, and the real format decides whether the conversion is possible at all.
+2. Use doc_convert. If that pair is not supported it will tell you what is; report that rather than trying alternatives at random.
+3. Tell me plainly what the conversion loses, if anything.`
+                    }
+                }
+            ]
+        }));
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * `documonster-mcp` executable — stdio transport.
+ *
+ * stdio is the only transport for now because it covers every local AI client
+ * and needs no session management or auth. A remote (Streamable HTTP) entry
+ * point would live beside this file, sharing `createServer`.
+ *
+ * Nothing here may write to stdout: stdout IS the protocol channel. All
+ * diagnostics go to stderr.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}

package/dist/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * `documonster-mcp` executable — stdio transport.
+ *
+ * stdio is the only transport for now because it covers every local AI client
+ * and needs no session management or auth. A remote (Streamable HTTP) entry
+ * point would live beside this file, sharing `createServer`.
+ *
+ * Nothing here may write to stdout: stdout IS the protocol channel. All
+ * diagnostics go to stderr.
+ */
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigError, readMetaFlags, resolveConfig, usage } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    const meta = readMetaFlags(argv);
+    if (meta.help) {
+        process.stdout.write(usage());
+        return;
+    }
+    const version = await readVersion();
+    if (meta.version) {
+        process.stdout.write(`${version}\n`);
+        return;
+    }
+    const config = resolveConfig(argv);
+    const server = createServer(config, { name: "documonster", version });
+    await server.connect(new StdioServerTransport());
+    // Report the effective sandbox on stderr so an operator can see, in the
+    // client's log, exactly what this process was allowed to touch.
+    process.stderr.write(`documonster-mcp ${version} ready — root=${config.root} output=${config.outputRoot} readonly=${config.readonly} inPlace=${config.allowInPlace} groups=${[...config.groups].join(",")}\n`);
+}
+/** Read the version from the package manifest, which sits beside `dist/` and `src/`. */
+async function readVersion() {
+    try {
+        const manifestUrl = new URL("../package.json", import.meta.url);
+        const parsed = JSON.parse(await readFile(manifestUrl, "utf8"));
+        if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+            const { version } = parsed;
+            if (typeof version === "string") {
+                return version;
+            }
+        }
+    }
+    catch {
+        // A missing or malformed manifest must not stop the server from starting.
+    }
+    return "0.0.0";
+}
+try {
+    await main();
+}
+catch (error) {
+    if (error instanceof ConfigError) {
+        process.stderr.write(`documonster-mcp: ${error.message}\n\n${usage()}`);
+        process.exit(2);
+    }
+    process.stderr.write(`documonster-mcp: fatal: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Server configuration: the command-line contract of `documonster-mcp`.
+ *
+ * Everything that constrains what the server is allowed to do lives here and
+ * is decided ONCE at startup, never per tool call. The model can therefore
+ * never widen its own permissions: `--root` and `--readonly` are invisible to it.
+ */
+/**
+ * Tool groups, used by `--enable` to keep the number of tools exposed to a
+ * model small. Every additional tool measurably increases the chance the model
+ * picks the wrong one, so a caller who only ever touches spreadsheets should
+ * not have to pay for the Word and PDF tool descriptions in its context.
+ *
+ * `core` (`documonster_help`, `doc_inspect`) is always enabled — it is how a
+ * model orients itself before doing anything else.
+ */
+export declare const TOOL_GROUPS: readonly ["core", "excel", "word", "pdf", "forms", "archive"];
+export type ToolGroup = (typeof TOOL_GROUPS)[number];
+export interface ServerConfig {
+    /**
+     * Absolute, symlink-resolved sandbox root. Every path a tool touches must
+     * resolve inside it (see `sandbox.ts`).
+     */
+    readonly root: string;
+    /**
+     * Private, disjoint writable root. Plain write paths resolve here; tools and
+     * prompts expose them as `@output/...` so later calls can read the result
+     * without ever granting writes to the input root.
+     */
+    readonly outputRoot: string;
+    /** Explicit compatibility escape hatch for modifying source files in place. */
+    readonly allowInPlace: boolean;
+    /** When true, every mutating tool is withheld from `tools/list` entirely. */
+    readonly readonly: boolean;
+    /** Enabled tool groups; always contains `core`. */
+    readonly groups: ReadonlySet<ToolGroup>;
+    /** Reject input documents larger than this many bytes. */
+    readonly maxFileSize: number;
+    /** Truncate tool output beyond this many characters. */
+    readonly maxOutputChars: number;
+}
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
+export interface ResolveConfigOptions {
+    /** Overrides `process.cwd()`; used by tests. */
+    readonly cwd?: string;
+}
+/**
+ * Build a {@link ServerConfig} from CLI-style arguments.
+ *
+ * @param argv - Arguments *after* `node script.js`, i.e. `process.argv.slice(2)`.
+ * @throws {ConfigError} On an unknown flag, a missing value, or a `--root`
+ *   that does not exist. Failing loudly at startup is deliberate: a silently
+ *   defaulted root would sandbox the model somewhere the operator never chose.
+ */
+export declare function resolveConfig(argv: readonly string[], options?: ResolveConfigOptions): ServerConfig;
+/** True when `--help` or `--version` was passed; the CLI short-circuits on these. */
+export declare function readMetaFlags(argv: readonly string[]): {
+    help: boolean;
+    version: boolean;
+};
+/** Usage text for `--help`. */
+export declare function usage(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,YAAI,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAEzF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAerD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAkB,IAAI,iBAAiB;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,oBAAyB,GACjC,YAAY,CAuEd;AAUD,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAK1F;AA2CD,+BAA+B;AAC/B,wBAAgB,KAAK,IAAI,MAAM,CAkC9B"}

package/dist/config.js

@@ -0,0 +1,189 @@
+/**
+ * Server configuration: the command-line contract of `documonster-mcp`.
+ *
+ * Everything that constrains what the server is allowed to do lives here and
+ * is decided ONCE at startup, never per tool call. The model can therefore
+ * never widen its own permissions: `--root` and `--readonly` are invisible to it.
+ */
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+/**
+ * Tool groups, used by `--enable` to keep the number of tools exposed to a
+ * model small. Every additional tool measurably increases the chance the model
+ * picks the wrong one, so a caller who only ever touches spreadsheets should
+ * not have to pay for the Word and PDF tool descriptions in its context.
+ *
+ * `core` (`documonster_help`, `doc_inspect`) is always enabled — it is how a
+ * model orients itself before doing anything else.
+ */
+export const TOOL_GROUPS = ["core", "excel", "word", "pdf", "forms", "archive"];
+/** Groups enabled when `--enable` is omitted. */
+const DEFAULT_GROUPS = ["core", "excel", "word", "pdf", "forms", "archive"];
+/** Default ceiling for a single input document, in bytes (64 MiB). */
+const DEFAULT_MAX_FILE_SIZE = 64 * 1024 * 1024;
+/**
+ * Default ceiling for the text a single tool call may return, in characters.
+ * A tool result goes straight into the model's context, so this is a token
+ * budget in disguise: ~40 000 characters is roughly 10 000 tokens.
+ */
+const DEFAULT_MAX_OUTPUT_CHARS = 40_000;
+export class ConfigError extends Error {
+    name = "ConfigError";
+}
+/**
+ * Build a {@link ServerConfig} from CLI-style arguments.
+ *
+ * @param argv - Arguments *after* `node script.js`, i.e. `process.argv.slice(2)`.
+ * @throws {ConfigError} On an unknown flag, a missing value, or a `--root`
+ *   that does not exist. Failing loudly at startup is deliberate: a silently
+ *   defaulted root would sandbox the model somewhere the operator never chose.
+ */
+export function resolveConfig(argv, options = {}) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            options: {
+                root: { type: "string" },
+                "output-root": { type: "string" },
+                "allow-in-place": { type: "boolean", default: false },
+                readonly: { type: "boolean", default: false },
+                enable: { type: "string" },
+                "max-file-size": { type: "string" },
+                "max-output-chars": { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false }
+            },
+            allowPositionals: false,
+            strict: true
+        });
+    }
+    catch (cause) {
+        throw new ConfigError(cause instanceof Error ? cause.message : String(cause), { cause });
+    }
+    const values = parsed.values;
+    const cwd = options.cwd ?? process.cwd();
+    const rootInput = values.root ?? cwd;
+    let root;
+    try {
+        // realpath, not just resolve: the containment check in `sandbox.ts`
+        // compares realpaths, so the root must already be one or a symlinked
+        // root (`/tmp` -> `/private/tmp` on macOS) would reject everything.
+        root = realpathSync(path.resolve(cwd, rootInput));
+    }
+    catch (cause) {
+        throw new ConfigError(`--root does not exist or is not readable: ${rootInput}`, { cause });
+    }
+    let outputRoot;
+    try {
+        const outputInput = values["output-root"];
+        if (outputInput === undefined) {
+            outputRoot = realpathSync(mkdtempSync(path.join(os.tmpdir(), "documonster-mcp-output-")));
+            chmodSync(outputRoot, 0o700);
+        }
+        else {
+            const absolute = path.resolve(cwd, outputInput);
+            mkdirSync(absolute, { recursive: true, mode: 0o700 });
+            outputRoot = realpathSync(absolute);
+        }
+    }
+    catch (cause) {
+        throw new ConfigError("--output-root could not be created or is not writable", { cause });
+    }
+    if (containsPath(root, outputRoot) || containsPath(outputRoot, root)) {
+        throw new ConfigError("--output-root must be disjoint from --root (neither may contain the other)");
+    }
+    return {
+        root,
+        outputRoot,
+        allowInPlace: values["allow-in-place"] ?? false,
+        readonly: values.readonly ?? false,
+        groups: parseGroups(values.enable),
+        maxFileSize: parseByteCount(values["max-file-size"], "--max-file-size", DEFAULT_MAX_FILE_SIZE),
+        maxOutputChars: parseByteCount(values["max-output-chars"], "--max-output-chars", DEFAULT_MAX_OUTPUT_CHARS)
+    };
+}
+function containsPath(parent, child) {
+    const relative = path.relative(parent, child);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)));
+}
+/** True when `--help` or `--version` was passed; the CLI short-circuits on these. */
+export function readMetaFlags(argv) {
+    return {
+        help: argv.includes("--help") || argv.includes("-h"),
+        version: argv.includes("--version") || argv.includes("-v")
+    };
+}
+function parseGroups(raw) {
+    if (raw === undefined) {
+        return new Set(DEFAULT_GROUPS);
+    }
+    const requested = raw
+        .split(",")
+        .map(entry => entry.trim())
+        .filter(entry => entry.length > 0);
+    if (requested.length === 0) {
+        throw new ConfigError(`--enable needs at least one group (known: ${TOOL_GROUPS.join(", ")})`);
+    }
+    const groups = new Set(["core"]);
+    for (const entry of requested) {
+        if (!isToolGroup(entry)) {
+            throw new ConfigError(`--enable: unknown group "${entry}" (known: ${TOOL_GROUPS.join(", ")})`);
+        }
+        groups.add(entry);
+    }
+    return groups;
+}
+function isToolGroup(value) {
+    return TOOL_GROUPS.includes(value);
+}
+function parseByteCount(raw, flag, fallback) {
+    if (raw === undefined) {
+        return fallback;
+    }
+    const parsedValue = Number(raw);
+    if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+        throw new ConfigError(`${flag} must be a positive integer, got "${raw}"`);
+    }
+    return parsedValue;
+}
+/** Usage text for `--help`. */
+export function usage() {
+    return `documonster-mcp — Model Context Protocol server for documonster
+
+Usage:
+  documonster-mcp [options]
+
+Options:
+  --root <dir>                Sandbox root. Every path a tool touches must
+                              resolve inside it. Read-only by default.
+  --output-root <dir>         Separate writable root. Default: a private 0700
+                              temporary directory. Outputs are addressed as
+                              @output/<path> in later tool calls.
+  --allow-in-place            Permit explicit in-place edits under --root.
+                              Off by default; weakens the filesystem boundary.
+  --readonly                  Withhold every mutating tool.
+  --enable <groups>           Comma-separated tool groups to expose.
+                              Known: ${TOOL_GROUPS.join(", ")}. "core" is always on.
+                              Default: all.
+  --max-file-size <bytes>     Reject larger input documents. Default: ${DEFAULT_MAX_FILE_SIZE}.
+  --max-output-chars <n>      Truncate tool output. Default: ${DEFAULT_MAX_OUTPUT_CHARS}.
+  -h, --help                  Show this help.
+  -v, --version               Show version.
+
+Transport: stdio. Point an MCP client at this command, for example
+
+  {
+    "mcpServers": {
+      "documonster": {
+        "command": "npx",
+        "args": ["-y", "@documonster/mcp", "--root", "/path/to/documents"]
+      }
+    }
+  }
+`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAIzF,iDAAiD;AACjD,MAAM,cAAc,GAAyB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAElG,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C;;;;GAIG;AACH,MAAM,wBAAwB,GAAG,MAAM,CAAC;AA0BxC,MAAM,OAAO,WAAY,SAAQ,KAAK;IAClB,IAAI,GAAG,aAAa,CAAC;CACxC;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAuB,EACvB,OAAO,GAAyB,EAAE;IAElC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC;YACjB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,OAAO,EAAE;gBACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxB,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACjC,gBAAgB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;gBACrD,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;gBAC7C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACnC,kBAAkB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACtC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;gBACrD,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;aACzD;YACD,gBAAgB,EAAE,KAAK;YACvB,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC;IAErC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,6CAA6C,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAC1C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,UAAU,GAAG,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC;YAC1F,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YAChD,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACtD,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,uDAAuD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,WAAW,CACnB,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI;QACJ,UAAU;QACV,YAAY,EAAE,MAAM,CAAC,gBAAgB,CAAC,IAAI,KAAK;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,KAAK;QAClC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAClC,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,iBAAiB,EAAE,qBAAqB,CAAC;QAC9F,cAAc,EAAE,cAAc,CAC5B,MAAM,CAAC,kBAAkB,CAAC,EAC1B,oBAAoB,EACpB,wBAAwB,CACzB;KACF,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,KAAa;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAC3F,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QACpD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAuB;IAC1C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,SAAS,GAAG,GAAG;SAClB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAErC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,WAAW,CAAC,6CAA6C,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChG,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,WAAW,CACnB,4BAA4B,KAAK,aAAa,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxE,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAQ,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,cAAc,CAAC,GAAuB,EAAE,IAAY,EAAE,QAAgB;IAC7E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,WAAW,CAAC,GAAG,IAAI,qCAAqC,GAAG,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,KAAK;IACnB,OAAO;;;;;;;;;;;;;;;uCAe8B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;;wEAEW,qBAAqB;+DAC9B,wBAAwB;;;;;;;;;;;;;;CActF,CAAC;AACF,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Error model.
+ *
+ * A tool error is not a crash — it is a message to the model, and the model
+ * will try again based on what it reads. So every error carries a machine
+ * `code` plus, wherever we can produce one, a `hint` telling the model what to
+ * do differently. Error text quality directly determines retry success rate,
+ * which makes this file part of the product rather than plumbing.
+ */
+export type ToolErrorCode = 
+/** Arguments were structurally valid but semantically wrong. */
+"invalid_input"
+/** The path does not exist. */
+ | "not_found"
+/** The path resolved outside the sandbox root. */
+ | "outside_root"
+/** A mutating tool was reached while `--readonly` is active. */
+ | "readonly"
+/** Input exceeded `--max-file-size`, or output would exceed its budget. */
+ | "too_large"
+/** A capability the server deliberately does not expose. */
+ | "unsupported"
+/** Anything unclassified — a bug in the server or an unmapped library error. */
+ | "internal";
+export interface McpToolErrorOptions extends ErrorOptions {
+    /** Actionable next step for the model, e.g. "call doc_inspect first". */
+    readonly hint?: string;
+}
+/**
+ * An error that is safe and useful to hand back to a model.
+ *
+ * Anything thrown that is NOT an `McpToolError` is treated as unclassified and
+ * reported as `internal` — so a stack-leaking library error can never be
+ * mistaken for a designed, model-facing message.
+ */
+export declare class McpToolError extends Error {
+    readonly name = "McpToolError";
+    readonly code: ToolErrorCode;
+    readonly hint: string | undefined;
+    constructor(code: ToolErrorCode, message: string, options?: McpToolErrorOptions);
+}
+/**
+ * Convenience constructors for the codes used most often.
+ *
+ * Each takes an optional `cause`, because documonster's own errors chain via
+ * `{ cause }` and the innermost message is usually the one naming the cell,
+ * OOXML part or ZIP entry that actually failed — dropping it would leave the
+ * model with a generic message it cannot act on.
+ */
+export declare const toolError: {
+    readonly invalidInput: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+    readonly notFound: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+    readonly outsideRoot: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+    readonly readonly: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+    readonly tooLarge: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+    readonly unsupported: (message: string, hint?: string, options?: ErrorOptions) => McpToolError;
+};
+/**
+ * Render any thrown value as the text body of an `isError` tool result.
+ *
+ * Includes the `cause` chain because documonster's own errors chain via
+ * `{ cause }`, and the innermost message is usually the one that says which
+ * cell, part or ZIP entry actually failed.
+ */
+export declare function formatToolError(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa;AACvB,gEAAgE;AAC9D,eAAe;AACjB,+BAA+B;GAC7B,WAAW;AACb,kDAAkD;GAChD,cAAc;AAChB,gEAAgE;GAC9D,UAAU;AACZ,2EAA2E;GACzE,WAAW;AACb,4DAA4D;GAC1D,aAAa;AACf,gFAAgF;GAC9E,UAAU,CAAC;AAEf,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,kBAAkB;IACxC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAElC,YAAY,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,EAIlF;CACF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS;aACpB,YAAY,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;aAGlF,QAAQ,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;aAG9E,WAAW,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;aAGjF,QAAQ,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;aAG9E,QAAQ,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;aAG9E,WAAW,YAAU,MAAM,SAAS,MAAM,YAAY,YAAY,KAAG,YAAY;CAGzE,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAuBtD"}