@ingcreators/annot-mcp 0.1.1 → 0.3.0

package/dist/io/encode-output.d.ts

@@ -0,0 +1,29 @@
+import { EncodeOptions } from '@ingcreators/annot-annotator';
+export interface EncodedToolOutput {
+    bytes: Uint8Array;
+    mimeType: "image/png" | "image/jpeg";
+    chosen: "png" | "jpeg";
+    width: number;
+    height: number;
+    reason?: string;
+}
+/**
+ * Apply the agent-provided `encode` options to a PNG byte stream
+ * the tool just produced. Returns the original bytes verbatim
+ * when no options are passed (the fast path for back-compat).
+ */
+export declare function applyEncodeOptions(pngBytes: Uint8Array, dimensions: {
+    width: number;
+    height: number;
+}, encode: Partial<EncodeOptions> | undefined): Promise<EncodedToolOutput>;
+/**
+ * Apply the agent-provided `encode` options to RGBA bytes (rather
+ * than already-encoded PNG bytes). Used by the annotate tools that
+ * go through `annotator.toEncoded()` directly — but currently
+ * unused because the tools opt for the "encode the PNG output"
+ * path via {@link applyEncodeOptions} for code uniformity.
+ *
+ * Exported for power callers who want to drive the pipeline
+ * themselves.
+ */
+export { decodeAndEncodeImage } from '@ingcreators/annot-annotator';

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

@@ -29,6 +29,10 @@ export declare const annotateScreenshotTool: {
                 readonly type: "string";
                 readonly description: string;
             };
+            readonly encode: {
+                readonly $ref: "#/$defs/EncodeOptions";
+                readonly description: string;
+            };
         };
         readonly $defs: {
             readonly BboxAnnotation: {
@@ -190,6 +194,38 @@ export declare const annotateScreenshotTool: {
                     };
                 })[];
             };
+            readonly EncodeOptions: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    format: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    saveSizePreset: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartFallback: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartColorThreshold: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    jpegPercent: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                        description: string;
+                    };
+                };
+            };
             readonly Locator: {
                 type: string;
                 minLength: number;
@@ -268,6 +304,7 @@ interface AnnotateScreenshotInput {
     image?: unknown;
     annotations?: unknown;
     output?: unknown;
+    encode?: unknown;
 }
 /** MCP `tools/call` result content block. */
 type ContentBlock = {

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

@@ -58,6 +58,10 @@ export declare const annotateUrlTool: {
                 readonly type: "string";
                 readonly description: string;
             };
+            readonly encode: {
+                readonly $ref: "#/$defs/EncodeOptions";
+                readonly description: string;
+            };
         };
         readonly $defs: {
             readonly LocatorAnnotation: {
@@ -259,6 +263,38 @@ export declare const annotateUrlTool: {
                     };
                 })[];
             };
+            readonly EncodeOptions: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    format: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    saveSizePreset: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartFallback: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartColorThreshold: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    jpegPercent: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                        description: string;
+                    };
+                };
+            };
             readonly Locator: {
                 type: string;
                 minLength: number;
@@ -337,6 +373,7 @@ interface AnnotateUrlInput {
     fullPage?: unknown;
     waitFor?: unknown;
     output?: unknown;
+    encode?: unknown;
 }
 export declare function handleAnnotateUrl(input: AnnotateUrlInput, deps: AnnotateUrlDeps): Promise<AnnotateToolResult>;
 export {};

package/dist/tools/aria-snapshot.d.ts

@@ -0,0 +1,73 @@
+import { BrowserPool } from '../browser/pool.js';
+import { AnnotateToolResult } from './annotate-screenshot.js';
+export declare const ARIA_SNAPSHOT_TOOL_NAME = "annot_aria_snapshot";
+export declare const ariaSnapshotTool: {
+    readonly name: "annot_aria_snapshot";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["url"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Page URL to snapshot.";
+            };
+            readonly viewport: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly width: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 1280;
+                    };
+                    readonly height: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 800;
+                    };
+                    readonly deviceScaleFactor: {
+                        readonly type: "number";
+                        readonly minimum: 0.1;
+                        readonly default: 1;
+                    };
+                };
+                readonly description: "Viewport size. Default 1280×800 at 1× device pixel ratio.";
+            };
+            readonly waitFor: {
+                readonly type: "string";
+                readonly enum: readonly ["load", "domcontentloaded", "networkidle"];
+                readonly default: "load";
+                readonly description: "Page event to await before snapshotting.";
+            };
+            readonly rootSelector: {
+                readonly type: "string";
+                readonly default: "body";
+                readonly description: string;
+            };
+            readonly timeout: {
+                readonly type: "integer";
+                readonly minimum: 0;
+                readonly description: string;
+            };
+            readonly output: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+    };
+};
+export interface AriaSnapshotToolDeps {
+    pool: BrowserPool;
+}
+export interface AriaSnapshotToolInput {
+    url?: unknown;
+    viewport?: unknown;
+    waitFor?: unknown;
+    rootSelector?: unknown;
+    timeout?: unknown;
+    output?: unknown;
+}
+export declare function handleAriaSnapshot(args: AriaSnapshotToolInput, deps: AriaSnapshotToolDeps): Promise<AnnotateToolResult>;

