@ingcreators/annot-mcp 0.1.0

package/dist/io/png-dimensions.d.ts

@@ -0,0 +1,16 @@
+export interface PngDimensions {
+    width: number;
+    height: number;
+}
+export declare class InvalidPngError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse the width / height fields from a PNG IHDR chunk. Throws
+ * `InvalidPngError` if the input doesn't start with a valid PNG
+ * signature or the IHDR chunk type is missing.
+ *
+ * Accepts any byte source with a `BufferSource`-compatible shape
+ * (`Uint8Array`, `ArrayBuffer`, Node `Buffer`).
+ */
+export declare function readPngDimensions(bytes: Uint8Array): PngDimensions;

package/dist/io/read-image.d.ts

@@ -0,0 +1,24 @@
+import { PngDimensions } from './png-dimensions.js';
+export interface ResolvedImage {
+    /** Raw PNG bytes. */
+    bytes: Uint8Array;
+    /** `data:image/png;base64,...` form. Suitable for the annotator. */
+    dataUrl: string;
+    /** Width / height parsed from the IHDR chunk. */
+    dimensions: PngDimensions;
+}
+export declare class InvalidImageInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve an `image` field from a tool call. Accepts either:
+ *
+ *   - a `data:image/png;base64,...` URL
+ *   - an absolute filesystem path to a PNG file
+ *
+ * Relative paths are rejected — agents are required to pass
+ * absolute paths so the resolution doesn't depend on the MCP
+ * server's current working directory (which the agent has no
+ * control over).
+ */
+export declare function resolveImageInput(input: string): Promise<ResolvedImage>;

package/dist/redact/burn.d.ts

@@ -0,0 +1,14 @@
+import { BBox, RedactStyle } from '../dsl/types.js';
+export interface RedactRegion {
+    bbox: BBox;
+    style?: RedactStyle;
+    color?: string;
+}
+/**
+ * Burn redactions into a PNG buffer. Returns a new PNG with the
+ * regions painted over the source pixels.
+ *
+ * Regions are processed in order; later regions overlay earlier
+ * ones (no automatic deduplication or alpha-blending).
+ */
+export declare function burnRedactions(pngBytes: Uint8Array, regions: readonly RedactRegion[]): Promise<Uint8Array>;

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+import { Annotator, AnnotatorOptions } from '@ingcreators/annot-annotator';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { BrowserPool } from './browser/pool.js';
+export interface CreateServerOptions {
+    /**
+     * Override the version reported in the MCP `initialize` response.
+     * Defaults to the package version baked at build time. Mostly
+     * useful for tests that want a deterministic version string.
+     */
+    version?: string;
+    /**
+     * Inject a pre-built annotator. Tests pass a stub here to avoid
+     * loading resvg-js's native rasteriser; production callers omit
+     * the field and let the server construct one with default
+     * options.
+     */
+    annotator?: Annotator;
+    /**
+     * Forwarded to `createAnnotator()` when `annotator` is omitted.
+     * Lets the host opt into system fonts or register a custom font
+     * set without subclassing the server.
+     */
+    annotatorOptions?: AnnotatorOptions;
+    /**
+     * Inject a pre-built browser pool. Tests pass a stub to skip the
+     * Chromium launch; production callers omit the field and let
+     * the server construct a `createChromiumPool()` lazily.
+     */
+    pool?: BrowserPool;
+}
+/**
+ * Construct an MCP server instance with the Annot tool surface.
+ */
+export declare function createServer(options?: CreateServerOptions): Server;

package/dist/tools/annotate-screenshot.d.ts

