@nyx-intelligence/val-mcp 0.1.0 → 0.3.0

package/README.md

@@ -6,14 +6,15 @@ them as tools your coding assistant can call. Val itself spends **no AI tokens**
 detection is deterministic and local; your agent (Claude Code, Cursor, Windsurf)
 does the reasoning and the fixing on your own key.
 
-## What it catches (v0)
+## What it catches
 
-- Broken links & 404s (same-origin pages that return HTTP ≥ 400)
-- Uncaught JS errors (`pageerror`)
-- Console errors
-- Failed network requests (4xx/5xx resources and API calls)
-- Broken images (failed to load)
-- Missing `<title>`
+Passive (crawl): broken links & 404s, uncaught JS errors, console errors,
+failed network requests (4xx/5xx), broken images, missing `<title>`.
+
+Interactive (the agent drives the browser): **dead buttons** (clicks every
+button, flags the ones with no effect or that throw) and **broken funnels**
+(walk signup / checkout step by step, filling forms, catching errors at each
+step).
 
 UX/functional only — **not** security/pentest.
 
@@ -33,15 +34,23 @@ First run downloads Chromium if needed (`npx playwright install chromium`).
 
 ## Tools
 
-- `val_scan({ url, maxPages? })` — crawl an app and report all findings. Run first.
+Passive crawl:
+- `val_scan({ url, maxPages? })` — crawl an app and report all passive findings. Run first.
 - `val_check({ url })` — re-check one page after a fix (the "verify" step).
 - `val_screenshot({ url, fullPage? })` — PNG of a page for visual reasoning.
 
-The detect → fix → verify loop: your agent calls `val_scan`, fixes the code,
-then calls `val_check` on the affected page, repeating until everything is green.
+Live interaction (drive these to click everything and walk funnels):
+- `val_open({ url })` — start a browser session at a URL.
+- `val_snapshot()` — list interactive elements, each with a `[ref]`.
+- `val_click({ target })` — click a `[ref]` or visible text; reports dead controls + errors.
+- `val_type({ target, text })` — fill a field (signup / checkout form).
+- `val_exercise()` — click EVERY button on the page; report which are dead or throw.
+- `val_state()` — current URL + errors since the last action.
+- `val_close()` — end the session.
 
 ## Test without an MCP client
 
 ```bash
 val-mcp scan http://localhost:3000 20
+val-mcp exercise http://localhost:3000
 ```

package/dist/index.js

@@ -1,76 +1,157 @@
 #!/usr/bin/env node
 import { scanSite, checkPage, screenshot } from "./scanner.js";
 import { formatReport } from "./report.js";
-/** CLI mode: `val-mcp scan <url> [maxPages]` — for testing without an MCP client. */
+import { session } from "./session.js";
+function fmtAction(r) {
+    const lines = [`${r.ok ? "ok" : "warn"} · ${r.title || "(no title)"} · ${r.url}`];
+    if (r.note)
+        lines.push(`note: ${r.note}`);
+    if (r.navigatedTo && r.navigatedTo !== r.url)
+        lines.push(`navigated: ${r.navigatedTo}`);
+    for (const e of r.newPageErrors)
+        lines.push(`JS error: ${e}`);
+    for (const e of r.newConsoleErrors)
+        lines.push(`console error: ${e}`);
+    for (const n of r.newNetworkErrors)
+        lines.push(`network ${n.status}: ${n.url}`);
+    return lines.join("\n");
+}
+function fmtSnapshot(els) {
+    if (els.length === 0)
+        return "No interactive elements found.";
+    return els.map((e) => `[${e.ref}] ${e.kind}  ${e.text || "—"}${e.attrs ? `  (${e.attrs})` : ""}`).join("\n");
+}
+// ───────────────────────── CLI (testing without an MCP client) ─────────────────────────
 async function runCli(args) {
-    const [cmd, url, maxPagesArg] = args;
+    const [cmd, url, arg2] = args;
     if (cmd === "scan" && url) {
-        const maxPages = Number(maxPagesArg) || 12;
-        const { findings, pagesVisited } = await scanSite(url, { maxPages });
+        const { findings, pagesVisited } = await scanSite(url, { maxPages: Number(arg2) || 12 });
         console.log(formatReport(findings, pagesVisited));
-        process.exit(0);
     }
-    console.error("Usage:\n  val-mcp scan <url> [maxPages]   run a scan and print the report\n  val-mcp                         start the MCP server on stdio");
-    process.exit(1);
+    else if (cmd === "exercise" && url) {
+        console.log(fmtAction(await session.open(url)));
+        const res = await session.exercise();
+        console.log(`\nexercised ${res.tested} button(s): ${res.dead.length} dead, ${res.errored.length} errored`);
+        for (const d of res.dead)
+            console.log(`  DEAD: ${d}`);
+        for (const e of res.errored)
+            console.log(`  ERROR: ${e.el} — ${e.error}`);
+        await session.close();
+    }
+    else {
+        console.error("Usage:\n  val-mcp scan <url> [maxPages]\n  val-mcp exercise <url>\n  val-mcp            (start MCP server on stdio)");
+        process.exit(1);
+    }
+    process.exit(0);
 }
