@explainui/mcp

Silent UX QA in your AI agent workflow. This MCP server captures screenshots at multiple viewports and runs GPT-4o analysis against your project's UX constraints — all without leaving your editor.

Installation

npm install -g @explainui/mcp

Chromium is installed automatically via Playwright during postinstall.

Quick Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "explainui": {
      "command": "explainui-mcp",
      "env": {
        "EXPLAINUI_LICENSE_KEY": "ek_live_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / Cline

Consult your editor's MCP configuration docs and add explainui-mcp as a stdio server with the environment variable below.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | EXPLAINUI_LICENSE_KEY | Yes | — | Your license key from explainui.com/settings | | EXPLAINUI_API_HOST | No | https://api.explainui.com | API base URL (override for self-hosted) |

Tools

The server exposes three MCP tools:

explainui_attach_project

Load your project configuration. Call this first before any analysis.

| Parameter | Type | Required | Description | |---|---|---|---| | project_id | string | Yes | proj_xxxxxxxx from your dashboard |

explainui_analyze

Run a UX QA check. Captures screenshots at 3 viewports (desktop 1280×800, tablet 768×1024, mobile 375×812) with scroll positions, then sends to GPT-4o for analysis.

| Parameter | Type | Required | Description | |---|---|---|---| | project_id | string | Yes | Project ID from attach step | | page_key | string | Yes | Page to check (e.g. homepage, pricing) | | iteration | integer | Yes | Iteration count (1–10), increment after each call | | this_iteration | string | Yes | What was built/changed (40–500 chars) | | git_snapshot_hash | string | No | Short SHA from pre-analysis commit |

Returns: Pass/fail verdict, per-check results, issues with severity and fix suggestions.

explainui_close_project

End the session. Releases browser resources and clears cached config.

| Parameter | Type | Required | Description | |---|---|---|---| | project_id | string | Yes | Same project from attach step | | reason | enum | Yes | all_pages_done · session_end · user_request · permanent_error |

Typical Workflow

1. explainui_attach_project  →  load project config
2. (write code / make changes)
3. explainui_analyze          →  capture + GPT-4o analysis
4. (fix any issues found)
5. explainui_analyze          →  re-check (iteration 2)
6. explainui_close_project    →  cleanup

Development

cd packages/explainui_mcp
npm install
npm run build      # TypeScript → dist/
npm test           # Vitest
npm run dev        # Watch mode

License

MIT