@explainui/mcp 0.1.0-beta.1 → 0.1.3

package/README.md

@@ -29,9 +29,64 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Cursor / Windsurf / Cline
+### Cursor
 
-Consult your editor's MCP configuration docs and add `explainui-mcp` as a stdio server with the environment variable below.
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "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`:
+
+```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`):
+
+```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
 
@@ -54,17 +109,16 @@ Load your project configuration. **Call this first** before any analysis.
 
 ### `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.
+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 (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 |
+| `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 with severity and fix suggestions.
+**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`
 
@@ -78,14 +132,18 @@ End the session. Releases browser resources and clears cached config.
 ## 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)
+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. explainui_close_project    →  cleanup
+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
 
 ```bash

package/dist/capture.d.ts

@@ -11,6 +11,7 @@
 import { type CaptureResult } from "./types.js";
 /**
  * Capture screenshots at all configured viewports for a given URL.
+ * Also runs deterministic DOM checks and extracts element maps.
  * Returns base64-encoded JPEG screenshots with labels.
  */
 export declare function captureAllViewports(url: string): Promise<CaptureResult>;

package/dist/capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAA8B,KAAK,aAAa,EAAkB,MAAM,YAAY,CAAC;AAmB5F;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmF7E;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAKlD"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAGL,KAAK,aAAa,EAYnB,MAAM,YAAY,CAAC;AAo6DpB;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsK7E;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAKlD"}