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

package/dist/errors.js

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+/**
+ * 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 class McpToolError extends Error {
+    name = "McpToolError";
+    code;
+    hint;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.code = code;
+        this.hint = options.hint;
+    }
+}
+/**
+ * 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 const toolError = {
+    invalidInput(message, hint, options) {
+        return new McpToolError("invalid_input", message, { hint, ...options });
+    },
+    notFound(message, hint, options) {
+        return new McpToolError("not_found", message, { hint, ...options });
+    },
+    outsideRoot(message, hint, options) {
+        return new McpToolError("outside_root", message, { hint, ...options });
+    },
+    readonly(message, hint, options) {
+        return new McpToolError("readonly", message, { hint, ...options });
+    },
+    tooLarge(message, hint, options) {
+        return new McpToolError("too_large", message, { hint, ...options });
+    },
+    unsupported(message, hint, options) {
+        return new McpToolError("unsupported", message, { hint, ...options });
+    }
+};
+/**
+ * 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 function formatToolError(error) {
+    if (error instanceof McpToolError) {
+        const lines = [`[${error.code}] ${error.message}`];
+        const chain = describeCauseChain(error.cause);
+        if (chain !== undefined) {
+            lines.push(`Caused by: ${chain}`);
+        }
+        if (error.hint !== undefined) {
+            lines.push(`Hint: ${error.hint}`);
+        }
+        return lines.join("\n");
+    }
+    if (error instanceof Error) {
+        const lines = [`[internal] ${error.name}: ${error.message}`];
+        const chain = describeCauseChain(error.cause);
+        if (chain !== undefined) {
+            lines.push(`Caused by: ${chain}`);
+        }
+        return lines.join("\n");
+    }
+    return `[internal] ${String(error)}`;
+}
+/** Flatten `cause` links into `A: msg -> B: msg`, with a depth guard. */
+function describeCauseChain(cause, depth = 0) {
+    if (cause === undefined || cause === null || depth >= 5) {
+        return undefined;
+    }
+    if (!(cause instanceof Error)) {
+        return String(cause);
+    }
+    const head = `${cause.name}: ${cause.message}`;
+    const tail = describeCauseChain(cause.cause, depth + 1);
+    return tail === undefined ? head : `${head} -> ${tail}`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@documonster/mcp` — programmatic entry point.
+ *
+ * Importing this package lets you embed the server in your own process (for
+ * example to attach a different transport, or to drive it from an agent
+ * framework) instead of spawning the `documonster-mcp` executable.
+ *
+ * ```ts
+ * import { createServer, resolveConfig } from "@documonster/mcp";
+ *
+ * const server = createServer(resolveConfig(["--root", "./workspace", "--readonly"]));
+ * await server.connect(myTransport);
+ * ```
+ */
+export { ConfigError, readMetaFlags, resolveConfig, TOOL_GROUPS, usage } from "./config.js";
+export type { ResolveConfigOptions, ServerConfig, ToolGroup } from "./config.js";
+export { formatToolError, McpToolError, toolError } from "./errors.js";
+export type { McpToolErrorOptions, ToolErrorCode } from "./errors.js";
+export { assertWritable, isInside, resolveInRoot } from "./sandbox.js";
+export type { ResolveOptions } from "./sandbox.js";
+export { createServer } from "./server.js";
+export type { ServerIdentity } from "./server.js";
+export { ALL_TOOLS, selectTools } from "./tools/index.js";
+export type { AnyToolDefinition, ToolContext, ToolDefinition } from "./tools/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@documonster/mcp` — programmatic entry point.
+ *
+ * Importing this package lets you embed the server in your own process (for
+ * example to attach a different transport, or to drive it from an agent
+ * framework) instead of spawning the `documonster-mcp` executable.
+ *
+ * ```ts
+ * import { createServer, resolveConfig } from "@documonster/mcp";
+ *
+ * const server = createServer(resolveConfig(["--root", "./workspace", "--readonly"]));
+ * await server.connect(myTransport);
+ * ```
+ */
+export { ConfigError, readMetaFlags, resolveConfig, TOOL_GROUPS, usage } from "./config.js";
+export { formatToolError, McpToolError, toolError } from "./errors.js";
+export { assertWritable, isInside, resolveInRoot } from "./sandbox.js";
+export { createServer } from "./server.js";
+export { ALL_TOOLS, selectTools } from "./tools/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/sandbox.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Path sandbox.
+ *
+ * The single most important file in this package. An MCP server hands a model
+ * the ability to name files, so every path a tool touches must go through
+ * {@link resolveInRoot} — there is no other legitimate way to turn a
+ * model-supplied string into a filesystem path.
+ *
+ * Two attacks this defends against:
+ *
+ * 1. Traversal — `../../.ssh/id_rsa`, or a plain absolute path. Handled by
+ *    resolving against the root and then checking containment.
+ * 2. Symlink escape — a link inside the root pointing outside it. Handled by
+ *    realpath'ing the deepest part of the path that actually exists, which is
+ *    why the check cannot be a naive `startsWith` on the raw string.
+ *
+ * Do NOT rely on the MCP client's tool-approval prompt for this. Programmatic
+ * clients have no prompt.
+ */
+import type { ServerConfig } from "./config.js";
+export interface ResolveOptions {
+    /**
+     * When true, the path must already exist. Use for inputs; leave false for
+     * write targets, whose parent is checked instead.
+     */
+    readonly mustExist?: boolean;
+}
+/**
+ * Turn a model-supplied path into an absolute path guaranteed to sit inside
+ * `config.root`.
+ *
+ * @throws {McpToolError} `invalid_input` for a URL or empty string,
+ *   `not_found` when `mustExist` is set and it is not there, and
+ *   `outside_root` for anything that escapes the sandbox.
+ */
+export declare function resolveInRoot(config: ServerConfig, userPath: string, options?: ResolveOptions): Promise<string>;
+/**
+ * Resolve a path a tool is about to write to, plus its sidecar files.
+ *
+ * A write target needs more than containment: every path the tool derives from
+ * it — a `.bak`, a temporary file — must be confined too, or a pre-planted
+ * symlink at `report.xlsx.bak` lets an in-place edit write outside the root.
+ */
+export declare function resolveWriteTarget(config: ServerConfig, userPath: string, options?: {
+    readonly inPlace?: boolean;
+}): Promise<WriteTarget>;
+/** Resolve a write destination inside the disjoint output root. */
+export declare function resolveOutputPath(config: ServerConfig, userPath: string): Promise<string>;
+/** Public display spelling for a path under the output root. */
+export declare function outputDisplay(userPath: string): string;
+export interface WriteTarget {
+    /** Confined absolute path to write. */
+    readonly path: string;
+    /** Confined absolute path for the `.bak` sidecar. */
+    readonly backupPath: string;
+    /** The caller's spelling, for messages. */
+    readonly display: string;
+}
+/**
+ * Choose the destination for a tool that edits an existing file.
+ *
+ * Files already under `@output/` may be edited in place because that root is
+ * the server's private writable workspace. Input files require an explicit
+ * `out` unless the operator enabled the compatibility escape hatch.
+ */
+export declare function resolveEditTarget(config: ServerConfig, sourcePath: string, out: string | undefined): Promise<WriteTarget>;
+/**
+ * Assert the server is allowed to mutate the filesystem.
+ *
+ * Mutating tools are already withheld from `tools/list` under `--readonly`;
+ * this is the second line of defence for a client that calls a tool it was
+ * never told about.
+ *
+ * @remarks
+ * Called by every mutating tool (`sheet_write`, `archive_read` when extracting)
+ * before it touches the disk. `selectTools` filtering is the other half.
+ */
+export declare function assertWritable(config: ServerConfig): void;
+/**
+ * True when `child` is `parent` itself or lives beneath it.
+ *
+ * Compares path segments rather than raw strings, so `/root-2` is correctly
+ * rejected as a sibling of `/root` instead of matching a `startsWith("/root")`.
+ */
+export declare function isInside(parent: string, child: string): boolean;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmCjB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,OAAO,CAAC,WAAW,CAAC,CA2BtB;AAED,mEAAmE;AACnE,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB/F;AAyBD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAW/D"}

package/dist/sandbox.js

@@ -0,0 +1,224 @@
+/**
+ * Path sandbox.
+ *
+ * The single most important file in this package. An MCP server hands a model
+ * the ability to name files, so every path a tool touches must go through
+ * {@link resolveInRoot} — there is no other legitimate way to turn a
+ * model-supplied string into a filesystem path.
+ *
+ * Two attacks this defends against:
+ *
+ * 1. Traversal — `../../.ssh/id_rsa`, or a plain absolute path. Handled by
+ *    resolving against the root and then checking containment.
+ * 2. Symlink escape — a link inside the root pointing outside it. Handled by
+ *    realpath'ing the deepest part of the path that actually exists, which is
+ *    why the check cannot be a naive `startsWith` on the raw string.
+ *
+ * Do NOT rely on the MCP client's tool-approval prompt for this. Programmatic
+ * clients have no prompt.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { toolError } from "./errors.js";
+/** Symlink hops allowed before a path is treated as a loop. */
+const MAX_SYMLINK_DEPTH = 32;
+/** Matches a URL scheme (`http:`, `file:`) without matching a Windows drive letter (`C:`). */
+const URL_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]+:/;
+/**
+ * Turn a model-supplied path into an absolute path guaranteed to sit inside
+ * `config.root`.
+ *
+ * @throws {McpToolError} `invalid_input` for a URL or empty string,
+ *   `not_found` when `mustExist` is set and it is not there, and
+ *   `outside_root` for anything that escapes the sandbox.
+ */
+export async function resolveInRoot(config, userPath, options = {}) {
+    if (typeof userPath !== "string" || userPath.trim().length === 0) {
+        throw toolError.invalidInput("path must be a non-empty string");
+    }
+    if (URL_SCHEME_RE.test(userPath)) {
+        throw toolError.invalidInput(`path must be a local path inside the sandbox, not a URL: ${userPath}`, "Use a path relative to the server root. This server reads local files only.");
+    }
+    const outputRelative = outputPathPart(userPath);
+    const base = outputRelative === undefined ? config.root : config.outputRoot;
+    const relative = outputRelative ?? userPath;
+    const candidate = path.resolve(base, relative);
+    const resolved = await resolveSegments(candidate);
+    if (!isInside(base, resolved)) {
+        throw toolError.outsideRoot(`path resolves outside the server root: ${userPath}`, outputRelative === undefined
+            ? "Only paths inside the configured --root are readable. Ask the user to restart the server with a wider root if this file is genuinely needed."
+            : "Only paths inside --output-root are accessible through @output/.");
+    }
+    if (options.mustExist === true && !(await pathExists(resolved))) {
+        throw toolError.notFound(`no such file or directory: ${userPath}`, "Call doc_inspect on the parent directory to see what is actually there.");
+    }
+    return resolved;
+}
+/**
+ * Resolve a path a tool is about to write to, plus its sidecar files.
+ *
+ * A write target needs more than containment: every path the tool derives from
+ * it — a `.bak`, a temporary file — must be confined too, or a pre-planted
+ * symlink at `report.xlsx.bak` lets an in-place edit write outside the root.
+ */
+export async function resolveWriteTarget(config, userPath, options = {}) {
+    if (options.inPlace === true) {
+        const outputRelative = outputPathPart(userPath);
+        if (outputRelative !== undefined) {
+            const target = await resolveOutputPath(config, outputRelative);
+            const backup = await resolveOutputPath(config, `${outputRelative}.bak`);
+            return {
+                path: target,
+                backupPath: backup,
+                display: `@output/${normaliseDisplay(outputRelative)}`
+            };
+        }
+        if (!config.allowInPlace) {
+            throw toolError.readonly("in-place edits are disabled", "Provide an `out` path to write safely under @output/, or restart the server with --allow-in-place.");
+        }
+        const target = await resolveInRoot(config, userPath);
+        const backup = await resolveInputSidecar(config, `${userPath}.bak`);
+        return { path: target, backupPath: backup, display: userPath };
+    }
+    const relative = outputPathPart(userPath) ?? userPath;
+    const target = await resolveOutputPath(config, relative);
+    const backup = await resolveOutputPath(config, `${relative}.bak`);
+    return { path: target, backupPath: backup, display: `@output/${normaliseDisplay(relative)}` };
+}
+/** Resolve a write destination inside the disjoint output root. */
+export async function resolveOutputPath(config, userPath) {
+    const relative = outputPathPart(userPath) ?? userPath;
+    if (path.isAbsolute(relative)) {
+        throw toolError.invalidInput(`output path must be relative: ${userPath}`, "Write paths are relative to --output-root and are returned as @output/<path>.");
+    }
+    const candidate = path.resolve(config.outputRoot, relative);
+    const resolved = await resolveSegments(candidate);
+    if (!isInside(config.outputRoot, resolved)) {
+        throw toolError.outsideRoot(`output path resolves outside --output-root: ${userPath}`, "Use a relative output path without `..`.");
+    }
+    return resolved;
+}
+/** Resolve a sidecar beside an input file; available only in explicit in-place mode. */
+async function resolveInputSidecar(config, userPath) {
+    const candidate = path.resolve(config.root, userPath);
+    const resolved = await resolveSegments(candidate);
+    if (!isInside(config.root, resolved)) {
+        throw toolError.outsideRoot(`sidecar path resolves outside --root: ${userPath}`);
+    }
+    return resolved;
+}
+/** Return the path after the virtual @output/ prefix, or undefined for input. */
+function outputPathPart(userPath) {
+    const normalised = userPath.replace(/\\/g, "/");
+    if (normalised === "@output") {
+        return ".";
+    }
+    return normalised.startsWith("@output/") ? normalised.slice("@output/".length) : undefined;
+}
+function normaliseDisplay(relative) {
+    return relative.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Public display spelling for a path under the output root. */
+export function outputDisplay(userPath) {
+    const relative = outputPathPart(userPath) ?? userPath;
+    return `@output/${normaliseDisplay(relative)}`;
+}
+/**
+ * Choose the destination for a tool that edits an existing file.
+ *
+ * Files already under `@output/` may be edited in place because that root is
+ * the server's private writable workspace. Input files require an explicit
+ * `out` unless the operator enabled the compatibility escape hatch.
+ */
+export async function resolveEditTarget(config, sourcePath, out) {
+    if (out !== undefined) {
+        return await resolveWriteTarget(config, out);
+    }
+    if (outputPathPart(sourcePath) !== undefined) {
+        return await resolveWriteTarget(config, sourcePath, { inPlace: true });
+    }
+    return await resolveWriteTarget(config, sourcePath, { inPlace: true });
+}
+/** True when a path exists, following symlinks. */
+async function pathExists(target) {
+    try {
+        await fs.stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Assert the server is allowed to mutate the filesystem.
+ *
+ * Mutating tools are already withheld from `tools/list` under `--readonly`;
+ * this is the second line of defence for a client that calls a tool it was
+ * never told about.
+ *
+ * @remarks
+ * Called by every mutating tool (`sheet_write`, `archive_read` when extracting)
+ * before it touches the disk. `selectTools` filtering is the other half.
+ */
+export function assertWritable(config) {
+    if (config.readonly) {
+        throw toolError.readonly("this server is running in --readonly mode", "Report to the user that writing is disabled; do not retry.");
+    }
+}
+/**
+ * True when `child` is `parent` itself or lives beneath it.
+ *
+ * Compares path segments rather than raw strings, so `/root-2` is correctly
+ * rejected as a sibling of `/root` instead of matching a `startsWith("/root")`.
+ */
+export function isInside(parent, child) {
+    if (child === parent) {
+        return true;
+    }
+    const relative = path.relative(parent, child);
+    return (relative.length > 0 &&
+        !relative.startsWith(`..${path.sep}`) &&
+        relative !== ".." &&
+        !path.isAbsolute(relative));
+}
+/**
+ * Realpath every segment of `target`, following symlinks explicitly.
+ *
+ * `fs.realpath` cannot be used for the whole path: it throws `ENOENT` both for
+ * "this does not exist" and for "this is a symlink whose target does not
+ * exist". Treating the second case as the first is a sandbox escape — a
+ * dangling link pointing outside the root would be reported as an ordinary
+ * not-yet-existing path inside it, and the tool would then create the file at
+ * the link's real destination.
+ *
+ * So each segment is resolved in turn: an existing symlink is read and its
+ * target resolved recursively, whether or not that target exists yet, while a
+ * genuinely missing segment is simply appended.
+ */
+async function resolveSegments(target, depth = 0) {
+    if (depth > MAX_SYMLINK_DEPTH) {
+        throw toolError.invalidInput(`too many symbolic links while resolving ${target}`, "The path contains a symlink loop.");
+    }
+    const parent = path.dirname(target);
+    // `path.dirname` is a fixed point at the filesystem root, which ends recursion.
+    const resolvedParent = parent === target ? target : await resolveSegments(parent, depth + 1);
+    const candidate = path.join(resolvedParent, path.basename(target));
+    let stats;
+    try {
+        stats = await fs.lstat(candidate);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT") {
+            // Genuinely absent: a valid write target, and nothing left to follow.
+            return candidate;
+        }
+        throw cause;
+    }
+    if (!stats.isSymbolicLink()) {
+        return candidate;
+    }
+    const link = await fs.readlink(candidate);
+    const absolute = path.isAbsolute(link) ? link : path.join(resolvedParent, link);
+    return await resolveSegments(absolute, depth + 1);
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Server assembly.
+ *
+ * Deliberately transport-agnostic: this builds an `McpServer` with tools
+ * registered and hands it back. `cli.ts` attaches stdio; tests attach an
+ * in-memory transport. Keeping the two apart is what makes protocol-level
+ * tests possible without spawning a process, and leaves room to add a
+ * Streamable HTTP entry point later without touching tool code.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./config.js";
+/** Package identity reported during the MCP handshake. */
+export interface ServerIdentity {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Build a configured MCP server. Nothing is connected yet — call
+ * `server.connect(transport)`.
+ */
+export declare function createServer(config: ServerConfig, identity?: ServerIdentity): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,QAAQ,GAAE,cAAiC,GAC1C,SAAS,CAgCX"}

package/dist/server.js

@@ -0,0 +1,66 @@
+/**
+ * Server assembly.
+ *
+ * Deliberately transport-agnostic: this builds an `McpServer` with tools
+ * registered and hands it back. `cli.ts` attaches stdio; tests attach an
+ * in-memory transport. Keeping the two apart is what makes protocol-level
+ * tests possible without spawning a process, and leaves room to add a
+ * Streamable HTTP entry point later without touching tool code.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerPrompts, registerResources } from "./capabilities.js";
+import { formatToolError } from "./errors.js";
+import { selectTools } from "./tools/index.js";
+import { errorResult } from "./tools/result.js";
+/**
+ * Fallback identity for programmatic callers that do not supply one.
+ *
+ * Deliberately not a plausible version number: the executable reads the real
+ * one from the package manifest, so anything reporting `0.0.0-unknown` in a
+ * client's logs is an embedder that should pass its own identity.
+ */
+const DEFAULT_IDENTITY = {
+    name: "documonster",
+    version: "0.0.0-unknown"
+};
+/**
+ * Build a configured MCP server. Nothing is connected yet — call
+ * `server.connect(transport)`.
+ */
+export function createServer(config, identity = DEFAULT_IDENTITY) {
+    const server = new McpServer({ name: identity.name, version: identity.version }, {
+        instructions: "Document toolkit for Excel, Word, PDF, CSV and ZIP files. Plain paths read from the input root; writes go to a separate output root and are returned as @output/<path>, which later tools can read. Input files are never modified unless the operator explicitly enabled in-place writes. Call doc_inspect before reading any document, and read narrow ranges rather than whole files. Call documonster_help for detailed guidance.",
+        capabilities: { tools: {}, resources: {}, prompts: {} }
+    });
+    // Resources publish the help topics at stable URIs, and prompts encode the
+    // inspect-then-read-then-verify order that the tool descriptions can only hint
+    // at. Neither costs a slot in the model's tool list.
+    registerResources(server);
+    registerPrompts(server, config);
+    const context = { config };
+    for (const tool of selectTools(config)) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations })
+        }, async (args) => runTool(tool, args, context));
+    }
+    return server;
+}
+/**
+ * Invoke a tool, converting any throw into an `isError` result.
+ *
+ * A thrown exception would surface as a protocol-level failure, which tells
+ * the model nothing it can act on. An `isError` result carries the code and
+ * hint, which is what lets it correct itself and retry.
+ */
+async function runTool(tool, args, context) {
+    try {
+        return await tool.handler(args, context);
+    }
+    catch (error) {
+        return errorResult(formatToolError(error));
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAShD;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,eAAe;CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAoB,EACpB,QAAQ,GAAmB,gBAAgB;IAE3C,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,EAClD;QACE,YAAY,EACV,uaAAua;QACza,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;KACxD,CACF,CAAC;IAEF,2EAA2E;IAC3E,+EAA+E;IAC/E,qDAAqD;IACrD,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAgB,EAAE,MAAM,EAAE,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;SAC7E,EACD,KAAK,EAAE,IAA6B,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CACtE,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,OAAO,CACpB,IAAuB,EACvB,IAA6B,EAC7B,OAAoB;IAEpB,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,WAAW,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * `archive_read` — list or extract a ZIP/TAR archive.
+ *
+ * The entry point to most real work: documents arrive as email attachments and
+ * export bundles, and a model cannot open a binary container by itself. It is
+ * also where the security surface is widest, so three guards apply beyond the
+ * generic path sandbox:
+ *
+ * 1. **Traversal, including through existing links.** Entries are written one at
+ *    a time and every destination goes through `resolveInRoot`, so an entry name
+ *    with `..` is rejected *and* so is an entry whose path passes through a
+ *    symlink already sitting in the destination directory. Delegating to the
+ *    library's `extractTo` was not enough: it validates entry names against the
+ *    target directory but writes through a pre-existing `out/link -> /elsewhere`,
+ *    which was verified to escape the sandbox.
+ * 2. **Decompression bombs** — the archive file's own size is checked before it
+ *    is opened, and the declared uncompressed sizes before anything is written.
+ * 3. **Symlink and special entries** — never materialised. A `link ->
+ *    /etc/passwd` entry would otherwise leave a live escape hatch inside the
+ *    sandbox for a later tool to follow.
+ * 4. **Permissions** — extracted files get the process default rather than the
+ *    archive's mode bits, so an untrusted archive cannot produce something
+ *    executable or world-writable.
+ *
+ * Encryption is not reported when listing: `ArchiveEntryInfo` carries an
+ * `isEncrypted` flag at runtime but does not declare it, and this package reads
+ * only documented public surface. Encryption therefore surfaces as a failed
+ * extraction with a hint to pass `password`. (Worth declaring upstream.)
+ */
+export declare const archiveReadTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=archive-read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../../src/tools/archive-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAwBH,eAAO,MAAM,eAAe,wCAoN1B,CAAC"}