viewpo-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Little Bear Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# viewpo-mcp
+
+MCP server that gives AI coding assistants **eyes into responsive viewport rendering** via the [Viewpo](https://viewpo.app) macOS app.
+
+Capture multi-viewport screenshots, extract DOM layout trees, and compare responsive behaviour across breakpoints — all from your AI assistant.
+
+## What it does
+
+AI coding assistants (Claude Code, Cursor, Windsurf, etc.) are **blind** when working on frontend UI. They write CSS and HTML but can't see the visual result. This creates a slow feedback loop:
+
+> AI writes code → you check → you describe what's wrong → AI fixes → repeat
+
+**viewpo-mcp** closes that loop. The AI can now:
+
+1. **Screenshot** a URL at multiple viewport widths simultaneously
+2. **Extract** the DOM layout tree with bounding rects and computed styles
+3. **Compare** layouts at two different viewport widths to find responsive issues
+
+## Requirements
+
+- **[Viewpo](https://viewpo.app) macOS app** with MCP Bridge enabled (Settings → MCP Bridge → Start)
+- **Node.js 20+**
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install -g viewpo-mcp
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx viewpo-mcp
+```
+
+### 2. Enable the MCP Bridge in Viewpo
+
+1. Open Viewpo on your Mac
+2. Go to **Settings → MCP Bridge**
+3. Click **Start** to enable the bridge server
+4. Copy the **auth token** (click the copy button next to the token)
+
+### 3. Configure your AI assistant
+
+#### Claude Code
+
+Add to your MCP config (`~/.claude/mcp.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "viewpo": {
+      "command": "npx",
+      "args": ["-y", "viewpo-mcp"],
+      "env": {
+        "VIEWPO_AUTH_TOKEN": "<paste token from step 2>"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "viewpo": {
+      "command": "npx",
+      "args": ["-y", "viewpo-mcp"],
+      "env": {
+        "VIEWPO_AUTH_TOKEN": "<paste token from step 2>"
+      }
+    }
+  }
+}
+```
+
+#### Other MCP-compatible assistants
+
+Any assistant supporting the [Model Context Protocol](https://modelcontextprotocol.io) can use viewpo-mcp. Set the command to `npx -y viewpo-mcp` and provide the `VIEWPO_AUTH_TOKEN` environment variable.
+
+## Tools
+
+### `viewpo_screenshot`
+
+Capture screenshots of a URL at one or more viewport widths. Returns base64 JPEG images.
+
+```
+url:       "https://example.com"           (required)
+viewports: [{ width: 375, name: "phone" }, (optional, defaults to 1920px desktop)
+            { width: 1920, name: "desktop" }]
+```
+
+Common widths: **375** (phone), **820** (tablet), **1920** (desktop).
+
+### `viewpo_get_layout_map`
+
+Extract the DOM layout tree at a given viewport width. Returns element hierarchy with tags, classes, bounding rects, and computed CSS styles.
+
+```
+url:      "https://example.com"    (required)
+viewport: 1920                     (optional, default 1920)
+selector: ".main-content"          (optional, scope to subtree)
+```
+
+### `viewpo_compare_viewports`
+
+Compare the layout of a URL at two different viewport widths. Returns elements whose size or CSS styles differ between the two viewports.
+
+```
+url:        "https://example.com"  (required)
+viewport_a: 375                    (required)
+viewport_b: 1920                   (required)
+selector:   ".hero"                (optional, scope to subtree)
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VIEWPO_AUTH_TOKEN` | Yes | — | Bearer token from Viewpo Settings &rarr; MCP Bridge |
+| `VIEWPO_PORT` | No | `9847` | Port the Viewpo bridge server listens on |
+
+## How it works
+
+```
+AI Assistant (Claude Code / Cursor / Windsurf)
+    | stdio (MCP protocol)
+    v
+viewpo-mcp (this package)
+    | HTTP localhost:9847
+    v
+Viewpo macOS app (NWListener)
+    | WKWebView rendering
+    v
+Headless browser pool (off-screen, up to 4 concurrent pages)
+```
+
+The Viewpo app runs a local HTTP server on `localhost:9847`. This MCP server translates tool calls into HTTP requests to that bridge. The app loads pages in headless WKWebView instances with real CSS viewport simulation — media queries fire at the target width, not the physical screen width.
+
+**Key advantage**: WKWebView bypasses X-Frame-Options entirely. Any website loads, regardless of security headers that would block iframe-based tools.
+
+## Example workflow
+
+```
+You: "The hero section looks broken on mobile"
+
+AI:  1. viewpo_screenshot("https://preview.example.com", [{width: 375}, {width: 1920}])
+        → Sees the layout at both sizes
+     2. viewpo_compare_viewports("https://preview.example.com", 375, 1920)
+        → Gets structured diff: ".hero img" is 1200px wide on mobile (overflowing)
+     3. Fixes the CSS
+     4. viewpo_screenshot("https://preview.example.com", [{width: 375}])
+        → Verifies the fix
+```
+
+## Development
+
+```bash
+git clone https://github.com/littlebearapps/viewpo-mcp.git
+cd viewpo-mcp
+npm install
+npm run build     # compile TypeScript
+npm run dev       # watch mode
+```
+
+## Licence
+
+MIT - see [LICENSE](LICENSE).
+
+## Links
+
+- [Viewpo app](https://viewpo.app) - The macOS/iOS app
+- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
+- [GitHub](https://github.com/littlebearapps/viewpo-mcp) - Source code

package/dist/client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HTTP client for the Viewpo bridge API.
+ * Communicates with the Viewpo macOS app's NWListener on localhost.
+ */
+import type { ScreenshotRequest, ScreenshotResponse, LayoutMapRequest, LayoutMapResponse, CompareRequest, CompareResponse, HealthResponse } from "./types.js";
+export declare class ViewpoBridgeClient {
+    private readonly baseURL;
+    private readonly authToken;
+    constructor(port?: number, authToken?: string);
+    health(): Promise<HealthResponse>;
+    screenshot(request: ScreenshotRequest): Promise<ScreenshotResponse>;
+    layoutMap(request: LayoutMapRequest): Promise<LayoutMapResponse>;
+    compare(request: CompareRequest): Promise<CompareResponse>;
+    private get;
+    private post;
+    private headers;
+    private handleResponse;
+}

package/dist/client.js

@@ -0,0 +1,71 @@
+/**
+ * HTTP client for the Viewpo bridge API.
+ * Communicates with the Viewpo macOS app's NWListener on localhost.
+ */
+export class ViewpoBridgeClient {
+    baseURL;
+    authToken;
+    constructor(port = 9847, authToken = "") {
+        this.baseURL = `http://127.0.0.1:${port}`;
+        this.authToken = authToken;
+    }
+    async health() {
+        return this.get("/health");
+    }
+    async screenshot(request) {
+        return this.post("/screenshot", request);
+    }
+    async layoutMap(request) {
+        return this.post("/layout", request);
+    }
+    async compare(request) {
+        return this.post("/compare", request);
+    }
+    async get(path) {
+        const response = await fetch(`${this.baseURL}${path}`, {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        return this.handleResponse(response);
+    }
+    async post(path, body) {
+        const response = await fetch(`${this.baseURL}${path}`, {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(body),
+        });
+        return this.handleResponse(response);
+    }
+    headers(includeContentType) {
+        const h = {};
+        if (this.authToken) {
+            h["Authorization"] = `Bearer ${this.authToken}`;
+        }
+        if (includeContentType) {
+            h["Content-Type"] = "application/json";
+        }
+        return h;
+    }
+    async handleResponse(response) {
+        const text = await response.text();
+        if (!response.ok) {
+            let message = `HTTP ${response.status}`;
+            try {
+                const err = JSON.parse(text);
+                message = err.error || message;
+            }
+            catch {
+                if (text)
+                    message = text;
+            }
+            throw new Error(`Viewpo bridge error (${response.status}): ${message}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Invalid JSON response from Viewpo bridge: ${text.slice(0, 200)}`);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Viewpo MCP Server
+ *
+ * Gives AI coding assistants visual inspection tools for responsive
+ * web development via the Viewpo macOS app.
+ *
+ * Transport: stdio (for Claude Code, Cursor, Windsurf, etc.)
+ * Communicates with: Viewpo macOS app on localhost:9847
+ *
+ * @see https://github.com/littlebearapps/viewpo-mcp
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Viewpo MCP Server
+ *
+ * Gives AI coding assistants visual inspection tools for responsive
+ * web development via the Viewpo macOS app.
+ *
+ * Transport: stdio (for Claude Code, Cursor, Windsurf, etc.)
+ * Communicates with: Viewpo macOS app on localhost:9847
+ *
+ * @see https://github.com/littlebearapps/viewpo-mcp
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ViewpoBridgeClient } from "./client.js";
+// --- Configuration from environment ---
+const port = parseInt(process.env.VIEWPO_PORT || "9847", 10);
+const authToken = process.env.VIEWPO_AUTH_TOKEN || "";
+if (!authToken) {
+    console.error("Warning: VIEWPO_AUTH_TOKEN not set. Copy the token from Viewpo > Settings > MCP Bridge.");
+}
+const client = new ViewpoBridgeClient(port, authToken);
+// --- MCP Server ---
+const server = new McpServer({
+    name: "viewpo",
+    version: "0.1.0",
+});
+// --- Tool: viewpo_screenshot ---
+server.tool("viewpo_screenshot", "Capture screenshots of a URL at one or more viewport widths. Returns base64 JPEG images. Use this to SEE what a webpage looks like at different screen sizes.", {
+    url: z.string().url().describe("The URL to screenshot"),
+    viewports: z
+        .array(z.object({
+        width: z
+            .number()
+            .int()
+            .min(100)
+            .max(3840)
+            .describe("Viewport width in CSS pixels"),
+        name: z
+            .string()
+            .optional()
+            .describe('Label for this viewport (e.g. "phone", "desktop")'),
+    }))
+        .optional()
+        .describe("Viewports to capture. Defaults to desktop (1920px) if omitted. Common widths: 375 (phone), 820 (tablet), 1920 (desktop)."),
+}, async ({ url, viewports }) => {
+    try {
+        const result = await client.screenshot({ url, viewports });
+        const content = result.viewports.flatMap((vp) => [
+            {
+                type: "text",
+                text: `**${vp.viewport}** (${vp.width}\u00d7${vp.height})`,
+            },
+            {
+                type: "image",
+                data: vp.image_base64,
+                mimeType: "image/jpeg",
+            },
+        ]);
+        return { content };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Screenshot failed: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Tool: viewpo_get_layout_map ---
+server.tool("viewpo_get_layout_map", "Extract the DOM layout tree of a URL at a given viewport width. Returns element hierarchy with tags, classes, bounding rects, and computed CSS styles. Use this to understand page structure and find layout issues.", {
+    url: z.string().url().describe("The URL to inspect"),
+    viewport: z
+        .number()
+        .int()
+        .min(100)
+        .max(3840)
+        .optional()
+        .describe("Viewport width in CSS pixels (default: 1920)"),
+    selector: z
+        .string()
+        .optional()
+        .describe('CSS selector to scope the layout map to a subtree (e.g. ".main-content", "#hero")'),
+}, async ({ url, viewport, selector }) => {
+    try {
+        const result = await client.layoutMap({ url, viewport, selector });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Layout map failed: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Tool: viewpo_compare_viewports ---
+server.tool("viewpo_compare_viewports", "Compare the layout of a URL at two different viewport widths. Returns a list of elements whose size or CSS styles differ between the two viewports. Use this to find responsive design issues.", {
+    url: z.string().url().describe("The URL to compare"),
+    viewport_a: z
+        .number()
+        .int()
+        .min(100)
+        .max(3840)
+        .describe("First viewport width in CSS pixels (e.g. 375 for phone)"),
+    viewport_b: z
+        .number()
+        .int()
+        .min(100)
+        .max(3840)
+        .describe("Second viewport width in CSS pixels (e.g. 1920 for desktop)"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector to scope comparison to a subtree"),
+}, async ({ url, viewport_a, viewport_b, selector }) => {
+    try {
+        const result = await client.compare({
+            url,
+            viewport_a,
+            viewport_b,
+            selector,
+        });
+        const summary = result.differences.length === 0
+            ? "No layout differences found between the two viewports."
+            : `Found ${result.differences.length} difference(s) between ${result.viewport_a}px and ${result.viewport_b}px:`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${summary}\n\n${JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Compare failed: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Viewpo MCP server fatal error:", error);
+    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/types.d.ts

@@ -0,0 +1,70 @@
+/** TypeScript interfaces matching the Viewpo macOS app bridge API. */
+export interface ViewportSpec {
+    width: number;
+    name?: string;
+}
+export interface ScreenshotRequest {
+    url: string;
+    viewports?: ViewportSpec[];
+}
+export interface ViewportResult {
+    viewport: string;
+    width: number;
+    height: number;
+    image_base64: string;
+}
+export interface ScreenshotResponse {
+    viewports: ViewportResult[];
+}
+export interface LayoutMapRequest {
+    url: string;
+    viewport?: number;
+    selector?: string;
+}
+export interface ElementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LayoutElement {
+    tag: string;
+    id?: string;
+    classes?: string[];
+    rect: ElementRect;
+    styles: Record<string, string>;
+    children: LayoutElement[];
+}
+export interface LayoutMapResponse {
+    url: string;
+    viewport: number;
+    root: LayoutElement;
+}
+export interface CompareRequest {
+    url: string;
+    viewport_a: number;
+    viewport_b: number;
+    selector?: string;
+}
+export interface LayoutDifference {
+    selector: string;
+    tag: string;
+    property: string;
+    value_a: string;
+    value_b: string;
+}
+export interface CompareResponse {
+    url: string;
+    viewport_a: number;
+    viewport_b: number;
+    differences: LayoutDifference[];
+}
+export interface HealthResponse {
+    status: string;
+    version: string;
+    port: number;
+}
+export interface ErrorResponse {
+    error: string;
+    code?: number;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** TypeScript interfaces matching the Viewpo macOS app bridge API. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sEAAsE"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "viewpo-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Viewpo — gives AI coding assistants eyes into responsive viewport rendering",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "viewpo-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "viewpo",
+    "viewport",
+    "responsive",
+    "screenshot",
+    "ai",
+    "claude",
+    "cursor",
+    "webview",
+    "frontend",
+    "testing"
+  ],
+  "author": "Little Bear Apps <hello@littlebearapps.com> (https://littlebearapps.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/littlebearapps/viewpo-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/littlebearapps/viewpo-mcp/issues"
+  },
+  "homepage": "https://github.com/littlebearapps/viewpo-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ]
+}