mcp-openmockup 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+# Optional: override the OpenMockup URL (defaults to https://openmockup.dev)
+# OPENMOCKUP_URL=https://openmockup.dev
+
+# Required only for project tools (list_projects, get_project, create_project)
+OPENMOCKUP_EMAIL=you@example.com
+OPENMOCKUP_PASSWORD=yourpassword
+OPENMOCKUP_SUPABASE_URL=https://your-project.supabase.co
+OPENMOCKUP_SUPABASE_ANON_KEY=your-anon-key

package/README.md

@@ -0,0 +1,60 @@
+# mcp-openmockup
+
+MCP server for [OpenMockup](https://openmockup.dev) — generate 3D device mockup images (iPhone, MacBook) from any AI agent.
+
+No local OpenMockup install required. Rendering runs against `https://openmockup.dev`.
+
+## Install
+
+Add to your MCP config (`~/.cursor/mcp.json`, `~/.claude/.mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "mcp-openmockup": {
+      "command": "npx",
+      "args": ["-y", "mcp-openmockup"]
+    }
+  }
+}
+```
+
+Requires [Node.js](https://nodejs.org/) 18+. On first render, Playwright downloads Chromium (~150 MB, one-time).
+
+## Tools
+
+### Render (no auth)
+
+| Tool | Description |
+|------|-------------|
+| `render_mockup` | Single device mockup → PNG |
+| `render_mockup_multi` | Multiple devices in one scene → PNG |
+
+Pass `image_url` or `image_data` (base64). Optional: `device` (`phone`/`mac`), `device_color`, `bg_color`, `device_rotation`, `zoom`, `transparent`, `width`, `height`.
+
+### Projects (optional auth)
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List saved projects |
+| `get_project` | Get project by UUID |
+| `create_project` | Create empty project |
+
+Requires env vars:
+
+```
+OPENMOCKUP_EMAIL=
+OPENMOCKUP_PASSWORD=
+OPENMOCKUP_SUPABASE_URL=
+OPENMOCKUP_SUPABASE_ANON_KEY=
+```
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENMOCKUP_URL` | `https://openmockup.dev` | Override renderer URL |
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+import { type Page } from 'playwright-chromium';
+export declare function getPage(): Promise<Page>;
+export declare function closeBrowser(): Promise<void>;

package/dist/browser.js

@@ -0,0 +1,28 @@
+import { chromium } from 'playwright-chromium';
+const OPENMOCKUP_URL = process.env.OPENMOCKUP_URL ?? 'https://openmockup.dev';
+let browser = null;
+let page = null;
+export async function getPage() {
+    if (!browser || !browser.isConnected()) {
+        browser = await chromium.launch({
+            args: ['--no-sandbox', '--disable-setuid-sandbox'],
+        });
+    }
+    if (!page || page.isClosed()) {
+        page = await browser.newPage();
+        await page.setViewportSize({ width: 1440, height: 900 });
+        await page.goto(`${OPENMOCKUP_URL}?headless`, { waitUntil: 'networkidle' });
+        await page.waitForFunction(() => window.__rendererReady === true, {
+            timeout: 30_000,
+        });
+    }
+    return page;
+}
+export async function closeBrowser() {
+    await browser?.close();
+    browser = null;
+    page = null;
+}
+process.on('exit', () => void closeBrowser());
+process.on('SIGINT', async () => { await closeBrowser(); process.exit(0); });
+process.on('SIGTERM', async () => { await closeBrowser(); process.exit(0); });

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { renderMockup, renderMockupMulti } from './render.js';
+import { listProjects, getProject, createProject } from './projects.js';
+const server = new Server({ name: 'mcp-openmockup', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'render_mockup',
+            description: 'Render a 3D device mockup image (iPhone or MacBook) with a screenshot on the screen. Returns a PNG image. No auth required.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    image_url: {
+                        type: 'string',
+                        description: 'Public URL of the screenshot to display on the device screen',
+                    },
+                    image_data: {
+                        type: 'string',
+                        description: 'Base64-encoded image (PNG or JPEG). Use this OR image_url.',
+                    },
+                    device: {
+                        type: 'string',
+                        enum: ['phone', 'mac'],
+                        default: 'phone',
+                        description: 'Device type: iPhone (phone) or MacBook (mac)',
+                    },
+                    device_color: {
+                        type: 'string',
+                        description: 'Hex color for the device frame. iPhone 17 colors: #DFCEEA (Lavender), #96AED1 (Mist Blue), #A9B689 (Sage), #353839 (Black), #F5F5F5 (White). iPhone 17 Pro: #32374A (Deep Blue), #F77E2D (Cosmic Orange), #F5F5F5 (Silver).',
+                    },
+                    bg_color: {
+                        type: 'string',
+                        description: 'Background color (hex) or CSS gradient. E.g. "#0a0a0a", "#ffffff", "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"',
+                    },
+                    device_rotation: {
+                        type: 'array',
+                        items: { type: 'number' },
+                        minItems: 3,
+                        maxItems: 3,
+                        description: '[x, y, z] rotation in radians. E.g. [0, 0.3, 0] for a slight Y-axis rotation.',
+                    },
+                    zoom: {
+                        type: 'number',
+                        description: 'Camera zoom. 1 = default, >1 = closer, <1 = wider. Range 0.3–3.',
+                    },
+                    camera_offset_x: {
+                        type: 'number',
+                        description: 'Horizontal camera offset. Negative moves camera left (shows more right edge).',
+                    },
+                    camera_offset_y: {
+                        type: 'number',
+                        description: 'Vertical camera offset. Negative = lower camera (hero/contrapicado angle).',
+                    },
+                    camera_roll: {
+                        type: 'number',
+                        description: 'Camera roll in radians. 0 = upright, 1.5708 ≈ 90°.',
+                    },
+                    transparent: {
+                        type: 'boolean',
+                        description: 'Render with transparent background (alpha PNG). Ignores bg_color.',
+                    },
+                    width: {
+                        type: 'number',
+                        description: 'Output PNG width in pixels. Default: 1440.',
+                    },
+                    height: {
+                        type: 'number',
+                        description: 'Output PNG height in pixels. Default: 2880.',
+                    },
+                },
+            },
+        },
+        {
+            name: 'render_mockup_multi',
+            description: 'Render a scene with multiple 3D device mockups side by side. Returns a PNG image. No auth required.',
+            inputSchema: {
+                type: 'object',
+                required: ['devices'],
+                properties: {
+                    devices: {
+                        type: 'array',
+                        description: 'List of devices to include in the scene (1–4 recommended)',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                image_url: {
+                                    type: 'string',
+                                    description: 'Public URL of the screenshot for this device',
+                                },
+                                image_data: {
+                                    type: 'string',
+                                    description: 'Base64 image data for this device',
+                                },
+                                kind: {
+                                    type: 'string',
+                                    enum: ['phone', 'mac'],
+                                    default: 'phone',
+                                },
+                                device_color: { type: 'string', description: 'Hex frame color' },
+                                device_rotation: {
+                                    type: 'array',
+                                    items: { type: 'number' },
+                                    minItems: 3,
+                                    maxItems: 3,
+                                    description: '[x, y, z] in radians',
+                                },
+                                position_x: {
+                                    type: 'number',
+                                    description: 'Horizontal position in scene units. 0 = center, ±14 = adjacent devices.',
+                                },
+                                position_y: {
+                                    type: 'number',
+                                    description: 'Vertical position in scene units.',
+                                },
+                            },
+                        },
+                    },
+                    bg_color: {
+                        type: 'string',
+                        description: 'Background color or CSS gradient',
+                    },
+                    zoom: {
+                        type: 'number',
+                        description: 'Camera zoom (0.3–3)',
+                    },
+                    camera_roll: {
+                        type: 'number',
+                        description: 'Camera roll in radians',
+                    },
+                    transparent: {
+                        type: 'boolean',
+                        description: 'Transparent background PNG',
+                    },
+                    width: {
+                        type: 'number',
+                        description: 'Output PNG width in pixels. Default: 2880.',
+                    },
+                    height: {
+                        type: 'number',
+                        description: 'Output PNG height in pixels. Default: 2880.',
+                    },
+                },
+            },
+        },
+        {
+            name: 'list_projects',
+            description: 'List your saved OpenMockup projects. Requires OPENMOCKUP_EMAIL, OPENMOCKUP_PASSWORD, OPENMOCKUP_SUPABASE_URL, and OPENMOCKUP_SUPABASE_ANON_KEY env vars.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'get_project',
+            description: 'Get a specific OpenMockup project and its full scene snapshot by ID.',
+            inputSchema: {
+                type: 'object',
+                required: ['id'],
+                properties: {
+                    id: { type: 'string', description: 'Project UUID' },
+                },
+            },
+        },
+        {
+            name: 'create_project',
+            description: 'Create a new empty OpenMockup project.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Project name' },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'render_mockup':
+                return await renderMockup(args);
+            case 'render_mockup_multi':
+                return await renderMockupMulti(args);
+            case 'list_projects':
+                return await listProjects();
+            case 'get_project':
+                return await getProject(args);
+            case 'create_project':
+                return await createProject(args);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/projects.d.ts

