InterfaceGuard MCP Server

An MCP (Model Context Protocol) server that brings InterfaceGuard UX analysis directly into AI coding tools — Claude Code, Cursor, Windsurf, and any other MCP-compatible environment. Capture screenshots with embedded Playwright, submit analysis jobs, and consume prioritized UX recommendations without leaving your editor.

Features

• Screenshot Capture: Headless Chromium captures desktop, tablet, and mobile viewports — no external browser server needed
• Multi-Viewport Analysis: Responsive UX issues caught at 1440×900, 768×1024, and 390×844 in a single call
• 9 Analysis Types: Accessibility, usability, consistency, visual hierarchy, color scheme, layout, design system extraction, branding, and expert review
• Fix Prompts: AI-generated coding prompts for each issue, ready to paste into a task
• Issue Tracking: Mark issues resolved after fixing them
• Zero Config: Defaults to the production Cloud Run endpoint — only UXA_API_KEY is required

MCP Tools

| Tool | Description | |---|---| | capture_screenshots | Open a URL in headless Chromium and capture at desktop, tablet, and/or mobile viewports | | list_projects | List InterfaceGuard projects available to the API key | | submit_analysis | Submit captured screenshots for UX analysis; returns a jobId | | get_job_status | Check job progress (0–100%) and completion status | | get_results | Fetch the full analysis result: issues, recommendations, and severity summary | | enhance_prompt | Generate an AI-powered coding fix prompt for a specific issue | | resolve_issue | Mark an issue resolved or reopen it | | cancel_job | Cancel a pending or in-progress job |

Prerequisites

• Node.js 18 or higher
• Chromium for Playwright (see Installation)
• An InterfaceGuard API key (generate one in the web app under Settings → API Keys)

Installation

Install the package globally or use it via npx:

npm install -g @cre8tivsystems/interfaceguard-mcp

Install the Chromium browser for screenshot capture (one-time setup):

npx playwright install chromium

Configuration

Claude Code

⚠️ WARNING: Never place UXA_API_KEY in a project-scoped .claude/settings.json — that file is typically committed to version control and would expose your API key. Use ~/.claude/settings.json (user-level, untracked) instead, or inject the key via a secret-management tool (e.g., op run, direnv, or a CI secret store).

Add to ~/.claude/settings.json (user-level, all projects) or .claude/settings.json (project-level — only if the file is in .gitignore):

{
  "mcpServers": {
    "ux-analyzer": {
      "command": "npx",
      "args": ["-y", "@cre8tivsystems/interfaceguard-mcp"],
      "env": {
        "UXA_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ux-analyzer": {
      "command": "npx",
      "args": ["-y", "@cre8tivsystems/interfaceguard-mcp"],
      "env": {
        "UXA_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf / other MCP clients

Use the same JSON block in your client's MCP configuration file. The server communicates over stdio, which all MCP clients support.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | UXA_API_KEY | Yes | — | InterfaceGuard API key from the web app | | UXA_API_URL | No | — | Analysis service URL. Optional — defaults to the production endpoint. Set to http://localhost:8080 to test against a locally running service. |

Usage

Once configured, Claude Code (and other clients) can invoke the tools directly. The typical workflow:

1. capture_screenshots(url)           → captureId
2. list_projects()                    → pick projectId
3. submit_analysis(captureId, projectId) → jobId
4. get_job_status(jobId)              → poll until "completed", "failed", or "cancelled"
5. get_results(jobId)                 → issues + recommendations
6. enhance_prompt(issue)              → coding fix prompt
7. resolve_issue(jobId, issueId, true)

Use cancel_job(jobId) to stop a pending or in-progress job — the status will then return "cancelled".

See SKILL.md for the detailed agent workflow, analysis type guidance, and example session — this file is intended to be referenced by Claude Code as a skill.

Commands

# Build TypeScript to dist/
npm run build

# Watch mode (rebuild on change)
npm run dev

# Type check without emitting
npm run type-check

# Run the compiled server directly
npm start

Local Development

To run the server directly from source without a build step (useful during development):

UXA_API_KEY=your-key npx tsx src/index.ts

Or configure your MCP client to use tsx instead of the compiled output:

{
  "mcpServers": {
    "ux-analyzer": {
      "command": "npx",
      "args": ["tsx", "/path/to/ux.ai/ux-analyzer-mcp/src/index.ts"],
      "env": {
        "UXA_API_KEY": "your-api-key",
        "UXA_API_URL": "http://localhost:8080"
      }
    }
  }
}

Project Structure

ux-analyzer-mcp/
├── src/
│   ├── index.ts              # Entry point — wires server, tools, and stdio transport
│   ├── config.ts             # Reads UXA_API_KEY / UXA_API_URL from environment
│   ├── store.ts              # In-memory capture store (captureId → PNG buffers)
│   ├── api/
│   │   ├── client.ts         # Axios wrapper for the InterfaceGuard REST API
│   │   └── types.ts          # Shared TypeScript types (Issue, Recommendation, etc.)
│   └── tools/
│       ├── capture.ts        # capture_screenshots — Playwright multi-viewport capture
│       ├── projects.ts       # list_projects
│       ├── jobs.ts           # submit_analysis, get_job_status, get_results, cancel_job
│       └── issues.ts         # enhance_prompt, resolve_issue
├── SKILL.md                  # Claude Code skill: agent workflow and examples
├── package.json
└── tsconfig.json

Publishing

npm run build
npm publish --access public

The package is published as the scoped, public package @cre8tivsystems/interfaceguard-mcp. The --access public flag is required on first publish since scoped packages default to private.

How Screenshot Capture Works

capture_screenshots launches a headless Chromium instance using the bundled playwright package, opens the target URL at each requested viewport, and takes a PNG screenshot. The images are held in an in-memory store keyed by captureId and passed directly to submit_analysis as multipart form data — the AI agent never handles raw image bytes.

The in-memory store is cleared after each successful submit_analysis call. If the MCP server process restarts between capture_screenshots and submit_analysis, the captureId will be invalid and you will need to capture again.

Troubleshooting

UXA_API_KEY environment variable is required Set the UXA_API_KEY env var in your MCP client config.

No capture found for captureId "..." The MCP server process restarted between capture and submission, clearing the in-memory store. Run capture_screenshots again.

Playwright / Chromium not found Run npx playwright install chromium to download the browser binary.

networkidle timeout on capture The page may have long-polling or streaming connections that prevent networkidle. This can happen with dev servers. The server will time out after 30 seconds and proceed with whatever has loaded.

API errors (401) Verify UXA_API_KEY is correct. Generate a new key under Settings → API Keys in the InterfaceGuard web app if needed.

License

MIT