-/** Default mode: MCP server over stdio. */
+// ───────────────────────── MCP server ─────────────────────────
 async function runServer() {
+    // License gate — no active subscription, no tools.
+    const apiBase = process.env.VAL_API_BASE || "https://val.nyx-intelligence.com";
+    try {
+        const res = await fetch(`${apiBase}/api/license/validate`, {
+            headers: { Authorization: `Bearer ${process.env.VAL_LICENSE_KEY || ""}` },
+        });
+        const lic = (await res.json());
+        if (!lic.valid) {
+            console.error("Val: no active subscription for this VAL_LICENSE_KEY. Subscribe at https://val.nyx-intelligence.com");
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error("Val: could not verify your license (check VAL_LICENSE_KEY and connectivity).");
+        process.exit(1);
+    }
     const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
     const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
     const { chromium } = await import("playwright");
     const { z } = await import("zod");
-    const server = new McpServer({ name: "val", version: "0.1.0" });
+    const server = new McpServer({ name: "val", version: "0.3.0" });
+    const text = (t) => ({ content: [{ type: "text", text: t }] });
+    // ── Passive crawl ──
     server.registerTool("val_scan", {
-        title: "Scan an app for UX bugs",
-        description: "Crawl an app (localhost or live URL), following same-origin links, and report UX/functional bugs: broken links and 404s, uncaught JS errors, console errors, failed network requests, broken images, missing titles. Returns a prioritized list with the page each bug is on. Run this first.",
-        inputSchema: {
-            url: z.string().describe("Start URL, e.g. http://localhost:3000"),
-            maxPages: z.number().int().min(1).max(50).optional().describe("Max pages to crawl (default 12)"),
-        },
+        title: "Scan an app for UX bugs (crawl)",
+        description: "Crawl an app (localhost or live), following same-origin links, and report passive bugs: broken links/404s, uncaught JS errors, console errors, failed network requests, broken images, missing titles. Good first pass. Does NOT click buttons or fill forms — use the val_open/val_click/val_type/val_exercise tools for that.",
+        inputSchema: { url: z.string(), maxPages: z.number().int().min(1).max(50).optional() },
     }, async ({ url, maxPages }) => {
         const { findings, pagesVisited } = await scanSite(url, { maxPages: maxPages ?? 12 });
-        return {
-            content: [
-                { type: "text", text: `${formatReport(findings, pagesVisited)}\n\nJSON:\n${JSON.stringify(findings)}` },
-            ],
-        };
+        return text(`${formatReport(findings, pagesVisited)}\n\nJSON:\n${JSON.stringify(findings)}`);
     });
     server.registerTool("val_check", {
         title: "Re-check one page (verify a fix)",
-        description: "Run the UX checks on a SINGLE page only. Use this after fixing a bug to confirm it is gone and nothing new broke on that page. This is the 'verify' half of the detect-fix-verify loop.",
-        inputSchema: { url: z.string().describe("The page URL to re-check") },
+        description: "Run the passive checks on a SINGLE page. Use after fixing a bug to confirm it is gone.",
+        inputSchema: { url: z.string() },
     }, async ({ url }) => {
         const browser = await chromium.launch({ headless: true });
         try {
             const { findings } = await checkPage(browser, url);
-            return {
-                content: [
-                    { type: "text", text: `${formatReport(findings, [url])}\n\nJSON:\n${JSON.stringify(findings)}` },
-                ],
-            };
+            return text(`${formatReport(findings, [url])}\n\nJSON:\n${JSON.stringify(findings)}`);
         }
         finally {
             await browser.close();
         }
     });
+    // ── Interactive session (walk funnels, click everything) ──
+    server.registerTool("val_open", {
+        title: "Open a page in the live session",
+        description: "Start (or reuse) the browser session and navigate to a URL. Returns the page state and any load errors. This begins an interactive session you drive with val_snapshot / val_click / val_type to walk a funnel (e.g. sign up, checkout).",
+        inputSchema: { url: z.string() },
+    }, async ({ url }) => text(fmtAction(await session.open(url))));
+    server.registerTool("val_snapshot", {
+        title: "List the interactive elements on the current page",
+        description: "Return every clickable/fillable element on the current page with a [ref] you can pass to val_click / val_type, plus its kind and label. Call this to see what you can act on before clicking or typing.",
+        inputSchema: {},
+    }, async () => text(fmtSnapshot(await session.snapshot())));
+    server.registerTool("val_click", {
+        title: "Click an element",
+        description: "Click an element by its [ref] (from val_snapshot) or by visible text. Returns whether anything changed, where it navigated, and any errors triggered. If nothing changes and no error fires, the control is flagged as a possible dead button.",
+        inputSchema: { target: z.string().describe("A ref like 'v3' from val_snapshot, or the visible button/link text") },
+    }, async ({ target }) => text(fmtAction(await session.click(target))));
+    server.registerTool("val_type", {
+        title: "Type into a field",
+        description: "Fill an input/textarea (by [ref] or label) with text. Use to fill a signup or checkout form, then val_click the submit button.",
+        inputSchema: { target: z.string().describe("A ref like 'v2' or the field label/placeholder"), text: z.string() },
+    }, async ({ target, text: value }) => text(fmtAction(await session.type(target, value))));
+    server.registerTool("val_exercise", {
+        title: "Click every button on the current page",
+        description: "Deterministically click every visible button on the current page (returning to the page after any navigation) and report which ones are DEAD (no effect, no error, no network) or which throw a JS error. The fast way to answer 'is any button broken on this screen?'.",
+        inputSchema: {},
+    }, async () => {
+        const r = await session.exercise();
+        const lines = [`Exercised ${r.tested} button(s): ${r.dead.length} dead, ${r.errored.length} errored.`];
+        for (const d of r.dead)
+            lines.push(`DEAD: ${d}`);
+        for (const e of r.errored)
+            lines.push(`ERROR: ${e.el} — ${e.error}`);
+        return text(lines.join("\n"));
+    });
+    server.registerTool("val_state", {
+        title: "Current page state + new errors",
+        description: "Return the current URL/title and any console/JS/network errors captured since the last action. Use to verify a step did not break anything.",
+        inputSchema: {},
+    }, async () => text(fmtAction(await session.state())));
     server.registerTool("val_screenshot", {
         title: "Screenshot a page",
-        description: "Capture a PNG screenshot of a page so you can reason about layout or visual issues.",
-        inputSchema: {
-            url: z.string().describe("The page URL to screenshot"),
-            fullPage: z.boolean().optional().describe("Capture the full scrollable page (default false)"),
-        },
+        description: "Capture a PNG of a URL so you can reason about layout/visual issues.",
+        inputSchema: { url: z.string(), fullPage: z.boolean().optional() },
     }, async ({ url, fullPage }) => {
         const data = await screenshot(url, fullPage ?? false);
         return { content: [{ type: "image", data, mimeType: "image/png" }] };
     });
+    server.registerTool("val_close", {
+        title: "Close the session",
+        description: "Close the browser session when finished walking a flow.",
+        inputSchema: {},
+    }, async () => {
+        await session.close();
+        return text("session closed");
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // stdout is the MCP channel; logs go to stderr.
     console.error("val-mcp server running on stdio");
 }
 const args = process.argv.slice(2);
-if (args[0] === "scan") {
+if (args[0] === "scan" || args[0] === "exercise") {
     runCli(args).catch((e) => {
         console.error(e);
         process.exit(1);

package/dist/session.js

@@ -0,0 +1,209 @@
+import { chromium } from "playwright";
+function dedupe(a) {
+    return Array.from(new Set(a));
+}
+class ValSession {
+    browser;
+    page;
+    consoleErrors = [];
+    pageErrors = [];
+    netErrors = [];
+    async ensure() {
+        if (this.browser && this.page)
+            return this.page;
+        this.browser = await chromium.launch({ headless: true });
+        const ctx = await this.browser.newContext();
+        this.page = await ctx.newPage();
+        this.page.on("console", (m) => {
+            if (m.type() === "error" && !/Failed to load resource/i.test(m.text())) {
+                this.consoleErrors.push(m.text().slice(0, 300));
+            }
+        });
+        this.page.on("pageerror", (e) => this.pageErrors.push((e.message || String(e)).slice(0, 300)));
+        this.page.on("response", (r) => {
+            const s = r.status();
+            if (s >= 400)
+                this.netErrors.push({ url: r.url(), status: s });
+        });
+        return this.page;
+    }
+    /** Pull and clear the errors captured since the last drain. */
+    drain() {
+        return {
+            newConsoleErrors: dedupe(this.consoleErrors.splice(0)),
+            newPageErrors: dedupe(this.pageErrors.splice(0)),
+            newNetworkErrors: this.netErrors.splice(0),
+        };
+    }
+    /** A cheap signature of the page to detect whether an action changed anything. */
+    async sig() {
+        return this.page.evaluate(() => ({
+            url: location.href,
+            nodes: document.querySelectorAll("*").length,
+            text: document.body ? document.body.innerText.length : 0,
+        }));
+    }
+    async resolve(refOrText) {
+        const page = this.page;
+        const byRef = page.locator(`[data-val-ref="${refOrText}"]`);
+        if ((await byRef.count()) > 0)
+            return byRef.first();
+        return page.getByText(refOrText, { exact: false }).first();
+    }
+    async open(url) {
+        const page = await this.ensure();
+        this.drain();
+        let note;
+        try {
+            const resp = await page.goto(url, { waitUntil: "load", timeout: 25000 });
+            await page.waitForTimeout(800);
+            if (resp && resp.status() >= 400)
+                note = `Page returned HTTP ${resp.status()}`;
+        }
+        catch (e) {
+            note = `load failed: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        return { ok: !note, url: page.url(), title: await safeTitle(page), changed: true, navigatedTo: page.url(), ...this.drain(), note };
+    }
+    async snapshot() {
+        const page = await this.ensure();
+        return page.evaluate(() => {
+            const isVisible = (el) => {
+                const r = el.getBoundingClientRect();
+                const s = getComputedStyle(el);
+                return r.width > 0 && r.height > 0 && s.visibility !== "hidden" && s.display !== "none";
+            };
+            const sel = "a[href], button, [role=button], input:not([type=hidden]), select, textarea, [onclick]";
+            const els = Array.from(document.querySelectorAll(sel)).filter(isVisible).slice(0, 150);
+            return els.map((el, i) => {
+                const ref = `v${i}`;
+                el.setAttribute("data-val-ref", ref);
+                const tag = el.tagName.toLowerCase();
+                let kind = tag === "a" ? "link" : tag;
+                if (tag === "input")
+                    kind = el.type || "text";
+                if (el.getAttribute("role") === "button")
+                    kind = "button";
+                const input = el;
+                const text = (el.innerText ||
+                    input.value ||
+                    el.getAttribute("aria-label") ||
+                    input.placeholder ||
+                    "")
+                    .trim()
+                    .slice(0, 60);
+                const attrs = [
+                    tag === "a" ? `href=${el.getAttribute("href")}` : "",
+                    input.name ? `name=${input.name}` : "",
+                    input.type ? `type=${input.type}` : "",
+                ]
+                    .filter(Boolean)
+                    .join(" ");
+                return { ref, kind, text, attrs };
+            });
+        });
+    }
+    async click(refOrText) {
+        const page = await this.ensure();
+        this.drain();
+        const before = await this.sig();
+        let note;
+        let changed = false;
+        try {
+            const loc = await this.resolve(refOrText);
+            if ((await loc.count()) === 0) {
+                return { ok: false, url: before.url, title: await safeTitle(page), changed: false, ...this.drain(), note: `element not found: ${refOrText}` };
+            }
+            await loc.click({ timeout: 8000 });
+            await page.waitForTimeout(700);
+            const after = await this.sig();
+            changed = after.url !== before.url || after.nodes !== before.nodes || Math.abs(after.text - before.text) > 3;
+        }
+        catch (e) {
+            note = `click failed: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const errs = this.drain();
+        if (!note && !changed && errs.newPageErrors.length === 0 && errs.newConsoleErrors.length === 0 && errs.newNetworkErrors.length === 0) {
+            note = "no visible effect — possible dead control";
+        }
+        return { ok: !note, url: page.url(), title: await safeTitle(page), changed, navigatedTo: page.url() !== before.url ? page.url() : undefined, ...errs, note };
+    }
+    async type(refOrText, text) {
+        const page = await this.ensure();
+        this.drain();
+        let note;
+        try {
+            const loc = await this.resolve(refOrText);
+            await loc.fill(text, { timeout: 8000 });
+        }
+        catch (e) {
+            note = `type failed: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        return { ok: !note, url: page.url(), title: await safeTitle(page), changed: true, ...this.drain(), note };
+    }
+    /** Click every visible button on the current page; report dead + erroring ones. */
+    async exercise() {
+        const page = await this.ensure();
+        const tag = () => page.evaluate(() => {
+            const isVisible = (el) => {
+                const r = el.getBoundingClientRect();
+                return r.width > 0 && r.height > 0;
+            };
+            const els = Array.from(document.querySelectorAll("button, [role=button]")).filter(isVisible);
+            els.forEach((el, i) => el.setAttribute("data-val-ex", `e${i}`));
+            return els.map((el, i) => ({ ref: `e${i}`, text: (el.innerText || el.getAttribute("aria-label") || "").trim().slice(0, 40) }));
+        });
+        const buttons = await tag();
+        const dead = [];
+        const errored = [];
+        const startUrl = page.url();
+        for (const b of buttons) {
+            this.drain();
+            const before = await this.sig();
+            try {
+                const loc = page.locator(`[data-val-ex="${b.ref}"]`);
+                if ((await loc.count()) === 0)
+                    continue;
+                await loc.click({ timeout: 4000 });
+                await page.waitForTimeout(400);
+                if (page.url() !== startUrl) {
+                    await page.goBack({ waitUntil: "load" }).catch(() => { });
+                    await page.waitForTimeout(300);
+                    await tag(); // re-tag after navigating back
+                    continue;
+                }
+                const after = await this.sig();
+                const errs = this.drain();
+                const label = b.text || b.ref;
+                const moved = after.nodes !== before.nodes || Math.abs(after.text - before.text) > 3;
+                if (errs.newPageErrors.length)
+                    errored.push({ el: label, error: errs.newPageErrors[0] });
+                else if (!moved && errs.newConsoleErrors.length === 0 && errs.newNetworkErrors.length === 0)
+                    dead.push(label);
+            }
+            catch (e) {
+                errored.push({ el: b.text || b.ref, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return { tested: buttons.length, dead, errored };
+    }
+    async state() {
+        const page = await this.ensure();
+        return { ok: true, url: page.url(), title: await safeTitle(page), changed: false, ...this.drain() };
+    }
+    async close() {
+        await this.browser?.close().catch(() => { });
+        this.browser = undefined;
+        this.page = undefined;
+    }
+}
+async function safeTitle(page) {
+    try {
+        return await page.title();
+    }
+    catch {
+        return "";
+    }
+}
+/** One session per server process. */
+export const session = new ValSession();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyx-intelligence/val-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Val — a 100% MCP QA agent for vibecoders. Drives a real browser to catch UX bugs (broken links, 404s, console errors, broken images) so your coding agent can fix them.",
   "type": "module",
   "license": "UNLICENSED",