package/dist/tools/compare-screenshots.d.ts

@@ -32,6 +32,43 @@ export declare const compareScreenshotsTool: {
             readonly output: {
                 readonly type: "string";
             };
+            readonly encode: {
+                readonly $ref: "#/$defs/EncodeOptions";
+            };
+        };
+        readonly $defs: {
+            readonly EncodeOptions: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    format: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    saveSizePreset: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartFallback: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartColorThreshold: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    jpegPercent: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                        description: string;
+                    };
+                };
+            };
         };
     };
 };
@@ -44,6 +81,7 @@ interface CompareScreenshotsInput {
     threshold?: unknown;
     includeChangeList?: unknown;
     output?: unknown;
+    encode?: unknown;
 }
 export declare function handleCompareScreenshots(input: CompareScreenshotsInput, deps: CompareScreenshotsDeps): Promise<AnnotateToolResult>;
 export {};

package/dist/tools/draft-screen-spec.d.ts

@@ -0,0 +1,75 @@
+import { BrowserPool } from '../browser/pool.js';
+import { AnnotateToolResult } from './annotate-screenshot.js';
+export declare const DRAFT_SCREEN_SPEC_TOOL_NAME = "annot_draft_screen_spec";
+export declare const draftScreenSpecTool: {
+    readonly name: "annot_draft_screen_spec";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["url", "id"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Page URL to draft from.";
+            };
+            readonly id: {
+                readonly type: "string";
+                readonly description: "Screen ID — used as the MDX frontmatter `annot.id` and as the `<Screen id>` prop.";
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly description: "Optional screen title (frontmatter `annot.title`).";
+            };
+            readonly book: {
+                readonly type: "string";
+                readonly description: "Optional book name (frontmatter `xlsx.book`).";
+            };
+            readonly screenImageSrc: {
+                readonly type: "string";
+                readonly default: "./shots/{id}.png";
+                readonly description: string;
+            };
+            readonly viewport: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly width: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 1280;
+                    };
+                    readonly height: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 800;
+                    };
+                    readonly deviceScaleFactor: {
+                        readonly type: "number";
+                        readonly minimum: 0.1;
+                        readonly default: 1;
+                    };
+                };
+            };
+            readonly waitFor: {
+                readonly type: "string";
+                readonly enum: readonly ["load", "domcontentloaded", "networkidle"];
+                readonly default: "load";
+            };
+        };
+    };
+};
+export interface DraftScreenSpecToolDeps {
+    pool: BrowserPool;
+}
+export interface DraftScreenSpecToolInput {
+    url?: unknown;
+    id?: unknown;
+    title?: unknown;
+    book?: unknown;
+    screenImageSrc?: unknown;
+    viewport?: unknown;
+    waitFor?: unknown;
+}
+export declare function handleDraftScreenSpec(args: DraftScreenSpecToolInput, deps: DraftScreenSpecToolDeps): Promise<AnnotateToolResult>;

package/dist/tools/propose-drift-fixes.d.ts

@@ -0,0 +1,64 @@
+import { BrowserPool } from '../browser/pool.js';
+import { AnnotateToolResult } from './annotate-screenshot.js';
+export declare const PROPOSE_DRIFT_FIXES_TOOL_NAME = "annot_propose_drift_fixes";
+export declare const proposeDriftFixesTool: {
+    readonly name: "annot_propose_drift_fixes";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["mdxPath", "url"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly mdxPath: {
+                readonly type: "string";
+                readonly description: "Absolute or cwd-relative path to the `.mdx` file with `annot:` frontmatter.";
+            };
+            readonly url: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "URL to navigate to for the live snapshot.";
+            };
+            readonly screenId: {
+                readonly type: "string";
+                readonly description: "Optional `<Screen id>` filter. Default: run drift against every screen in the MDX.";
+            };
+            readonly viewport: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly width: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 1280;
+                    };
+                    readonly height: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly default: 800;
+                    };
+                    readonly deviceScaleFactor: {
+                        readonly type: "number";
+                        readonly minimum: 0.1;
+                        readonly default: 1;
+                    };
+                };
+            };
+            readonly waitFor: {
+                readonly type: "string";
+                readonly enum: readonly ["load", "domcontentloaded", "networkidle"];
+                readonly default: "load";
+            };
+        };
+    };
+};
+export interface ProposeDriftFixesToolDeps {
+    pool: BrowserPool;
+}
+export interface ProposeDriftFixesToolInput {
+    mdxPath?: unknown;
+    url?: unknown;
+    screenId?: unknown;
+    viewport?: unknown;
+    waitFor?: unknown;
+}
+export declare function handleProposeDriftFixes(args: ProposeDriftFixesToolInput, deps: ProposeDriftFixesToolDeps): Promise<AnnotateToolResult>;

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

