# 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