@nyx-intelligence/val-mcp 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @nyx-intelligence/val-mcp
+
+Val is a **100% MCP QA agent** for vibecoders. It drives a real browser
+(Playwright + Chromium) to catch UX/functional bugs in your app, and exposes
+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)
+
+- 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>`
+
+UX/functional only — **not** security/pentest.
+
+## Install (MCP)
+
+Add to your MCP client config (e.g. Claude Code / Cursor):
+
+```json
+{
+  "mcpServers": {
+    "val": { "command": "npx", "args": ["-y", "@nyx-intelligence/val-mcp"] }
+  }
+}
+```
+
+First run downloads Chromium if needed (`npx playwright install chromium`).
+
+## Tools
+
+- `val_scan({ url, maxPages? })` — crawl an app and report all 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.
+
+## Test without an MCP client
+
+```bash
+val-mcp scan http://localhost:3000 20
+```

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/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. */
+async function runCli(args) {
+    const [cmd, url, maxPagesArg] = args;
+    if (cmd === "scan" && url) {
+        const maxPages = Number(maxPagesArg) || 12;
+        const { findings, pagesVisited } = await scanSite(url, { maxPages });
+        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);
+}
+/** Default mode: MCP server over stdio. */
+async function runServer() {
+    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" });
+    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)"),
+        },
+    }, 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)}` },
+            ],
+        };
+    });
+    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") },
+    }, 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)}` },
+                ],
+            };
+        }
+        finally {
+            await browser.close();
+        }
+    });
+    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)"),
+        },
+    }, async ({ url, fullPage }) => {
+        const data = await screenshot(url, fullPage ?? false);
+        return { content: [{ type: "image", data, mimeType: "image/png" }] };
+    });
+    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") {
+    runCli(args).catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}
+else {
+    runServer().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/report.js

@@ -0,0 +1,26 @@
+const RANK = { high: 0, medium: 1, low: 2 };
+/** Render findings as a readable, agent-friendly report. */
+export function formatReport(findings, pagesVisited) {
+    const counts = { high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    const lines = [];
+    lines.push(`Val scan: ${pagesVisited.length} page(s) crawled, ${findings.length} finding(s) — ` +
+        `${counts.high} high, ${counts.medium} medium, ${counts.low} low.`);
+    if (findings.length === 0) {
+        lines.push("All green. No UX bugs detected on the crawled pages.");
+    }
+    else {
+        lines.push("");
+        const sorted = [...findings].sort((a, b) => RANK[a.severity] - RANK[b.severity]);
+        for (const f of sorted) {
+            lines.push(`[${f.severity.toUpperCase()}] ${f.type} — ${f.page}`);
+            lines.push(`   ${f.detail}${f.evidence ? `  (${f.evidence})` : ""}`);
+        }
+    }
+    lines.push("");
+    lines.push("Pages crawled:");
+    for (const p of pagesVisited)
+        lines.push(`  - ${p}`);
+    return lines.join("\n");
+}

package/dist/scanner.js

@@ -0,0 +1,148 @@
+import { chromium } from "playwright";
+let _seq = 0;
+function finding(type, severity, page, detail, evidence) {
+    return { id: `f${++_seq}`, type, severity, page, detail, evidence };
+}
+/** Strip the hash and normalize so we don't visit the same page twice. */
+function normalize(u) {
+    try {
+        const url = new URL(u);
+        url.hash = "";
+        return url.toString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Load one page in a fresh context, capture browser-level signals
+ * (HTTP status, uncaught errors, console errors, failed responses,
+ * broken images, missing title) and the outgoing links.
+ */
+export async function checkPage(browser, url, timeoutMs = 20000) {
+    const ctx = await browser.newContext();
+    const page = await ctx.newPage();
+    const findings = [];
+    const consoleErrors = new Set();
+    const pageErrors = new Set();
+    const netErrors = new Map();
+    page.on("console", (m) => {
+        if (m.type() !== "error")
+            return;
+        const t = m.text();
+        // Browser-generated "Failed to load resource" lines just duplicate the
+        // network-error findings, so drop them to keep the report clean.
+        if (/Failed to load resource/i.test(t))
+            return;
+        consoleErrors.add(t.slice(0, 300));
+    });
+    page.on("pageerror", (e) => pageErrors.add((e.message || String(e)).slice(0, 300)));
+    page.on("response", (r) => {
+        const s = r.status();
+        if (s >= 400)
+            netErrors.set(r.url(), s);
+    });
+    let links = [];
+    let mainUrl = url;
+    try {
+        const resp = await page.goto(url, { waitUntil: "load", timeout: timeoutMs });
+        mainUrl = resp?.url() ?? url;
+        const status = resp?.status() ?? 0;
+        if (status >= 400)
+            findings.push(finding("page-status", "high", url, `Page returned HTTP ${status}`, String(status)));
+        // let late JS / lazy images settle
+        await page.waitForTimeout(900);
+        const title = (await page.title()).trim();
+        if (!title)
+            findings.push(finding("missing-title", "low", url, "Page has no <title>"));
+        const dom = await page.evaluate(() => {
+            const links = Array.from(document.querySelectorAll("a[href]"))
+                .map((a) => a.href)
+                .filter((h) => h.startsWith("http"));
+            const brokenImgs = Array.from(document.querySelectorAll("img"))
+                .filter((img) => {
+                const i = img;
+                return i.complete && i.naturalWidth === 0 && !!(i.currentSrc || i.src);
+            })
+                .map((img) => img.currentSrc || img.src);
+            return { links, brokenImgs };
+        });
+        links = dom.links;
+        for (const src of new Set(dom.brokenImgs)) {
+            findings.push(finding("broken-image", "medium", url, "Image failed to load", src));
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        findings.push(finding("page-load", "high", url, `Page failed to load: ${msg}`));
+    }
+    for (const t of pageErrors)
+        findings.push(finding("page-error", "high", url, `Uncaught JS error: ${t}`));
+    for (const t of consoleErrors)
+        findings.push(finding("console-error", "medium", url, `Console error: ${t}`));
+    for (const [u, s] of netErrors) {
+        if (u === mainUrl)
+            continue; // the main document status is already reported as page-status
+        findings.push(finding("network-error", s >= 500 ? "high" : "medium", url, `Resource returned HTTP ${s}`, u));
+    }
+    await ctx.close();
+    return { findings, links };
+}
+/** BFS-crawl same-origin pages from startUrl and check each one. */
+export async function scanSite(startUrl, opts = {}) {
+    const maxPages = opts.maxPages ?? 12;
+    const timeoutMs = opts.timeoutMs ?? 20000;
+    const start = normalize(startUrl);
+    if (!start)
+        throw new Error(`Invalid URL: ${startUrl}`);
+    const origin = new URL(start).origin;
+    const browser = await chromium.launch({ headless: true });
+    const findings = [];
+    const visited = new Set();
+    const queued = new Set([start]);
+    const queue = [start];
+    const pagesVisited = [];
+    try {
+        while (queue.length > 0 && pagesVisited.length < maxPages) {
+            const url = queue.shift();
+            if (visited.has(url))
+                continue;
+            visited.add(url);
+            const res = await checkPage(browser, url, timeoutMs);
+            findings.push(...res.findings);
+            pagesVisited.push(url);
+            for (const link of res.links) {
+                const n = normalize(link);
+                if (!n || queued.has(n))
+                    continue;
+                try {
+                    if (new URL(n).origin === origin) {
+                        queued.add(n);
+                        queue.push(n);
+                    }
+                }
+                catch {
+                    /* ignore unparseable links */
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return { findings, pagesVisited };
+}
+/** Screenshot a single page, return base64 PNG. */
+export async function screenshot(url, fullPage = false, timeoutMs = 20000) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        await page.goto(url, { waitUntil: "load", timeout: timeoutMs });
+        await page.waitForTimeout(700);
+        const buf = await page.screenshot({ fullPage, type: "png" });
+        return buf.toString("base64");
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nyx-intelligence/val-mcp",
+  "version": "0.1.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",
+  "bin": {
+    "val-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "scan": "node dist/index.js scan",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "playwright": "^1.49.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}