Package Exports

@explainui/mcp
@explainui/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@explainui/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

Add to .cursor/mcp.json in your project root:

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

GitHub Copilot (VS Code)

Add to your VS Code settings.json or .vscode/mcp.json:

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

Then in Copilot Chat, use agent mode (@workspace) and mention your ExplainUI project ID — Copilot will discover and call the MCP tools automatically.

Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

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

Cline

Open the Cline MCP settings panel in VS Code and add a new server with command explainui-mcp and 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–2000 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