mcp-image-previewer 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# mcp-image-previewer
+
+An MCP (Model Context Protocol) server that previews base64-encoded images in a native GUI window using [Slint](https://slint.dev/).
+
+## Features
+
+- **Native GUI** — Slint-based window, no Python or external runtime needed
+- **Window reuse** — Same window updates in-place across multiple images
+- **Always-on-top** — Optionally pin the preview window above other windows
+- **Show/hide** — Toggle window visibility without losing state
+- **Format support** — PNG, JPEG, WebP, GIF, TIFF, etc. (via sharp)
+
+## Requirements
+
+- Node.js 18+
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "image-previewer": {
+      "command": "node",
+      "args": ["/path/to/mcp-image-previewer/dist/index.js"]
+    }
+  }
+}
+```
+
+### Tools
+
+#### `preview_image`
+
+Display a base64-encoded image in the viewer window.
+
+| Parameter  | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `data`    | string | Yes      | Base64-encoded image data |
+| `mimeType`| string | Yes      | MIME type (e.g. `image/png`, `image/jpeg`) |
+
+#### `show_window`
+
+Show or hide the preview window.
+
+| Parameter | Type    | Required | Description |
+|-----------|---------|----------|-------------|
+| `visible` | boolean | Yes      | `true` to show, `false` to hide |
+
+#### `stay_on_top`
+
+Set whether the preview window stays on top of other windows.
+
+| Parameter | Type    | Required | Description |
+|-----------|---------|----------|-------------|
+| `enabled` | boolean | Yes      | `true` to enable, `false` to disable |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import * as slint from "slint-ui";
+import { showImage, setStayOnTop, showWindow, hideWindow, cleanup, } from "./viewer.js";
+const server = new McpServer({
+    name: "mcp-image-previewer",
+    version: "0.1.0",
+});
+server.tool("preview_image", "Preview a base64-encoded image. Opens a GUI viewer window that is reused across calls.", {
+    data: z.string().describe("Base64-encoded image data"),
+    mimeType: z
+        .string()
+        .describe("MIME type of the image (e.g. image/png, image/jpeg)"),
+}, async ({ data, mimeType }) => {
+    try {
+        await showImage(data, mimeType);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Image displayed.",
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: `Preview failed: ${message}` },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("show_window", "Show or hide the image preview window.", {
+    visible: z.boolean().describe("true to show, false to hide"),
+}, async ({ visible }) => {
+    try {
+        if (visible) {
+            showWindow();
+        }
+        else {
+            hideWindow();
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Window ${visible ? "shown" : "hidden"}.`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: `Failed: ${message}` },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("stay_on_top", "Set whether the image preview window stays on top of other windows.", {
+    enabled: z.boolean().describe("true to enable always-on-top, false to disable"),
+}, async ({ enabled }) => {
+    try {
+        setStayOnTop(enabled);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Stay-on-top ${enabled ? "enabled" : "disabled"}.`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                { type: "text", text: `Failed: ${message}` },
+            ],
+            isError: true,
+        };
+    }
+});
+process.on("exit", cleanup);
+process.on("SIGINT", () => {
+    cleanup();
+    slint.quitEventLoop();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    cleanup();
+    slint.quitEventLoop();
+    process.exit(0);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Slint event loop merges with Node.js event loop at ~16ms intervals,
+    // so MCP stdio I/O continues to work while the GUI is running.
+    await slint.runEventLoop({ quitOnLastWindowClosed: false });
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/viewer.d.ts

@@ -0,0 +1,5 @@
+export declare function setStayOnTop(value: boolean): void;
+export declare function showImage(data: string, _mimeType: string): Promise<void>;
+export declare function showWindow(): void;
+export declare function hideWindow(): void;
+export declare function cleanup(): void;

package/dist/viewer.js

@@ -0,0 +1,71 @@
+import * as slint from "slint-ui";
+import sharp from "sharp";
+let component = null;
+let ui = null;
+function ensureUI() {
+    if (!ui) {
+        ui = slint.loadFile(new URL("../ui/main.slint", import.meta.url));
+    }
+    return ui;
+}
+function ensureWindow() {
+    const mod = ensureUI();
+    let needNew = !component;
+    if (!needNew) {
+        try {
+            needNew = !component.window.visible;
+        }
+        catch {
+            needNew = true;
+        }
+    }
+    if (needNew) {
+        const Ctor = mod.MainWindow;
+        component = new Ctor();
+        component.show();
+    }
+    return component;
+}
+export function setStayOnTop(value) {
+    const win = ensureWindow();
+    win.stay_on_top = value;
+}
+export async function showImage(data, _mimeType) {
+    const buf = Buffer.from(data, "base64");
+    const { data: rgba, info } = await sharp(buf)
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    const win = ensureWindow();
+    win.current_image = {
+        width: info.width,
+        height: info.height,
+        data: new Uint8ClampedArray(rgba.buffer, rgba.byteOffset, rgba.byteLength),
+    };
+    win.image_info = `${info.width} x ${info.height}`;
+}
+export function showWindow() {
+    ensureWindow();
+}
+export function hideWindow() {
+    if (component) {
+        try {
+            component.hide();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+export function cleanup() {
+    if (component) {
+        try {
+            component.hide();
+        }
+        catch {
+            // ignore errors during cleanup
+        }
+        component = null;
+    }
+}
+//# sourceMappingURL=viewer.js.map

package/dist/viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.js","sourceRoot":"","sources":["../src/viewer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,UAAU,CAAC;AAClC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,IAAI,SAAS,GAA+B,IAAI,CAAC;AACjD,IAAI,EAAE,GAA+B,IAAI,CAAC;AAE1C,SAAS,QAAQ;IACf,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,KAAK,CAAC,QAAQ,CACjB,IAAI,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CACtB,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,IAAI,OAAO,GAAG,CAAC,SAAS,CAAC;IACzB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,GAAG,CAAE,SAAiC,CAAC,MAAM,CAAC,OAAO,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,GAAG,CAAC,UAA2C,CAAC;QAC7D,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QACtB,SAAiC,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,SAAgC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,SAAiB;IAEjB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;SAC1C,WAAW,EAAE;SACb,GAAG,EAAE;SACL,QAAQ,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,GAAG,CAAC,aAAa,GAAG;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC;KAC3E,CAAC;IACF,GAAG,CAAC,UAAU,GAAG,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,YAAY,EAAE,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC;YACF,SAAiC,CAAC,IAAI,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC;YACF,SAAiC,CAAC,IAAI,EAAE,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mcp-image-previewer",
+  "version": "0.1.0",
+  "description": "MCP server for previewing base64-encoded images from other MCP servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-image-previewer": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "sharp": "^0.34.5",
+    "slint-ui": "^1.14.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}