@documonster/mcp 0.10.0 → 0.11.0

package/dist/tools/help.js.map

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

package/dist/tools/image.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Image sources, shared by every tool that can put a picture somewhere.
+ *
+ * There is exactly one shape for "which image", and it routes on the file
+ * extension rather than on a discriminator the caller has to get right:
+ *
+ * - `from: "logo.png"` — a `.png` / `.jpg` / `.gif` file, embedded as it is.
+ * - `from: "design.md"` — a Markdown file's ```mermaid fence, drawn server-side.
+ * - `from: "flow.mmd"` — a diagram file, drawn server-side.
+ * - `source: "flowchart LR\n A --> B"` — Mermaid text, drawn server-side.
+ *
+ * That ordering is the point. A Mermaid diagram is *one source of an image*, not a
+ * separate feature: a tool that could only place diagrams would be a
+ * mermaid-shaped hole where generic image support belongs, and a caller with a
+ * PNG on disk would have no way in. The three raster formats are the three
+ * `Image.add` accepts, which is what makes the workbook path total.
+ *
+ * The natural size of a raster file has to be *read*, because two of the three
+ * destinations need it. A worksheet anchored to a single cell needs pixels; a Word
+ * template placeholder needs EMU and has no default at all. Guessing would place a
+ * portrait photograph as a square, and the model would never see it — so the
+ * dimension readers below fail loudly on a file they cannot parse rather than
+ * returning a 1×1 placeholder.
+ */
+import type { MermaidDiagram } from "documonster/mermaid";
+import { z } from "zod";
+import type { ServerConfig } from "../config.js";
+/** Raster formats a workbook and a Word document both accept. */
+export type RasterMediaType = "png" | "jpeg" | "gif";
+/**
+ * Tracks what one tool call has spent, so the aggregate caps mean something.
+ *
+ * Threaded explicitly rather than kept in module state: two calls must never share
+ * a budget, and a module-level counter is exactly how that goes wrong under
+ * concurrency.
+ */
+export interface ImageBudget {
+    count: number;
+    bytes: number;
+    pixels: number;
+}
+/** A fresh budget for one tool call. */
+export declare function newImageBudget(): ImageBudget;
+/**
+ * Where an image comes from and how big it should be.
+ *
+ * Spread into a tool's schema rather than nested, so the fields read as the
+ * tool's own and a caller does not have to discover an extra level of object.
+ */
+export declare const imageSourceShape: {
+    readonly from: z.ZodOptional<z.ZodString>;
+    readonly source: z.ZodOptional<z.ZodString>;
+    readonly index: z.ZodOptional<z.ZodNumber>;
+    readonly width: z.ZodOptional<z.ZodNumber>;
+    readonly height: z.ZodOptional<z.ZodNumber>;
+    readonly altText: z.ZodOptional<z.ZodString>;
+    readonly theme: z.ZodOptional<z.ZodEnum<{
+        dark: "dark";
+        default: "default";
+        neutral: "neutral";
+    }>>;
+    readonly background: z.ZodOptional<z.ZodString>;
+};
+/** The parsed form of {@link imageSourceShape}. */
+export interface ImageSourceArgs {
+    readonly from?: string;
+    readonly source?: string;
+    readonly index?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly altText?: string;
+    readonly theme?: "default" | "dark" | "neutral";
+    readonly background?: string;
+}
+export interface ResolvedImage {
+    readonly bytes: Uint8Array;
+    readonly mediaType: RasterMediaType;
+    /** Display size in points, after `width`/`height` and any cap were applied. */
+    readonly width: number;
+    readonly height: number;
+    /** Suggested `word/media` / `xl/media` file name. */
+    readonly fileName: string;
+    readonly altText: string;
+    /** How to name the source in a report. */
+    readonly origin: string;
+    /**
+     * Present when the image was drawn from Mermaid, so the tool can report what
+     * the parser recognised — the only way a model can check a picture it cannot see.
+     */
+    readonly diagram?: MermaidDiagram;
+}
+export interface ResolveImageOptions {
+    /** Shrink to at most this many points wide, keeping the aspect ratio. */
+    readonly maxWidthPoints?: number;
+    /** Running total for the call, so the aggregate caps apply across images. */
+    readonly budget?: ImageBudget;
+}
+/**
+ * Turn an image source into bytes and a display size.
+ *
+ * @throws {McpToolError} `invalid_input` for a missing or ambiguous source, an
+ *   unsupported extension, or a raster file whose header cannot be read.
+ */
+export declare function resolveImageSource(config: ServerConfig, args: ImageSourceArgs, options?: ResolveImageOptions): Promise<ResolvedImage>;
+/** Display size in EMU, the unit Word measures a drawing in. */
+export declare function toEmu(points: number): number;
+/** Display size in CSS pixels, the unit a worksheet anchor's `ext` is in. */
+export declare function toCssPixels(points: number): number;
+/** What {@link tryReadImageHeader} found, including the size it would be placed at. */
+export interface ProbedImage {
+    readonly mediaType: RasterMediaType;
+    readonly width: number;
+    readonly height: number;
+    readonly dpi?: number;
+    /** The size it would occupy when placed, in points. */
+    readonly points: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * What is wrong with the file, when anything is.
+     *
+     * Reported rather than thrown, because the two callers want opposite things from
+     * the same finding: placing must refuse a damaged file, while inspecting exists to
+     * *say* it is damaged. Leaving it out made the advice the placement tools give —
+     * "run doc_inspect on it" — lead to a report that the file was fine.
+     */
+    readonly damage?: string;
+}
+/**
+ * Read a raster header without throwing, for `doc_inspect`.
+ *
+ * Identification and placement want the same parse but different failure
+ * behaviour: placing must refuse a file it cannot size, whereas inspecting exists
+ * precisely to *report* that it cannot be sized. Sharing the parsers keeps the two
+ * answers consistent — a file `doc_inspect` calls unreadable is exactly one the
+ * placement tools reject.
+ */
+export declare function tryReadImageHeader(bytes: Uint8Array): ProbedImage | undefined;
+/**
+ * Describe a placed image for a tool report.
+ *
+ * The diagram line is the load-bearing part: for a Mermaid source the model has
+ * no other way to check that the picture says what it meant.
+ */
+export declare function describePlacedImage(image: ResolvedImage, where: string): string;
+//# sourceMappingURL=image.d.ts.map

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

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