@@ -0,0 +1,22 @@
+export declare function listProjects(): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function getProject({ id }: {
+    id: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function createProject({ name }?: {
+    name?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/projects.js

@@ -0,0 +1,94 @@
+import { createClient } from '@supabase/supabase-js';
+const SUPABASE_URL = process.env.OPENMOCKUP_SUPABASE_URL ?? '';
+const SUPABASE_ANON_KEY = process.env.OPENMOCKUP_SUPABASE_ANON_KEY ?? '';
+let supabase = null;
+let userId = null;
+async function getClient() {
+    if (!SUPABASE_URL || !SUPABASE_ANON_KEY) {
+        throw new Error('OPENMOCKUP_SUPABASE_URL and OPENMOCKUP_SUPABASE_ANON_KEY are required for project operations');
+    }
+    if (supabase)
+        return supabase;
+    supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+    const email = process.env.OPENMOCKUP_EMAIL;
+    const password = process.env.OPENMOCKUP_PASSWORD;
+    if (!email || !password) {
+        throw new Error('OPENMOCKUP_EMAIL and OPENMOCKUP_PASSWORD are required for project operations');
+    }
+    const { data, error } = await supabase.auth.signInWithPassword({ email, password });
+    if (error)
+        throw new Error(`Auth failed: ${error.message}`);
+    userId = data.user.id;
+    return supabase;
+}
+export async function listProjects() {
+    const sb = await getClient();
+    const { data, error } = await sb
+        .from('projects')
+        .select('id, name, created_at, updated_at, is_public, thumbnail')
+        .eq('user_id', userId)
+        .order('updated_at', { ascending: false });
+    if (error)
+        throw new Error(error.message);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export async function getProject({ id }) {
+    const sb = await getClient();
+    const { data, error } = await sb
+        .from('projects')
+        .select('*')
+        .eq('id', id)
+        .maybeSingle();
+    if (error)
+        throw new Error(error.message);
+    if (!data)
+        throw new Error(`Project not found: ${id}`);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export async function createProject({ name } = {}) {
+    const sb = await getClient();
+    const { data, error } = await sb
+        .from('projects')
+        .insert({
+        user_id: userId,
+        name: name?.trim() || 'Untitled mockup',
+        is_public: false,
+        snapshot: {
+            devices: [
+                {
+                    id: crypto.randomUUID(),
+                    screenshot: null,
+                    screenMediaKind: null,
+                    screenLoadError: null,
+                    videoStartTime: 0,
+                    videoEndTime: null,
+                    deviceKind: 'phone',
+                    deviceColor: '#DFCEEA',
+                    deviceRotation: [0, 0, 0],
+                    positionX: 0,
+                    positionY: 0,
+                },
+            ],
+            bgColor: '#ffffff',
+            uiTheme: 'dark',
+            cameraRoll: 0,
+            orbitDistance: 28,
+            autoRotate: false,
+            cameraPosition: [0, 0, 28],
+            cameraTarget: [0, 0, 0],
+            viewportAspect: 1,
+            viewportInsetRight: 0,
+        },
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(error.message);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,47 @@
+export type RenderOpts = {
+    image_url?: string;
+    image_data?: string;
+    device?: 'phone' | 'mac';
+    device_color?: string;
+    bg_color?: string;
+    device_rotation?: [number, number, number];
+    zoom?: number;
+    camera_offset_x?: number;
+    camera_offset_y?: number;
+    camera_roll?: number;
+    transparent?: boolean;
+    width?: number;
+    height?: number;
+};
+export type MultiDevice = {
+    image_url?: string;
+    image_data?: string;
+    kind?: 'phone' | 'mac';
+    device_color?: string;
+    device_rotation?: [number, number, number];
+    position_x?: number;
+    position_y?: number;
+};
+export type MultiRenderOpts = {
+    devices: MultiDevice[];
+    bg_color?: string;
+    zoom?: number;
+    camera_roll?: number;
+    transparent?: boolean;
+    width?: number;
+    height?: number;
+};
+export declare function renderMockup(opts: RenderOpts): Promise<{
+    content: {
+        type: string;
+        data: string;
+        mimeType: string;
+    }[];
+}>;
+export declare function renderMockupMulti(opts: MultiRenderOpts): Promise<{
+    content: {
+        type: string;
+        data: string;
+        mimeType: string;
+    }[];
+}>;

package/dist/render.js

@@ -0,0 +1,71 @@
+import { getPage } from './browser.js';
+async function toDataUrl(imageUrl, imageData) {
+    if (imageData) {
+        return imageData.startsWith('data:') ? imageData : `data:image/png;base64,${imageData}`;
+    }
+    if (imageUrl) {
+        if (imageUrl.startsWith('data:'))
+            return imageUrl;
+        const res = await fetch(imageUrl);
+        if (!res.ok)
+            throw new Error(`Failed to fetch image: ${res.status} ${res.statusText}`);
+        const buf = await res.arrayBuffer();
+        const base64 = Buffer.from(buf).toString('base64');
+        const ct = res.headers.get('content-type') ?? 'image/png';
+        return `data:${ct};base64,${base64}`;
+    }
+    return '';
+}
+function extractBase64(dataUrl) {
+    return dataUrl.replace(/^data:image\/\w+;base64,/, '');
+}
+export async function renderMockup(opts) {
+    const page = await getPage();
+    const imageDataUrl = await toDataUrl(opts.image_url, opts.image_data);
+    const renderOpts = {
+        devices: [
+            {
+                kind: opts.device ?? 'phone',
+                imageDataUrl,
+                deviceColor: opts.device_color,
+                deviceRotation: opts.device_rotation,
+            },
+        ],
+        bgColor: opts.bg_color,
+        zoom: opts.zoom,
+        camera_offset_x: opts.camera_offset_x,
+        camera_offset_y: opts.camera_offset_y,
+        camera_roll: opts.camera_roll,
+        transparent: opts.transparent,
+        width: opts.width ?? 1440,
+        height: opts.height ?? 2880,
+    };
+    const dataUrl = await page.evaluate(async (o) => window.renderMockup(o), renderOpts);
+    return {
+        content: [{ type: 'image', data: extractBase64(dataUrl), mimeType: 'image/png' }],
+    };
+}
+export async function renderMockupMulti(opts) {
+    const page = await getPage();
+    const devices = await Promise.all(opts.devices.map(async (d) => ({
+        kind: d.kind ?? 'phone',
+        imageDataUrl: await toDataUrl(d.image_url, d.image_data),
+        deviceColor: d.device_color,
+        deviceRotation: d.device_rotation,
+        positionX: d.position_x,
+        positionY: d.position_y,
+    })));
+    const renderOpts = {
+        devices,
+        bgColor: opts.bg_color,
+        zoom: opts.zoom,
+        camera_roll: opts.camera_roll,
+        transparent: opts.transparent,
+        width: opts.width ?? 2880,
+        height: opts.height ?? 2880,
+    };
+    const dataUrl = await page.evaluate(async (o) => window.renderMockup(o), renderOpts);
+    return {
+        content: [{ type: 'image', data: extractBase64(dataUrl), mimeType: 'image/png' }],
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mcp-openmockup",
+  "version": "0.1.0",
+  "description": "MCP server for OpenMockup — generate 3D device mockup images with AI",
+  "keywords": [
+    "mcp",
+    "mockup",
+    "device",
+    "3d",
+    "screenshot",
+    "phone",
+    "mac",
+    "openmockup",
+    "iphone",
+    "macbook"
+  ],
+  "homepage": "https://openmockup.dev",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "mcp-openmockup": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "playwright-chromium": "^1.50.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}