@explainui/mcp

ExplainUI MCP — baseline-first UX analysis with phase-gated iteration control and git checkpoint snapshots.

Captures screenshots, runs UX/accessibility analysis against your project constraints, and guides the agent through a strict fix loop with full git history at every step.

Every tool call requires both project_id and page_key.

Installation

npm install -g @explainui/mcp

Chromium is installed automatically via Playwright during postinstall.

Quick Setup

Claude Desktop

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

Cursor

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

GitHub Copilot (VS Code)

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

Windsurf

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

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | EXPLAINUI_LICENSE_KEY | Yes | — | License key from explainui.com/settings | | EXPLAINUI_API_HOST | No | https://api.explainui.com | Override API host (self-hosted / staging) |

Tools (7)

| Tool | Purpose | |---|---| | explainui_status | Entry point — attach project/page, fetch current run state and strict next commands | | explainui_new_run | Create a run and automatically run baseline analysis | | explainui_baseline_analysis | Manual baseline retry/refresh (only if auto baseline failed) | | explainui_start_iteration | Begin fix loop — initialises git branch + cp-0, delivers baseline issues | | explainui_submit_iteration | Submit fixes and analyse — captures screenshots, snapshots cp-N | | explainui_finish_run | Merge or abandon the run | | explainui_close_project | End session and release browser resources |

Workflow

1. explainui_status({ project_id, page_key })
      ↓ loads project config, reports run state and next commands
2. explainui_new_run({ project_id, page_key })
      ↓ creates run, auto-runs baseline analysis, phase → baseline_ready
3. explainui_start_iteration({ project_id, page_key })
      ↓ initialises git branch + cp-0 snapshot, returns baseline issues to fix
4. [agent applies fixes in editor]
5. explainui_submit_iteration({ project_id, page_key, changes_made })
      ↓ analyses page, creates cp-N snapshot after success
      ↓ next_action="fix"  → repeat from step 3
      ↓ next_action="done" → go to step 6
6. explainui_finish_run({ project_id, page_key, action: "merge" | "abandon" })
      ↓ merge: creates cp-N if needed, merges run branch → source branch
      ↓ abandon: deletes run branch and all checkpoint tags
7. explainui_close_project({ project_id, page_key, reason })

Git Checkpoint System

When git snapshots are enabled for a page, the MCP maintains a full checkpoint history on a dedicated run branch. No changes are ever made to your source branch until finish_run is called.

Branch Structure

main (source branch)
  │
  ├─── cp-0  ← original code at run start
  │
  └─── explainui/run-N  (run branch, branched from main at new_run)
         │
         ├─── cp-1  ← code after iteration 1 fixes
         ├─── cp-2  ← code after iteration 2 fixes
         ├─── cp-3  ← code after iteration 3 fixes
         │
         └─── merged into main at finish_run

Checkpoint Lifecycle

| Checkpoint | When created | What it contains | |---|---|---| | cp-0 | At start_iteration (first call) | Original code before any fixes | | cp-N | After submit_iteration succeeds for iteration N | Agent's fixes for iteration N, as analysed | | cp-N (final) | At finish_run if cp-N doesn't exist yet | Created automatically before merge |

Tag format: explainui/run-{run_number}/cp-{N}

Example: explainui/run-5/cp-2

finish_run Merge Behaviour

# Merge latest checkpoint (default — normal happy path)
explainui_finish_run({ project_id, page_key, action: "merge" })

# Merge a specific earlier checkpoint
# Use when: iteration 3 made things worse, iteration 2 was better
explainui_finish_run({ project_id, page_key, action: "merge", checkpoint: 2 })

# Abandon — discard all changes, delete run branch
explainui_finish_run({ project_id, page_key, action: "abandon" })

When checkpoint: N is passed:

• If N is the latest iteration: creates cp-N snapshot if it doesn't exist yet, then merges
• If N is an earlier iteration: resets the run branch to cp-N's git tag, then merges that state into source branch

After a Merge

The run branch (explainui/run-N) and all checkpoint tags (explainui/run-N/cp-*) are deleted automatically. The merged state is committed to your source branch.

To restore a specific checkpoint manually after a run is complete:

git merge explainui/run-5/cp-2

This command is shown in the ExplainUI dashboard timeline for each checkpoint.

Error Handling

ANALYSIS_PARSE_FAILED

The analysis pipeline occasionally fails to parse results. When this happens:

• The MCP rolls back the iteration counter so the retry uses the same iteration number
• The agent should retry explainui_submit_iteration once with the same arguments
• If it fails again, set next_action to review_human

Baseline capture failed

If automatic baseline from explainui_new_run fails (page unavailable, timeout):

explainui_baseline_analysis({ project_id, page_key })

This retries the baseline without creating a new run.

Troubleshooting

| Error | Fix | |---|---| | "No page attached" | Call explainui_status first | | "Baseline review required" | Call explainui_start_iteration after baseline completes | | "No active run" | Call explainui_new_run to start a fresh run | | "Cannot merge: source branch unknown" | Run explainui_start_iteration first (it records the source branch) | | "Checkpoint cp-N not found" | Tag doesn't exist locally — only checkpoints from the current session are available |

Development

cd packages/explainui_mcp
npm install
npm run build
npm test
npm run dev   # tsx watch mode

License

MIT