@explainui/mcp 0.1.0-beta.1

package/README.md

@@ -0,0 +1,101 @@
+# @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
+
+```bash
+npm install -g @explainui/mcp
+```
+
+Chromium is installed automatically via Playwright during `postinstall`.
+
+## Quick Setup
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```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](https://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
+
+```bash
+cd packages/explainui_mcp
+npm install
+npm run build      # TypeScript → dist/
+npm test           # Vitest
+npm run dev        # Watch mode
+```
+
+## License
+
+MIT

package/dist/capture.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ExplainUI MCP — Playwright Screenshot Capture
+ * Launches headless Chromium, captures screenshots at all viewports.
+ *
+ * Browser lifecycle:
+ *   - Lazy launch on first capture (saves ~400MB idle RAM)
+ *   - Reused across all analyze calls in a session
+ *   - Auto-relaunches if browser disconnects
+ *   - Clean shutdown on SIGINT/SIGTERM
+ */
+import { type CaptureResult } from "./types.js";
+/**
+ * Capture screenshots at all configured viewports for a given URL.
+ * Returns base64-encoded JPEG screenshots with labels.
+ */
+export declare function captureAllViewports(url: string): Promise<CaptureResult>;
+/**
+ * Clean shutdown of the browser instance.
+ */
+export declare function closeBrowser(): Promise<void>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -0,0 +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"}

package/dist/capture.js

@@ -0,0 +1,116 @@
+/**
+ * ExplainUI MCP — Playwright Screenshot Capture
+ * Launches headless Chromium, captures screenshots at all viewports.
+ *
+ * Browser lifecycle:
+ *   - Lazy launch on first capture (saves ~400MB idle RAM)
+ *   - Reused across all analyze calls in a session
+ *   - Auto-relaunches if browser disconnects
+ *   - Clean shutdown on SIGINT/SIGTERM
+ */
+import { chromium } from "playwright";
+import { VIEWPORTS, ExplainUIError } from "./types.js";
+let browser = null;
+async function getBrowser() {
+    if (!browser || !browser.isConnected()) {
+        browser = await chromium.launch({
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-gpu",
+            ],
+        });
+    }
+    return browser;
+}
+/**
+ * Capture screenshots at all configured viewports for a given URL.
+ * Returns base64-encoded JPEG screenshots with labels.
+ */
+export async function captureAllViewports(url) {
+    const startTime = Date.now();
+    const b = await getBrowser();
+    const context = await b.newContext({
+        ignoreHTTPSErrors: true,
+        userAgent: "ExplainUI/1.0 (UX QA Agent)",
+        viewport: { width: 1280, height: 800 },
+    });
+    const page = await context.newPage();
+    try {
+        await page.goto(url, { waitUntil: "networkidle", timeout: 15_000 });
+        const screenshots = [];
+        for (const vp of VIEWPORTS) {
+            await page.setViewportSize({ width: vp.width, height: vp.height });
+            await page.waitForTimeout(300); // let layout reflow settle
+            const pageHeight = await page.evaluate(() => document.body.scrollHeight);
+            const scrollStep = vp.height;
+            const maxScrolls = Math.min(vp.scrolls, Math.ceil(pageHeight / scrollStep));
+            for (let i = 0; i < maxScrolls; i++) {
+                const scrollY = i * scrollStep;
+                await page.evaluate((y) => window.scrollTo(0, y), scrollY);
+                await page.waitForTimeout(150); // let lazy images load
+                let bytes = await page.screenshot({
+                    type: "jpeg",
+                    quality: 70,
+                    clip: { x: 0, y: 0, width: vp.width, height: vp.height },
+                });
+                // Size guard: if screenshot > 5MB, reduce quality
+                if (bytes.length > 5 * 1024 * 1024) {
+                    bytes = await page.screenshot({
+                        type: "jpeg",
+                        quality: 50,
+                        clip: { x: 0, y: 0, width: vp.width, height: vp.height },
+                    });
+                }
+                screenshots.push({
+                    label: `${vp.label}_scroll_${i}`,
+                    viewport: vp.label,
+                    scroll_index: i,
+                    data: bytes.toString("base64"),
+                });
+                // Break if we've scrolled past the page content
+                const currentY = await page.evaluate(() => window.scrollY);
+                const maxY = await page.evaluate(() => document.body.scrollHeight - window.innerHeight);
+                if (currentY >= maxY)
+                    break;
+            }
+        }
+        return {
+            screenshots,
+            capture_duration_ms: Date.now() - startTime,
+        };
+    }
+    catch (err) {
+        const message = err.message || "";
+        if (message.includes("ERR_CONNECTION_REFUSED")) {
+            throw new ExplainUIError("LOCAL_SERVER_NOT_RUNNING", `Could not connect to ${url}. Is your dev server running?`);
+        }
+        if (message.includes("Timeout")) {
+            throw new ExplainUIError("CAPTURE_TIMEOUT", `Page at ${url} took too long to load (>15s).`);
+        }
+        throw err;
+    }
+    finally {
+        await page.close();
+        await context.close();
+    }
+}
+/**
+ * Clean shutdown of the browser instance.
+ */
+export async function closeBrowser() {
+    if (browser) {
+        await browser.close();
+        browser = null;
+    }
+}
+// Graceful shutdown on process exit
+process.on("SIGINT", () => {
+    browser?.close().then(() => process.exit(0));
+});
+process.on("SIGTERM", () => {
+    browser?.close().then(() => process.exit(0));
+});
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAgD,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,SAAS,EAAuC,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5F,IAAI,OAAO,GAAmB,IAAI,CAAC;AAEnC,KAAK,UAAU,UAAU;IACvB,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACvC,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YAC9B,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE;gBACJ,cAAc;gBACd,0BAA0B;gBAC1B,yBAAyB;gBACzB,eAAe;aAChB;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,CAAC,GAAG,MAAM,UAAU,EAAE,CAAC;IAE7B,MAAM,OAAO,GAAmB,MAAM,CAAC,CAAC,UAAU,CAAC;QACjD,iBAAiB,EAAE,IAAI;QACvB,SAAS,EAAE,6BAA6B;QACxC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;KACvC,CAAC,CAAC;IACH,MAAM,IAAI,GAAS,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAEpE,MAAM,WAAW,GAAiB,EAAE,CAAC;QAErC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;YACnE,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,2BAA2B;YAE3D,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzE,MAAM,UAAU,GAAG,EAAE,CAAC,MAAM,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC;YAE5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpC,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,CAAC;gBAC/B,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBACnE,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,uBAAuB;gBAEvD,IAAI,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;oBAChC,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,EAAE;oBACX,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE;iBACzD,CAAC,CAAC;gBAEH,kDAAkD;gBAClD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;oBACnC,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;wBAC5B,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,EAAE;wBACX,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE;qBACzD,CAAC,CAAC;gBACL,CAAC;gBAED,WAAW,CAAC,IAAI,CAAC;oBACf,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,WAAW,CAAC,EAAE;oBAChC,QAAQ,EAAE,EAAE,CAAC,KAAK;oBAClB,YAAY,EAAE,CAAC;oBACf,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;iBAC/B,CAAC,CAAC;gBAEH,gDAAgD;gBAChD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAC9B,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CACtD,CAAC;gBACF,IAAI,QAAQ,IAAI,IAAI;oBAAE,MAAM;YAC9B,CAAC;QACH,CAAC;QAED,OAAO;YACL,WAAW;YACX,mBAAmB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SAC5C,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAI,GAAa,CAAC,OAAO,IAAI,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,cAAc,CACtB,0BAA0B,EAC1B,wBAAwB,GAAG,+BAA+B,CAC3D,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,cAAc,CACtB,iBAAiB,EACjB,WAAW,GAAG,gCAAgC,CAC/C,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;AACH,CAAC;AAED,oCAAoC;AACpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;IACzB,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ExplainUI MCP — API Client
+ * Axios-based client for talking to the ExplainUI API.
+ */
+import type { Config } from "./config.js";
+import type { AnalyzeRequest, AnalyzeResponse, ProjectConfig, VersionInfo } from "./types.js";
+export declare class ApiClient {
+    private client;
+    private licenseKey;
+    private mcpVersion;
+    constructor(config: Config);
+    /**
+     * GET /v2/version — check API compatibility.
+     */
+    checkVersion(): Promise<VersionInfo>;
+    /**
+     * GET /v2/projects/{id}/config — fetch project config (license key auth).
+     */
+    getProjectConfig(projectId: string): Promise<ProjectConfig>;
+    /**
+     * POST /v2/agent/analyze — run UX QA analysis.
+     */
+    analyze(req: AnalyzeRequest): Promise<AnalyzeResponse>;
+    /**
+     * Health check — GET /health
+     */
+    healthCheck(): Promise<boolean>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,WAAW,EAEZ,MAAM,YAAY,CAAC;AAGpB,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,MAAM;IAa1B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC;IAK1C;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAyBjE;;OAEG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAY5D;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAQtC"}

package/dist/client.js

@@ -0,0 +1,78 @@
+/**
+ * ExplainUI MCP — API Client
+ * Axios-based client for talking to the ExplainUI API.
+ */
+import axios from "axios";
+import { ExplainUIError } from "./types.js";
+export class ApiClient {
+    client;
+    licenseKey;
+    mcpVersion;
+    constructor(config) {
+        this.licenseKey = config.licenseKey;
+        this.mcpVersion = config.mcpVersion;
+        this.client = axios.create({
+            baseURL: config.apiHost,
+            timeout: 60_000, // 60s — GPT calls can take a while
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": `ExplainUI-MCP/${config.mcpVersion}`,
+            },
+        });
+    }
+    /**
+     * GET /v2/version — check API compatibility.
+     */
+    async checkVersion() {
+        const resp = await this.client.get("/v2/version");
+        return resp.data;
+    }
+    /**
+     * GET /v2/projects/{id}/config — fetch project config (license key auth).
+     */
+    async getProjectConfig(projectId) {
+        const resp = await this.client.get(`/v2/projects/${projectId}/config`, {
+            headers: { "X-License-Key": this.licenseKey },
+        });
+        const data = resp.data;
+        if (data.error) {
+            throw new ExplainUIError(data.error.code || "API_ERROR", data.error.message || "Failed to fetch project config");
+        }
+        return {
+            project_id: data.project_id,
+            name: data.name,
+            pages: data.pages || [],
+            constraint_bundle: data.constraint_bundle || {
+                user_goal: "",
+                user_enforced_constraints: [],
+                do_not_flag: [],
+            },
+            trigger_threshold: data.trigger_threshold || "major_features",
+            fetched_at: Date.now(),
+        };
+    }
+    /**
+     * POST /v2/agent/analyze — run UX QA analysis.
+     */
+    async analyze(req) {
+        const resp = await this.client.post("/v2/agent/analyze", {
+            ...req,
+            license_key: this.licenseKey,
+            mcp_version: this.mcpVersion,
+        });
+        return resp.data;
+    }
+    /**
+     * Health check — GET /health
+     */
+    async healthCheck() {
+        try {
+            const resp = await this.client.get("/health", { timeout: 5000 });
+            return resp.data?.status === "ok";
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AASlD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,OAAO,SAAS;IACZ,MAAM,CAAgB;IACtB,UAAU,CAAS;IACnB,UAAU,CAAS;IAE3B,YAAY,MAAc;QACxB,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,EAAE,mCAAmC;YACpD,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,YAAY,EAAE,iBAAiB,MAAM,CAAC,UAAU,EAAE;aACnD;SACF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAc,aAAa,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,SAAiB;QACtC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,SAAS,SAAS,EAAE;YACrE,OAAO,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,UAAU,EAAE;SAC9C,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,cAAc,CACtB,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,WAAW,EAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,gCAAgC,CACvD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;YACvB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,IAAI;gBAC3C,SAAS,EAAE,EAAE;gBACb,yBAAyB,EAAE,EAAE;gBAC7B,WAAW,EAAE,EAAE;aAChB;YACD,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,IAAI,gBAAgB;YAC7D,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;SACvB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,GAAmB;QAC/B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACjC,mBAAmB,EACnB;YACE,GAAG,GAAG;YACN,WAAW,EAAE,IAAI,CAAC,UAAU;YAC5B,WAAW,EAAE,IAAI,CAAC,UAAU;SAC7B,CACF,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACjE,OAAO,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ExplainUI MCP — Configuration
+ * Reads environment variables for API host, license key, etc.
+ */
+export interface Config {
+    apiHost: string;
+    licenseKey: string;
+    mcpVersion: string;
+}
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAcnC"}

package/dist/config.js

@@ -0,0 +1,15 @@
+/**
+ * ExplainUI MCP — Configuration
+ * Reads environment variables for API host, license key, etc.
+ */
+export function loadConfig() {
+    const apiHost = process.env.EXPLAINUI_API_HOST || "https://api.explainui.com";
+    const licenseKey = process.env.EXPLAINUI_LICENSE_KEY || "";
+    const mcpVersion = "0.1.0";
+    if (!licenseKey) {
+        console.error("[ExplainUI] EXPLAINUI_LICENSE_KEY is not set. " +
+            "Get your key at https://explainui.com/settings");
+    }
+    return { apiHost, licenseKey, mcpVersion };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GACX,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,2BAA2B,CAAC;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC;IAE3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACX,gDAAgD;YAC9C,gDAAgD,CACnD,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * ExplainUI MCP Server
+ * ====================
+ * Registers 3 tools: explainui_attach_project, explainui_analyze, explainui_close_project
+ * Runs over stdio transport for Claude Desktop, Cursor, Cline, Windsurf.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * ExplainUI MCP Server
+ * ====================
+ * Registers 3 tools: explainui_attach_project, explainui_analyze, explainui_close_project
+ * Runs over stdio transport for Claude Desktop, Cursor, Cline, Windsurf.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { ApiClient } from "./client.js";
+import { attachProject, analyze, closeProject } from "./tools.js";
+// ── Session State ──────────────────────────────────────────────────────────
+function detectPlatform() {
+    const c = (process.env.MCP_CLIENT ?? "").toLowerCase();
+    if (c.includes("cursor"))
+        return "cursor";
+    if (c.includes("cline"))
+        return "cline";
+    if (c.includes("windsurf"))
+        return "windsurf";
+    if (process.env.CLAUDE_DESKTOP_APP)
+        return "claude_desktop";
+    return "unknown";
+}
+const session = {
+    projectConfig: null,
+    platform: detectPlatform(),
+};
+// ── Config + Client ────────────────────────────────────────────────────────
+const config = loadConfig();
+const client = new ApiClient(config);
+// ── MCP Server ─────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "explainui",
+    version: config.mcpVersion,
+});
+// ── Tool: explainui_attach_project ─────────────────────────────────────────
+server.tool("explainui_attach_project", `Load your ExplainUI project configuration into this session.
+
+WHEN TO CALL:
+Immediately when the user provides their project ID in any of these forms:
+  "ExplainUI project: proj_abc123"
+  "My ExplainUI project is proj_abc123"
+  "proj_abc123" (if ExplainUI context is established)
+Call BEFORE writing any code. BEFORE starting any task. First action always.
+
+WHAT THIS LOADS AND CACHES FOR THE ENTIRE SESSION:
+- pages[]: every configured page with page_key → URL mapping
+- constraint_bundle: design constraints + intentional decisions to skip
+- trigger_threshold: when to auto-call analyze
+- project name + tier
+
+CONFIG IS CACHED: If called again for the same project_id within 5 minutes,
+returns cached result without hitting the API.`, {
+    project_id: z
+        .string()
+        .describe("The project ID from explainui.com/dashboard, format: proj_xxxxxxxx"),
+}, async ({ project_id }) => {
+    return attachProject(session, client, project_id);
+});
+// ── Tool: explainui_analyze ────────────────────────────────────────────────
+server.tool("explainui_analyze", `Run a UX QA check on a locally running web page. Captures screenshots at 3 viewports (desktop, tablet, mobile) and sends them to GPT-4o for professional UX analysis.
+
+Call this after each meaningful code change. The tool:
+1. Launches headless Chromium and captures the page at multiple viewports
+2. Sends screenshots + context to the ExplainUI API
+3. Returns issues with severity, fix suggestions, and bounding boxes
+
+IMPORTANT: Always call explainui_attach_project first to load the project config.`, {
+    project_id: z
+        .string()
+        .describe("proj_xxx — from the attach_project result this session"),
+    page_key: z
+        .string()
+        .describe("Which page to check. E.g., 'homepage', 'pricing'. Must match a page in project config."),
+    iteration: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .describe("Current iteration count for this page_key. Start at 1. Increment after each call."),
+    this_iteration: z
+        .string()
+        .min(40)
+        .max(500)
+        .describe("What was just built or changed. Be specific — GPT uses this to verify. Minimum 40 characters."),
+    git_snapshot_hash: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Short SHA from the pre-analysis git commit. null if git unavailable."),
+}, async (args) => {
+    return analyze(session, client, args);
+});
+// ── Tool: explainui_close_project ──────────────────────────────────────────
+server.tool("explainui_close_project", `Mark the ExplainUI session as complete. Housekeeping — always call when done.
+
+WHEN TO CALL:
+- After analyze returns next_action="done" for the LAST page in the session
+- When user says: "we're done for today", "that's all", "stopping here"
+- Before ending any long coding session where ExplainUI was active
+- If analysis errors out permanently on all pages
+
+WHAT THIS DOES:
+- Releases browser resources (headless Chromium)
+- Clears cached project config
+- All iterations and screenshots are preserved in the dashboard.`, {
+    project_id: z
+        .string()
+        .describe("proj_xxx — same project that was attached this session"),
+    reason: z
+        .enum([
+        "all_pages_done",
+        "session_end",
+        "user_request",
+        "permanent_error",
+    ])
+        .describe("Why the session is being closed"),
+}, async (args) => {
+    return closeProject(session, client, args);
+});
+// ── Start Server ───────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[ExplainUI MCP] Server started (platform: ${session.platform})`);
+}
+main().catch((err) => {
+    console.error("[ExplainUI MCP] Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ExplainUI MCP — Tool Implementations
+ * Three tools: attach_project, analyze, close_project
+ */
+import { ApiClient } from "./client.js";
+import type { ExplainUISession } from "./types.js";
+/**
+ * explainui_attach_project — Load project config into session.
+ */
+export declare function attachProject(session: ExplainUISession, client: ApiClient, projectId: string): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+/**
+ * explainui_analyze — Capture screenshots + run UX QA analysis.
+ */
+export declare function analyze(session: ExplainUISession, client: ApiClient, args: {
+    project_id: string;
+    page_key: string;
+    iteration: number;
+    this_iteration: string;
+    git_snapshot_hash?: string | null;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+/**
+ * explainui_close_project — Session cleanup.
+ */
+export declare function closeProject(session: ExplainUISession, _client: ApiClient, args: {
+    project_id: string;
+    reason: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAKpB;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA4E7D;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,GACA,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA4F7D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAuB7D"}

package/dist/tools.js

@@ -0,0 +1,245 @@
+/**
+ * ExplainUI MCP — Tool Implementations
+ * Three tools: attach_project, analyze, close_project
+ */
+import { captureAllViewports, closeBrowser } from "./capture.js";
+import { ExplainUIError } from "./types.js";
+const CONFIG_CACHE_TTL_MS = 5 * 60 * 1000; // 5 min
+/**
+ * explainui_attach_project — Load project config into session.
+ */
+export async function attachProject(session, client, projectId) {
+    // Return cached if fresh
+    if (session.projectConfig &&
+        session.projectConfig.project_id === projectId &&
+        Date.now() - session.projectConfig.fetched_at < CONFIG_CACHE_TTL_MS) {
+        const config = session.projectConfig;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `✅ Project already loaded: ${config.name} (${config.project_id})`,
+                        `Pages: ${config.pages.map((p) => p.page_key).join(", ")}`,
+                        `Trigger: ${config.trigger_threshold}`,
+                        `(cached — valid for ${Math.round((CONFIG_CACHE_TTL_MS - (Date.now() - config.fetched_at)) / 1000)}s)`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    }
+    try {
+        const config = await client.getProjectConfig(projectId);
+        session.projectConfig = config;
+        const pageList = config.pages
+            .map((p) => `  • ${p.page_key} → ${p.url}${p.description ? ` (${p.description})` : ""}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `✅ Project loaded: ${config.name} (${config.project_id})`,
+                        ``,
+                        `Pages:`,
+                        pageList,
+                        ``,
+                        `Trigger threshold: ${config.trigger_threshold}`,
+                        config.constraint_bundle.user_goal
+                            ? `User goal: ${config.constraint_bundle.user_goal}`
+                            : "",
+                        config.constraint_bundle.do_not_flag.length > 0
+                            ? `Do not flag: ${config.constraint_bundle.do_not_flag.join(", ")}`
+                            : "",
+                        ``,
+                        `You may now call explainui_analyze for any page_key listed above.`,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        if (err instanceof ExplainUIError) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Failed to load project: ${err.message}\nCode: ${err.code}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Failed to load project: ${err.message}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * explainui_analyze — Capture screenshots + run UX QA analysis.
+ */
+export async function analyze(session, client, args) {
+    // Verify project is attached
+    if (!session.projectConfig) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "❌ No project loaded. Call explainui_attach_project first.",
+                },
+            ],
+        };
+    }
+    if (session.projectConfig.project_id !== args.project_id) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Project mismatch. Session has ${session.projectConfig.project_id} but you requested ${args.project_id}. Call explainui_attach_project with the correct project.`,
+                },
+            ],
+        };
+    }
+    // Find the page URL
+    const pageConfig = session.projectConfig.pages.find((p) => p.page_key === args.page_key);
+    if (!pageConfig) {
+        const available = session.projectConfig.pages
+            .map((p) => p.page_key)
+            .join(", ");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Unknown page_key: "${args.page_key}". Available: ${available}`,
+                },
+            ],
+        };
+    }
+    // Step 1: Capture screenshots
+    let capture;
+    try {
+        capture = await captureAllViewports(pageConfig.url);
+    }
+    catch (err) {
+        if (err instanceof ExplainUIError) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Screenshot capture failed: ${err.message}\nCode: ${err.code}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Screenshot capture failed: ${err.message}`,
+                },
+            ],
+        };
+    }
+    // Step 2: Send to API
+    try {
+        const response = await client.analyze({
+            project_id: args.project_id,
+            page_key: args.page_key,
+            iteration: args.iteration,
+            this_iteration: args.this_iteration,
+            license_key: "", // Filled by client
+            screenshots_base64: capture.screenshots.map((s) => s.data),
+            screenshot_labels: capture.screenshots.map((s) => s.label),
+            git_snapshot_hash: args.git_snapshot_hash,
+        });
+        // Step 3: Format response for Claude
+        return { content: [{ type: "text", text: formatResponse(response) }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Analysis API call failed: ${err.message}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * explainui_close_project — Session cleanup.
+ */
+export async function closeProject(session, _client, args) {
+    const projectName = session.projectConfig?.name || args.project_id;
+    // Clean up browser
+    await closeBrowser();
+    // Clear session
+    session.projectConfig = null;
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `✅ ExplainUI session closed for ${projectName}.`,
+                    `Reason: ${args.reason}`,
+                    ``,
+                    `All iterations and screenshots are preserved in the dashboard.`,
+                    `Browser resources released.`,
+                ].join("\n"),
+            },
+        ],
+    };
+}
+// ── Response Formatter ─────────────────────────────────────────────────────
+function formatResponse(resp) {
+    const lines = [];
+    if (resp.error) {
+        lines.push(`❌ Analysis Error`);
+        lines.push(`Code: ${resp.error.code}`);
+        lines.push(`Message: ${resp.error.message}`);
+        if (resp.error.hint)
+            lines.push(`Hint: ${resp.error.hint}`);
+        return lines.join("\n");
+    }
+    const emoji = resp.pass ? "✅" : "🔧";
+    lines.push(`${emoji} UX QA Result — ${resp.page_key} iteration ${resp.iteration}`);
+    lines.push(`Pass: ${resp.pass}`);
+    lines.push(`Next action: ${resp.next_action}`);
+    lines.push("");
+    // Checks summary
+    if (resp.checks) {
+        lines.push("Checks:");
+        for (const [check, result] of Object.entries(resp.checks)) {
+            const r = result;
+            const icon = r.pass ? "✅" : "❌";
+            lines.push(`  ${icon} ${check}: ${r.pass ? "pass" : `${r.issues_found} issue(s)`}`);
+        }
+        lines.push("");
+    }
+    // Issues
+    if (resp.issues && resp.issues.length > 0) {
+        lines.push(`Issues (${resp.issues.length}):`);
+        for (const issue of resp.issues) {
+            lines.push(`  [${issue.severity.toUpperCase()}] ${issue.id}: ${issue.summary}`);
+            lines.push(`    Type: ${issue.type}`);
+            lines.push(`    Location: ${issue.location.viewport} — ${issue.location.element_description}`);
+            lines.push(`    Confidence: ${(issue.confidence * 100).toFixed(0)}%`);
+            lines.push(`    Fix: ${issue.fix_suggestion}`);
+            lines.push("");
+        }
+    }
+    if (resp.deprecation_warning) {
+        lines.push(`⚠️ ${resp.deprecation_warning}`);
+    }
+    if (resp.analysis_duration_ms) {
+        lines.push(`(Analysis took ${resp.analysis_duration_ms}ms)`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ExplainUI MCP — TypeScript Types
+ * Mirrors the Python schema.py models for the MCP side.
+ */
+export interface ExplainUISession {
+    projectConfig: ProjectConfig | null;
+    platform: "claude_desktop" | "cursor" | "cline" | "windsurf" | "unknown";
+}
+export interface ProjectConfig {
+    project_id: string;
+    name: string;
+    pages: PageConfig[];
+    constraint_bundle: ConstraintBundle;
+    trigger_threshold: "every_change" | "major_features" | "manual_only";
+    fetched_at: number;
+}
+export interface PageConfig {
+    page_key: string;
+    url: string;
+    description: string;
+}
+export interface ConstraintBundle {
+    user_goal: string;
+    user_enforced_constraints: string[];
+    do_not_flag: string[];
+}
+export interface ViewportDef {
+    label: string;
+    width: number;
+    height: number;
+    scrolls: number;
+}
+export declare const VIEWPORTS: ViewportDef[];
+export interface Screenshot {
+    label: string;
+    viewport: string;
+    scroll_index: number;
+    data: string;
+}
+export interface CaptureResult {
+    screenshots: Screenshot[];
+    capture_duration_ms: number;
+}
+export interface AnalyzeRequest {
+    project_id: string;
+    page_key: string;
+    iteration: number;
+    this_iteration: string;
+    license_key: string;
+    screenshots_base64: string[];
+    screenshot_labels: string[];
+    git_snapshot_hash?: string | null;
+    constraint_bundle?: ConstraintBundle;
+    mcp_version?: string;
+}
+export interface AnalyzeResponse {
+    project_id: string;
+    page_key: string;
+    iteration: number;
+    pass: boolean;
+    next_action: "fix" | "done" | "review_human" | "error";
+    checks?: Record<string, unknown>;
+    issues?: Issue[];
+    error?: AnalysisError | null;
+    deprecation_warning?: string | null;
+    analysis_duration_ms?: number;
+}
+export interface Issue {
+    id: string;
+    type: string;
+    severity: string;
+    summary: string;
+    location: {
+        viewport: string;
+        bbox: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+        element_description: string;
+    };
+    confidence: number;
+    fix_suggestion: string;
+}
+export interface AnalysisError {
+    code: string;
+    message: string;
+    hint?: string;
+    upgrade_url?: string;
+}
+export interface VersionInfo {
+    api_version: string;
+    min_mcp_version: string;
+    deprecation_warning: string | null;
+}
+export declare class ExplainUIError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * ExplainUI MCP — TypeScript Types
+ * Mirrors the Python schema.py models for the MCP side.
+ */
+export const VIEWPORTS = [
+    { label: "desktop_1280", width: 1280, height: 800, scrolls: 3 },
+    { label: "tablet_768", width: 768, height: 1024, scrolls: 2 },
+    { label: "mobile_375", width: 375, height: 812, scrolls: 2 },
+];
+// ── Error ──────────────────────────────────────────────────────────────────
+export class ExplainUIError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ExplainUIError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqCH,MAAM,CAAC,MAAM,SAAS,GAAkB;IACtC,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE;IAC/D,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;IAC7D,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE;CAC7D,CAAC;AAsEF,8EAA8E;AAC9E,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,IAAI,CAAS;IACb,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@explainui/mcp",
+  "version": "0.1.0-beta.1",
+  "description": "ExplainUI MCP server — silent UX QA in your AI agent workflow",
+  "bin": {
+    "explainui-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "postinstall": "playwright install chromium --quiet || true"
+  },
+  "keywords": [
+    "mcp",
+    "ux",
+    "qa",
+    "playwright",
+    "claude",
+    "cursor",
+    "ai",
+    "explainui"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.13.6",
+    "playwright": "^1.58.2",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  }
+}