@@ -0,0 +1,293 @@
+import { Annotator } from '@ingcreators/annot-annotator';
+export declare const ANNOTATE_SCREENSHOT_TOOL_NAME = "annot_annotate_screenshot";
+/**
+ * Tool descriptor for the MCP `tools/list` response. The
+ * `inputSchema` is shipped as a plain JSON Schema literal; the
+ * MCP SDK runs Ajv on the agent's payload before our handler sees
+ * it.
+ */
+export declare const annotateScreenshotTool: {
+    readonly name: "annot_annotate_screenshot";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["image", "annotations"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly image: {
+                readonly type: "string";
+                readonly description: string;
+            };
+            readonly annotations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly $ref: "#/$defs/BboxAnnotation";
+                };
+                readonly description: string;
+            };
+            readonly output: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly $defs: {
+            readonly BboxAnnotation: {
+                oneOf: ({
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        bbox: {
+                            $ref: string;
+                        };
+                        intent: {
+                            $ref: string;
+                        };
+                        stroke: {
+                            type: string;
+                        };
+                        strokeWidth: {
+                            type: string;
+                            minimum: number;
+                        };
+                        fill: {
+                            type: string;
+                        };
+                        color: {
+                            type: string;
+                        };
+                    };
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        center: {
+                            $ref: string;
+                        };
+                        radius: {
+                            type: string;
+                            minimum: number;
+                        };
+                        intent: {
+                            $ref: string;
+                        };
+                        stroke: {
+                            type: string;
+                        };
+                        strokeWidth: {
+                            type: string;
+                            minimum: number;
+                        };
+                        fill: {
+                            type: string;
+                        };
+                        color: {
+                            type: string;
+                        };
+                    };
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        from: {
+                            $ref: string;
+                        };
+                        to: {
+                            $ref: string;
+                        };
+                        intent: {
+                            $ref: string;
+                        };
+                        stroke: {
+                            type: string;
+                        };
+                        strokeWidth: {
+                            type: string;
+                            minimum: number;
+                        };
+                        color: {
+                            type: string;
+                        };
+                    };
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        at: {
+                            $ref: string;
+                        };
+                        content: {
+                            type: string;
+                        };
+                        fontSize: {
+                            type: string;
+                            minimum: number;
+                        };
+                        anchor: {
+                            type: string;
+                            enum: string[];
+                        };
+                        intent: {
+                            $ref: string;
+                        };
+                        color: {
+                            type: string;
+                        };
+                    };
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        at: {
+                            $ref: string;
+                        };
+                        targetBbox: {
+                            $ref: string;
+                        };
+                        content: {
+                            type: string;
+                        };
+                        intent: {
+                            $ref: string;
+                        };
+                        stroke: {
+                            type: string;
+                        };
+                        color: {
+                            type: string;
+                        };
+                    };
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        svgFragment: {
+                            type: string;
+                        };
+                    };
+                })[];
+            };
+            readonly BBox: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    x: {
+                        type: string;
+                    };
+                    y: {
+                        type: string;
+                    };
+                    width: {
+                        type: string;
+                        minimum: number;
+                    };
+                    height: {
+                        type: string;
+                        minimum: number;
+                    };
+                };
+            };
+            readonly Point: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    x: {
+                        type: string;
+                    };
+                    y: {
+                        type: string;
+                    };
+                };
+            };
+            readonly Intent: {
+                type: string;
+                enum: string[];
+            };
+            readonly AnnotationStyle: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    intent: {
+                        $ref: string;
+                    };
+                    stroke: {
+                        type: string;
+                    };
+                    strokeWidth: {
+                        type: string;
+                        minimum: number;
+                    };
+                    fill: {
+                        type: string;
+                    };
+                    color: {
+                        type: string;
+                    };
+                };
+            };
+            readonly Locator: {
+                type: string;
+                minLength: number;
+            };
+        };
+    };
+};
+/** Tool dependencies — injected at server construction time. */
+export interface AnnotateScreenshotDeps {
+    annotator: Annotator;
+}
+/** Raw, pre-validation tool input. The MCP SDK has already run the
+ *  JSON schema check by the time we see this, but we still
+ *  defensively narrow before reaching into fields. */
+interface AnnotateScreenshotInput {
+    image?: unknown;
+    annotations?: unknown;
+    output?: unknown;
+}
+/** MCP `tools/call` result content block. */
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/**
+ * Subset of the MCP SDK's `CallToolResult` we actually emit. The
+ * SDK's full type also covers async-task responses (added in MCP
+ * v2025-06-19); our handler always returns the synchronous content
+ * shape, so we narrow here for clarity. Dispatch in `server.ts`
+ * casts back up to the SDK union at the boundary.
+ */
+export interface AnnotateToolResult {
+    content: ContentBlock[];
+    isError?: boolean;
+}
+export declare function handleAnnotateScreenshot(input: AnnotateScreenshotInput, deps: AnnotateScreenshotDeps): Promise<AnnotateToolResult>;
+export {};