@@ -21,6 +21,10 @@ export declare const redactScreenshotTool: {
             readonly output: {
                 readonly type: "string";
             };
+            readonly encode: {
+                readonly $ref: "#/$defs/EncodeOptions";
+                readonly description: string;
+            };
         };
         readonly $defs: {
             readonly BboxRedactRegion: {
@@ -40,6 +44,38 @@ export declare const redactScreenshotTool: {
                     };
                 };
             };
+            readonly EncodeOptions: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    format: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    saveSizePreset: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartFallback: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartColorThreshold: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    jpegPercent: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                        description: string;
+                    };
+                };
+            };
             readonly Locator: {
                 type: string;
                 minLength: number;
@@ -111,6 +147,7 @@ interface RedactScreenshotInput {
     image?: unknown;
     regions?: unknown;
     output?: unknown;
+    encode?: unknown;
 }
 export declare function handleRedactScreenshot(input: RedactScreenshotInput): Promise<AnnotateToolResult>;
 export {};

package/dist/tools/redact-url.d.ts

@@ -53,6 +53,9 @@ export declare const redactUrlTool: {
             readonly output: {
                 readonly type: "string";
             };
+            readonly encode: {
+                readonly $ref: "#/$defs/EncodeOptions";
+            };
         };
         readonly $defs: {
             readonly LocatorRedactRegion: {
@@ -77,6 +80,38 @@ export declare const redactUrlTool: {
                     required: string[];
                 }[];
             };
+            readonly EncodeOptions: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    format: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    saveSizePreset: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartFallback: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    smartColorThreshold: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    jpegPercent: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                        description: string;
+                    };
+                };
+            };
             readonly Locator: {
                 type: string;
                 minLength: number;
@@ -154,6 +189,7 @@ interface RedactUrlInput {
     fullPage?: unknown;
     waitFor?: unknown;
     output?: unknown;
+    encode?: unknown;
 }
 export declare function handleRedactUrl(input: RedactUrlInput, deps: RedactUrlDeps): Promise<AnnotateToolResult>;
 export type RedactRegionStyle = RedactStyle;

package/dist/tools/translate-screen-spec.d.ts

@@ -0,0 +1,31 @@
+import { AnnotateToolResult } from './annotate-screenshot.js';
+export declare const TRANSLATE_SCREEN_SPEC_TOOL_NAME = "annot_translate_screen_spec";
+export declare const translateScreenSpecTool: {
+    readonly name: "annot_translate_screen_spec";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["mdxPath", "targetLocale"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly mdxPath: {
+                readonly type: "string";
+                readonly description: "Absolute or cwd-relative path to the source `.mdx`.";
+            };
+            readonly sourceLocale: {
+                readonly type: "string";
+                readonly description: string;
+            };
+            readonly targetLocale: {
+                readonly type: "string";
+                readonly description: "BCP-47 locale tag of the locale to produce (e.g. `en-US`).";
+            };
+        };
+    };
+};
+export interface TranslateScreenSpecToolInput {
+    mdxPath?: unknown;
+    sourceLocale?: unknown;
+    targetLocale?: unknown;
+}
+export declare function handleTranslateScreenSpec(args: TranslateScreenSpecToolInput): Promise<AnnotateToolResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Model Context Protocol server exposing the Annot headless annotator as agent-callable tools. Drop into Claude Desktop / Claude Code / Cursor and let an AI agent compose Annot with @playwright/mcp + GitHub MCP for one-turn bug-report autopilot, visual-diff PR review, and locator-first annotation workflows.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -46,17 +46,18 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^25.9.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
-    "vite": "^6.4.2",
-    "vite-plugin-dts": "^5.0.0"
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@napi-rs/canvas": "^0.1.0",
+    "@napi-rs/canvas": "^1.0.0",
     "pixelmatch": "^7.1.0",
     "playwright-core": "^1.50.0",
-    "@ingcreators/annot-annotator": "0.2.0"
+    "@ingcreators/annot-annotator": "0.5.0",
+    "@ingcreators/annot-product-docs": "0.2.0"
   },
   "scripts": {
     "build": "vite build",