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 (desktop 1440×900, multiple scroll positions) and runs analysis against your project's UX constraints. Iteration is tracked automatically — never pass an iteration number.

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID from attach step
`page_key`	string	Yes	Page to check — must exactly match a `page_key` from attach
`changes_made`	string	Yes	What was built/changed since last analysis (40–2000 chars). For first run: describe the current state of the page.
`git_snapshot_hash`	string	No	Short SHA (`git rev-parse --short HEAD`). Pass `null` if git unavailable.

Returns: Pass/fail verdict, per-check results, issues grouped by fix type, and a NEXT STEP instruction block that tells the agent exactly what to do next.

`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 config, shows pages + quota, asks which to analyze
2. (user confirms pages, e.g. "homepage and pricing")
3. explainui_analyze          →  capture + analysis (iteration tracked automatically)
4. (agent applies all fixes listed)
5. explainui_analyze          →  re-check (iteration 2)
6. ... repeat until next_action="done" or "review_human"
7. explainui_analyze          →  next confirmed page
8. explainui_close_project    →  cleanup when all pages done

The agent never needs to count iterations or ask whether to run analysis — the MCP response includes a NEXT STEP block with explicit instructions.

Development

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

License

MIT