@validate.qa/mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,983 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/init.ts
+var init_exports = {};
+__export(init_exports, {
+  runInit: () => runInit
+});
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { resolve as resolve2, join } from "path";
+function parseInitArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--") && i + 1 < argv.length) {
+      args[arg.slice(2)] = argv[++i];
+    }
+  }
+  const apiUrl = args["api-url"] ?? process.env.VALIDATEQA_API_URL ?? "https://shared-server.up.railway.app";
+  const token = args["token"] ?? process.env.VALIDATEQA_TOKEN;
+  const projectId = args["project-id"] ?? process.env.VALIDATEQA_PROJECT_ID;
+  if (!token) {
+    console.error("\u274C Missing --token. Copy the full command from your Validate.QA dashboard.");
+    process.exit(1);
+  }
+  if (!projectId) {
+    console.error("\u274C Missing --project-id. Copy the full command from your Validate.QA dashboard.");
+    process.exit(1);
+  }
+  return { apiUrl: apiUrl.replace(/\/$/, ""), token, projectId };
+}
+function buildMcpEntry(config2) {
+  return {
+    command: "npx",
+    args: [
+      "-y",
+      "@validate.qa/mcp@latest",
+      "--api-url",
+      config2.apiUrl,
+      "--token",
+      config2.token,
+      "--project-id",
+      config2.projectId
+    ]
+  };
+}
+function writeConfigForIDE(cwd, target, entry) {
+  const dir = resolve2(cwd, target.configDir);
+  const filePath = resolve2(dir, target.configFile);
+  if (target.configDir !== "." && !existsSync(dir)) {
+    return "skipped";
+  }
+  let existing = {};
+  if (existsSync(filePath)) {
+    try {
+      existing = JSON.parse(readFileSync2(filePath, "utf-8"));
+    } catch {
+    }
+  }
+  const servers = existing[target.serversKey] ?? {};
+  const hadEntry = "validate.qa" in servers;
+  servers["validate.qa"] = entry;
+  existing[target.serversKey] = servers;
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+  return hadEntry ? "updated" : "created";
+}
+function runInit() {
+  const config2 = parseInitArgs(process.argv.slice(3));
+  const entry = buildMcpEntry(config2);
+  const cwd = process.cwd();
+  console.log("");
+  console.log("  Validate.QA \u2014 MCP Setup");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("");
+  let anyWritten = false;
+  for (const target of IDE_TARGETS) {
+    const result = writeConfigForIDE(cwd, target, entry);
+    if (result === "skipped") {
+      continue;
+    }
+    const file = join(target.configDir, target.configFile);
+    if (result === "created") {
+      console.log(`  \u2713 ${target.name} \u2014 created ${file}`);
+    } else {
+      console.log(`  \u2713 ${target.name} \u2014 updated ${file}`);
+    }
+    anyWritten = true;
+  }
+  if (!anyWritten) {
+    const target = IDE_TARGETS[0];
+    writeConfigForIDE(cwd, target, entry);
+    console.log(`  \u2713 Created ${target.configFile} (works with Claude Code)`);
+    console.log("");
+    console.log("  Tip: Create a .cursor/ or .windsurf/ directory and re-run to set up those IDEs too.");
+  }
+  console.log("");
+  console.log("  Next: restart your IDE or reload MCP servers.");
+  console.log('  Then ask your AI: "list my tests" to verify it works.');
+  console.log("");
+}
+var IDE_TARGETS;
+var init_init = __esm({
+  "src/init.ts"() {
+    "use strict";
+    IDE_TARGETS = [
+      { name: "Claude Code", configDir: ".", configFile: ".mcp.json", serversKey: "mcpServers" },
+      { name: "Cursor", configDir: ".cursor", configFile: "mcp.json", serversKey: "mcpServers" },
+      { name: "Windsurf", configDir: ".windsurf", configFile: "mcp.json", serversKey: "mcpServers" },
+      { name: "VS Code", configDir: ".vscode", configFile: "mcp.json", serversKey: "servers" }
+    ];
+  }
+});
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--") && i + 1 < argv.length) {
+      const key = arg.slice(2);
+      args[key] = argv[++i];
+    }
+  }
+  return args;
+}
+function loadDotFile() {
+  try {
+    const content = readFileSync(resolve(process.cwd(), ".validateqa.json"), "utf-8");
+    const json = JSON.parse(content);
+    return {
+      apiUrl: typeof json.apiUrl === "string" ? json.apiUrl : void 0,
+      projectId: typeof json.projectId === "string" ? json.projectId : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function resolveConfig() {
+  const cliArgs = parseArgs(process.argv.slice(2));
+  const dotFile = loadDotFile();
+  const apiUrl = cliArgs["api-url"] ?? process.env.VALIDATEQA_API_URL ?? dotFile.apiUrl;
+  const token = cliArgs["token"] ?? process.env.VALIDATEQA_TOKEN;
+  const projectId = cliArgs["project-id"] ?? process.env.VALIDATEQA_PROJECT_ID ?? dotFile.projectId;
+  if (!apiUrl) {
+    console.error("Missing required config: api-url (--api-url, VALIDATEQA_API_URL, or .validateqa.json)");
+    process.exit(1);
+  }
+  if (!token) {
+    console.error("Missing required config: token (--token or VALIDATEQA_TOKEN)");
+    process.exit(1);
+  }
+  if (!projectId) {
+    console.error("Missing required config: project-id (--project-id, VALIDATEQA_PROJECT_ID, or .validateqa.json)");
+    process.exit(1);
+  }
+  return { apiUrl: apiUrl.replace(/\/$/, ""), token, projectId };
+}
+
+// src/api-client.ts
+var ValidateQAClient = class {
+  constructor(baseUrl, token, projectId) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+    this.projectId = projectId;
+  }
+  async executeTool(tool2, args = {}) {
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}/api/mcp/execute`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.token}`,
+          "X-Project-Id": this.projectId,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ tool: tool2, args }),
+        signal: AbortSignal.timeout(12e4)
+      });
+    } catch (err) {
+      const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : "";
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Connection failed: ${msg}${cause ? ` (${cause})` : ""}`);
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({ error: res.statusText }));
+      throw new Error(body.error || `API error ${res.status}`);
+    }
+    return res.json();
+  }
+  async healthCheck() {
+    try {
+      const res = await fetch(`${this.baseUrl}/health`, {
+        signal: AbortSignal.timeout(5e3)
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/tools/index.ts
+import { z } from "zod";
+function tool(server2, client2, name, description, schema, annotations) {
+  const handler = async (args) => {
+    try {
+      const result = await client2.executeTool(name, args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        isError: true
+      };
+    }
+  };
+  if (annotations) {
+    server2.tool(name, description, schema, annotations, handler);
+  } else {
+    server2.tool(name, description, schema, handler);
+  }
+}
+function registerAllTools(server2, client2) {
+  tool(
+    server2,
+    client2,
+    "list_tests",
+    "List tests in the current project. Returns test name, status, suite, tags, confidence, and the last run result. Paginated \u2014 use limit/offset to page through all tests.",
+    {
+      status: z.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).optional().describe("Filter by test lifecycle status"),
+      suite: z.string().optional().describe("Filter by suite name"),
+      search: z.string().optional().describe("Search test names (case-insensitive substring match)"),
+      tag: z.string().optional().describe("Filter by tag (e.g. @regression, @smoke, @auth)"),
+      limit: z.number().optional().describe("Max results to return (default: 50, max: 200)"),
+      offset: z.number().optional().describe("Number of results to skip for pagination (default: 0)")
+    },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_test",
+    "Get details of a specific test: name, status, tags, steps, session, and the 5 most recent run results. Code is truncated to 200 lines \u2014 use get_test_code for the full Playwright code.",
+    { testId: z.string().describe("The test case ID") },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "run_test",
+    "Queue a test for execution. Creates a PENDING test run that will be picked up by an online runner. Returns the run ID.",
+    { testId: z.string().describe("The test case ID to run") }
+  );
+  tool(
+    server2,
+    client2,
+    "delete_test",
+    "Permanently delete a test case and all its run history. Cannot be undone.",
+    { testId: z.string().describe("The test case ID to delete") },
+    { destructiveHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "heal_test",
+    "Queue an AI healing run for a failing test. The AI agent replays the test in a real browser, analyzes the failure, and either fixes the Playwright code OR detects an application bug (quarantines the test with @bug-found if the app itself is broken, not the test).",
+    { testId: z.string().describe("The failing test case ID") }
+  );
+  tool(
+    server2,
+    client2,
+    "edit_test_code",
+    "Update the Playwright code, name, or tags of an existing test case. Read project://test-conventions for patterns and pitfalls. Code is validated \u2014 fix any warnings returned.",
+    {
+      testId: z.string().describe("The test case ID to edit"),
+      playwrightCode: z.string().optional().describe("New Playwright test code (full file replacement)"),
+      name: z.string().optional().describe("New test name"),
+      tags: z.array(z.string()).optional().describe('New tags array (e.g. ["@regression", "@smoke"])')
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "update_test_status",
+    "Change the lifecycle status of one or more tests (e.g. promote DRAFT\u2192ACTIVE, disable a flaky test).",
+    {
+      testIds: z.array(z.string()).describe("Test IDs to update"),
+      status: z.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).describe("New status to set")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "get_test_run",
+    "Get the status and result of a specific test run, including error details if it failed. Can look up by runId or get the latest run for a testId.",
+    {
+      runId: z.string().optional().describe("The test run ID"),
+      testId: z.string().optional().describe("Get the most recent run for this test case ID")
+    },
+    { readOnlyHint: true }
+  );
+  server2.tool(
+    "get_test_screenshots",
+    "Get screenshots from a specific test run as images the AI can actually see. Use this to visually inspect what happened during a failed or passing run.",
+    {
+      runId: z.string().describe("The test run ID to fetch screenshots from"),
+      limit: z.number().optional().describe("Max screenshots to return (default: 5, max: 10)")
+    },
+    { readOnlyHint: true },
+    async (args) => {
+      try {
+        const result = await client2.executeTool("get_test_screenshots", args);
+        if (!result.screenshots || result.screenshots.length === 0) {
+          return {
+            content: [{
+              type: "text",
+              text: `No screenshots available for run ${result.runId} (status: ${result.status})`
+            }]
+          };
+        }
+        const content = [
+          {
+            type: "text",
+            text: `Run ${result.runId} \u2014 status: ${result.status} \u2014 showing ${result.returned} of ${result.total} screenshot(s)`
+          }
+        ];
+        for (const shot of result.screenshots) {
+          content.push({ type: "image", data: shot.data, mimeType: shot.mimeType });
+        }
+        return { content };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "cancel_test_run",
+    "Cancel a pending or running test run. Can cancel by run ID or cancel the latest running batch.",
+    {
+      runId: z.string().optional().describe("The specific test run ID to cancel"),
+      cancelBatch: z.boolean().optional().describe("If true, cancel the latest batch run instead")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "batch_run_tests",
+    "Run multiple tests from the database individually. Filter by test IDs or suite name; omit both to run all ACTIVE tests. Each test executes in its own browser.",
+    {
+      testIds: z.array(z.string()).optional().describe("Specific test IDs to run"),
+      suite: z.string().optional().describe("Run all active tests in this suite")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "list_features",
+    "List all features with test counts and failure counts (last 24h). Use failingTests > 0 to identify which features need attention, then call get_test_failures({ suite: featureName }) to drill into the full error details for that feature.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "list_api_endpoints",
+    "List captured API endpoints for the current project. Optionally scope to a specific feature name.",
+    {
+      featureName: z.string().optional().describe("Optional feature name to scope the endpoint list")
+    },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_runner_health",
+    "Check whether the project's configured runners are online, including available device capabilities.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_project_overview",
+    "Get a workspace-level QA overview: test counts, pass rates, runner readiness, features, coverage gaps, variables, schedules, and notifications.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_reports_summary",
+    "Get a high-level report: total tests (active, never-run), 7-day pass rate, today's run count, and the 10 most recent test run results.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "list_schedules",
+    "List all scheduled test runs in the project.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "create_schedule",
+    "Create a new recurring test schedule. Runs all matching tests from the database on the configured interval.",
+    {
+      name: z.string().describe('Name for the schedule (e.g. "Nightly smoke tests")'),
+      mode: z.enum(["batch"]).describe("Run mode: batch (runs project tests from the database)"),
+      intervalMinutes: z.union([z.literal(60), z.literal(360), z.literal(720), z.literal(1440), z.literal(2880), z.literal(10080)]).describe("Interval in minutes: 60 (hourly), 360 (6h), 720 (12h), 1440 (daily), 2880 (2 days), 10080 (weekly)"),
+      tags: z.array(z.string()).optional().describe('Tags to filter which tests run (e.g. ["@smoke"]). Omit to run all ACTIVE tests.'),
+      autoHeal: z.boolean().optional().describe("Automatically heal failing tests after each run"),
+      enabled: z.boolean().optional().describe("Whether the schedule is active (default: true)"),
+      runImmediately: z.boolean().optional().describe("Whether to trigger the first run immediately (default: true)")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "update_schedule",
+    "Update an existing test schedule.",
+    {
+      scheduleId: z.string().describe("The schedule ID to update"),
+      name: z.string().optional().describe("New name for the schedule"),
+      intervalMinutes: z.union([z.literal(60), z.literal(360), z.literal(720), z.literal(1440), z.literal(2880), z.literal(10080)]).optional().describe("New interval in minutes"),
+      suite: z.string().optional().describe("New suite name to filter tests"),
+      tags: z.array(z.string()).optional().describe("New tag filter"),
+      autoHeal: z.boolean().optional().describe("Toggle auto-heal"),
+      enabled: z.boolean().optional().describe("Enable or disable the schedule")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "delete_schedule",
+    "Delete (remove) a test schedule permanently.",
+    { scheduleId: z.string().describe("The schedule ID to delete") },
+    { destructiveHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "run_schedule_now",
+    "Trigger a scheduled run immediately instead of waiting for the next scheduled time.",
+    { scheduleId: z.string().describe("The schedule ID to trigger") }
+  );
+  tool(
+    server2,
+    client2,
+    "get_variables",
+    "Get all test variables (environment variables) for the current project. Secrets are redacted.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "set_variable",
+    "Set or update a test variable (environment variable) for the project. Used to configure base URLs, credentials, etc.",
+    {
+      key: z.string().describe("Variable name (e.g. BASE_URL, TEST_USER_EMAIL, API_KEY)"),
+      value: z.string().describe("Variable value. Set value to empty string to remove a variable."),
+      secret: z.boolean().optional().describe("Whether this variable is a secret (will be redacted in UI)")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "create_test",
+    "Create a new test case with Playwright code. Read project://test-conventions for templates and pitfalls BEFORE writing code. The test starts as DRAFT \u2014 auto-runs and auto-promotes to ACTIVE on pass. IMPORTANT: (1) Set suite to the EXACT feature name. (2) After creating all tests for a feature, you MUST call add_api_endpoints.",
+    {
+      name: z.string().describe('Test name (e.g. "Login \u2014 Happy Path")'),
+      playwrightCode: z.string().describe("Full Playwright test code"),
+      suite: z.string().optional().describe('MUST match an existing feature name exactly to link the test to that feature (e.g. "Authentication", not "Auth Tests")'),
+      tags: z.array(z.string()).optional().describe('Tags (e.g. ["@smoke", "@auth"])')
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "get_feature",
+    "Get detailed info about a feature including its pages, test plans, existing tests with lastRunStatus, and AI insights.",
+    { featureName: z.string().describe("The feature name (case-insensitive match)") },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "create_feature",
+    "Create a new feature with page routes. Read the developer's route files to provide accurate page URLs. Pages are used for coverage tracking and site map.",
+    {
+      name: z.string().describe('Feature name (e.g. "Checkout Flow")'),
+      description: z.string().optional().describe("What the feature does and what to test"),
+      pages: z.array(z.string()).describe('Page routes this feature covers (e.g. ["/checkout", "/checkout/payment"]). Required for test generation.'),
+      criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level (default: medium)")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "get_test_code",
+    "Get the full (untruncated) Playwright test code for a test case. Use this when you need to read, analyze, or prepare edits for the complete test code.",
+    { testId: z.string().describe("The test case ID") },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "set_runner_preference",
+    "Switch between cloud and local runner for test execution.",
+    { preference: z.enum(["cloud", "local"]).describe("Runner type: cloud (shared infrastructure) or local (runs on your machine)") }
+  );
+  tool(
+    server2,
+    client2,
+    "toggle_auto_heal",
+    "Enable or disable automatic AI healing when tests fail in batch or suite runs.",
+    { enabled: z.boolean().describe("true to enable auto-heal, false to disable") }
+  );
+  tool(
+    server2,
+    client2,
+    "list_test_data",
+    "List all test data sets in the project. Each set contains key-value pairs injected into AI prompts and test runs.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "create_test_data",
+    "Create a new test data set with key-value pairs. Max 200 entries per set.",
+    {
+      name: z.string().describe("Name of the test data set (max 100 chars)"),
+      description: z.string().optional().describe("Optional description (max 1000 chars)"),
+      data: z.record(z.string()).describe('Key-value pairs (e.g. {"email": "test@example.com", "password": "secret"})')
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "delete_test_data",
+    "Delete a test data set by ID.",
+    { dataSetId: z.string().describe("The test data set ID to delete") },
+    { destructiveHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "update_feature",
+    "Update a feature's name, description, pages, or criticality.",
+    {
+      featureId: z.string().describe("The feature ID to update"),
+      name: z.string().optional().describe("New feature name"),
+      description: z.string().optional().describe("New description"),
+      pages: z.array(z.string()).optional().describe("Updated page routes"),
+      criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "archive_feature",
+    "Archive a feature (soft delete). Archived features are hidden from the dashboard but can be restored.",
+    { featureId: z.string().describe("The feature ID to archive") },
+    { destructiveHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_site_map_coverage",
+    "Get site map coverage statistics: total pages, pages with tests, elements covered, coverage percentage, and per-page breakdown.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "list_bugs",
+    "Get all detected bugs: app bugs (quarantined tests with @bug-found), security findings, and flaky tests.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "flag_as_bug",
+    "Mark a failing test as a confirmed application bug \u2014 quarantines it with @bug-found and records the bug description. Use when the failure is caused by broken app behaviour, NOT a test script issue. Do NOT use for selector changes or timeout failures \u2014 use heal_test or edit_test_code for those.",
+    {
+      testId: z.string().describe("The failing test case ID"),
+      description: z.string().describe('What is broken in the application (e.g. "POST /api/checkout returns 500 when payment method is valid")')
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "run_security_audit",
+    'Run an AI security audit on captured API traffic. Requires prior browser-based test execution (discovery or capture) \u2014 analyzes real network traffic, not just registered endpoints. If no traffic exists, the developer can trigger "Security Audit" from the Dashboard which launches a live browser to capture it.',
+    {}
+  );
+  tool(
+    server2,
+    client2,
+    "list_security_findings",
+    "List security audit findings with optional filters. Returns severity, category, status, and affected endpoints.",
+    {
+      severity: z.enum(["critical", "high", "medium", "low", "info"]).optional().describe("Filter by severity"),
+      status: z.enum(["open", "acknowledged", "resolved", "false-positive"]).optional().describe("Filter by status")
+    },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "set_app_brief",
+    "Set or update the project's application brief \u2014 a description of the app used by AI for better test generation.",
+    { appBrief: z.string().describe("Application description. Set empty to clear.") }
+  );
+  tool(
+    server2,
+    client2,
+    "get_coverage_summary",
+    "Get feature-level test coverage: planned vs existing vs passing tests, plus API endpoint coverage. Shows uncoveredEndpoints per feature \u2014 use this to find which API endpoints still need tests.",
+    {},
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "run_draft_tests",
+    "Run all DRAFT tests to verify them. Tests that pass auto-promote to ACTIVE. Optionally scope to a feature.",
+    {
+      featureName: z.string().optional().describe("Only run drafts for this feature (optional)")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "setup_project",
+    'One-shot project setup from codebase knowledge. Sets app brief, base URL, test credentials, and creates features with pages \u2014 all in one call. Use this when a developer says "set up test coverage for my app."',
+    {
+      appBrief: z.string().optional().describe("Description of the application (what it does, key features, tech stack)"),
+      baseUrl: z.string().describe('Application base URL (e.g. "https://myapp.com" or "http://localhost:3000")'),
+      testCredentials: z.object({
+        email: z.string().optional().describe("Test user email"),
+        password: z.string().optional().describe("Test user password")
+      }).optional().describe("Login credentials for test execution"),
+      features: z.array(z.object({
+        name: z.string().describe("Feature name"),
+        description: z.string().optional().describe("What the feature does"),
+        pages: z.array(z.string()).describe('Page routes (e.g. ["/login", "/register"])'),
+        criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality")
+      })).describe("Features to create with their page routes")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "add_api_endpoints",
+    "Register API endpoints for a feature from codebase knowledge. Read the developer's route handlers to extract methods, paths, request/response shapes. Populates the API intelligence dashboard.",
+    {
+      featureName: z.string().describe("Feature name to link these endpoints to"),
+      endpoints: z.array(z.object({
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+        path: z.string().describe('API path (e.g. "/api/auth/login")'),
+        requestShape: z.record(z.string()).optional().describe('Request body fields with types (e.g. { "email": "string" })'),
+        responseShapes: z.record(z.record(z.string())).optional().describe('Response shapes by status code (e.g. { "200": { "token": "string" } })'),
+        requiresAuth: z.boolean().optional().describe("Whether endpoint requires authentication")
+      })).describe("API endpoints to register")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "get_test_failures",
+    "Get recent test failures with full error messages, Playwright code, step-level failures, and heal context. Use this to understand why tests are failing.",
+    {
+      limit: z.number().optional().describe("Max failures to return (default: 50, max: 100)"),
+      suite: z.string().optional().describe("Filter by feature/suite name"),
+      mode: z.enum(["run", "heal", "all"]).optional().describe("run = regular failures, heal = heal attempt failures, all = both (default)"),
+      sinceHours: z.number().optional().describe("Only failures from the last N hours (default: 24)")
+    },
+    { readOnlyHint: true }
+  );
+}
+
+// src/index.ts
+if (process.argv[2] === "init") {
+  const { runInit: runInit2 } = await Promise.resolve().then(() => (init_init(), init_exports));
+  runInit2();
+  process.exit(0);
+}
+var config = resolveConfig();
+var client = new ValidateQAClient(config.apiUrl, config.token, config.projectId);
+var server = new McpServer(
+  { name: "validate.qa", version: "1.0.0" },
+  { instructions: `Validate.QA \u2014 AI-powered QA platform: generates, runs, and heals Playwright E2E tests.
+
+## Capabilities
+- Setup projects via setup_project (read source code first)
+- Write tests via create_test (read routes, components, API handlers first)
+- Manage tests: list, view, edit, run, delete (DRAFT/ACTIVE/DISABLED/QUARANTINED)
+- Heal failing tests: AI replays in browser, fixes code or flags app bugs
+- Schedule recurring runs (hourly-weekly) with auto-heal
+
+## Workflows
+1. New project: READ source, setup_project (features, baseUrl, testCredentials, appBrief). Per feature: READ code, create_test, add_api_endpoints.
+2. Check health: list_features (failingTests > 0), get_test_failures per feature, edit_test_code or heal_test.
+3. Add coverage: READ code, create_feature, create_test x N (suite = feature name), add_api_endpoints.
+4. Nightly automation: create_schedule (daily, autoHeal: true).
+5. After code change: batch_run_tests, then list_features + get_test_failures.
+
+## Automatic lifecycle
+Do NOT call run_test after create_test (auto-queued) or heal_test after failures (auto-heals).
+Do NOT check run status in a loop \u2014 call get_test_failures after a reasonable wait to see what failed.
+Lifecycle: create > auto-run > pass=ACTIVE, fail=auto-heal > heal fail=@needs-review.
+DO call add_api_endpoints per feature (not automatic).
+DO call run_security_audit after UI tests to analyze captured API traffic. If it errors about missing data, tell the developer to click "Security Audit" in the Dashboard to run a live browser capture first. Use list_security_findings to review results.
+
+## Rate limits
+50 calls/60s. Reads parallel OK, writes sequential. On 429, wait 30-60s.
+
+## Triaging failures
+- App broken: flag_as_bug(testId, description). Selector/timing: heal_test. Bad test logic: edit_test_code.
+- Unsure: heal_test first \u2014 it detects app bugs automatically.
+
+## Using the codebase
+You have full source code access. Always READ before writing: routes for URLs, components for selectors, API handlers for endpoints.
+
+## Before writing any test \u2014 preflight check
+
+Read project://test-conventions first. Check the variables section:
+- BASE_URL must be set (the runner needs it). If missing, call setup_project or set_variable.
+- TEST_USER_EMAIL and TEST_USER_PASSWORD must be set if tests require login. If missing, ask the developer for credentials and call set_variable.
+- If starting fresh (no features, no variables), use workflow #1 (setup_project) before anything else.
+
+## Critical rules \u2014 see project://test-conventions for full details and code templates
+- URLs: relative only, never hardcoded domains \u2014 runner sets baseURL
+- Credentials: process.env.TEST_USER_EMAIL! (non-null assertion) \u2014 never ?? or || fallbacks
+- Registration: testuser-\${Date.now()}@example.com
+- Suite name must match feature name exactly (case-sensitive)
+- @auth must NOT combine with @smoke/@regression/@needs-auth/@critical
+- Each test = own browser process; @needs-auth tests MUST login inline
+- API tests: test.describe.serial() with __QA_HTTP__ log after every request
+- UI tests: console.log() milestones after key actions
+- create_test/edit_test_code validate code \u2014 fix warnings before moving on
+
+## Setting up coverage
+1. SCAN: Read router, nav, pages, API handlers \u2014 map ALL routes and features.
+2. SETUP: setup_project with features, pages, baseUrl, testCredentials, appBrief.
+3. WRITE: One feature at a time. For EACH test, read the SPECIFIC source code first (see codeReadingRequirements in test-conventions). For login blocks: read the login component. For UI tests: read the page component. For API tests: read the route handler. Templates are structure guides \u2014 selectors MUST come from the real code. Use create_test for BOTH UI and API tests. Then call add_api_endpoints.
+4. VERIFY: get_coverage_summary + list_features for failures + get_test_failures.
+
+Test real user flows (forms, validation, errors). "Page loads" tests are worthless.` }
+);
+registerAllTools(server, client);
+server.resource(
+  "Project Overview",
+  "project://overview",
+  { description: "Live project state: test counts, pass rates, runner status, features, coverage gaps, and configuration. Read this first to understand the current project." },
+  async () => {
+    try {
+      const [overview, coverage, stats] = await Promise.all([
+        client.executeTool("get_project_overview"),
+        client.executeTool("get_coverage_summary").catch(() => null),
+        client.executeTool("get_regression_stats").catch(() => null)
+      ]);
+      const snapshot = {
+        overview,
+        coverage,
+        regressionStats: stats,
+        retrievedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return { contents: [{ uri: "project://overview", mimeType: "application/json", text: JSON.stringify(snapshot, null, 2) }] };
+    } catch (err) {
+      return { contents: [{ uri: "project://overview", mimeType: "text/plain", text: `Failed to load project overview: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+  }
+);
+server.resource(
+  "Test Conventions",
+  "project://test-conventions",
+  { description: "Project-specific test conventions: environment variables, credential patterns, tag meanings, and registration email rules. Read this before writing or editing any test." },
+  async () => {
+    try {
+      const vars = await client.executeTool("get_variables");
+      const varNames = Object.keys(vars.variables || {});
+      const hasAuth = varNames.includes("TEST_USER_EMAIL") && varNames.includes("TEST_USER_PASSWORD");
+      const conventions = {
+        codeReadingRequirements: {
+          CRITICAL: "Templates below are STRUCTURE GUIDES \u2014 every selector, route, and endpoint MUST come from reading the actual source code. Never copy a template verbatim.",
+          forLogin: "BEFORE writing any @needs-auth login block: READ the login/auth page component. Find: (1) the login route (/login, /auth/login, /signin?), (2) the flow type (single-step or multi-step with Continue/Next button?), (3) exact input selectors (labels, placeholders, input types \u2014 is it getByLabel, getByPlaceholder, or input[type=password]?), (4) exact submit button text, (5) post-login redirect URL. Every app is different \u2014 single-step, multi-step, OAuth buttons, magic links.",
+          forUITests: "BEFORE writing a UI test for a page: READ the page component. Find: headings (text + level), form fields (labels, placeholders, types), buttons (text, role), navigation elements, validation error messages, success/error states. Use the exact text from the component \u2014 do not guess.",
+          forAPITests: "BEFORE writing an API test: READ the route handler. Find: the endpoint path, HTTP method, request body schema (what fields, what types), response body shape (is it flat or wrapped in { data: {...} }?), auth requirements (Bearer token? Cookie? API key?), error response shapes.",
+          forAPIMapping: "BEFORE calling add_api_endpoints: READ ALL route handlers for the feature. Register every endpoint with accurate method, path, requestShape, responseShapes, requiresAuth."
+        },
+        credentials: {
+          rule: "Never hardcode credentials in test code",
+          loginFields: hasAuth ? "Use process.env.TEST_USER_EMAIL! and process.env.TEST_USER_PASSWORD!" : "No credentials configured \u2014 set TEST_USER_EMAIL and TEST_USER_PASSWORD via set_variable",
+          registrationFields: 'MUST use unique email per run: `testuser-${Date.now()}@example.com` \u2014 reusing emails causes "already registered" failures',
+          registrationPassword: "Use 'TestPass123!' for new account passwords (meets typical strength rules)"
+        },
+        variables: {
+          configured: varNames,
+          baseUrl: vars.variables?.BASE_URL?.value || "Not set"
+        },
+        tags: {
+          "@auth": "Tests the login/auth flow itself. MUST NOT combine with @smoke, @regression, @needs-auth, @critical. CAN include @discovered.",
+          "@needs-auth": "Tests for authenticated pages \u2014 MUST include inline login block. CAN combine with @smoke, @regression, @critical.",
+          "@smoke": "Quick sanity checks \u2014 run on every deploy",
+          "@regression": "Full regression suite tests",
+          "@critical": "Business-critical paths (informational label \u2014 no special suite filtering)",
+          "@api": "API-level tests. Runs in its own project, excluded from suite/smoke/regression runs",
+          "@discovered": "Auto-added to tests generated by AI discovery",
+          "@generated": "Auto-added by AI discovery and API test generation",
+          "@manual": "Default tag for tests created via create_test when no tags specified",
+          "@flaky": "Auto-added after repeated failures. Excluded from suite/smoke/regression runs",
+          "@bug-found": "Added when healer detects an app bug. Test is auto-quarantined",
+          "@needs-review": "Added when DRAFT test fails healing. Requires human attention",
+          "@heal-skip": "Added by healer when test is permanently unfixable. Prevents future auto-heal"
+        },
+        executionModel: {
+          isolation: "Each test runs as its own separate Playwright process in a fresh browser. No shared state, no storageState, no global setup.",
+          authRequired: "Every @needs-auth test MUST include its own login block. Do NOT suggest storageState or performLogin() \u2014 those only work in the regression suite.",
+          concurrency: "Tests run in parallel \u2014 runner claims up to 10 per poll, launched 3s apart (~30s per batch). Multiple batches can overlap. Use test.setTimeout(120_000) if the target app is slow under concurrent login load."
+        },
+        lifecycle: {
+          DRAFT: "New or unverified test \u2014 not included in scheduled runs",
+          ACTIVE: "Verified and running \u2014 included in batch/suite executions",
+          DISABLED: "Manually paused \u2014 excluded from all runs",
+          QUARANTINED: "Auto-quarantined after repeated failures"
+        },
+        logging: {
+          CRITICAL: "EVERY request.get/post/put/patch/delete call MUST be followed by a __QA_HTTP__ log line. This is how the platform surfaces request/response data in the Network panel. Missing this = invisible API calls.",
+          apiPattern: "const body = await res.json();\nconsole.log('__QA_HTTP__:' + JSON.stringify({ method: 'POST', url: '/api/path', status: res.status(), requestBody: { field: value, password: '[REDACTED]' }, responseBody: body }));",
+          rules: [
+            "Call res.json() ONCE, store in body variable \u2014 reuse for log and assertions (calling twice throws)",
+            "Log AFTER the request, BEFORE assertions",
+            'Redact sensitive fields: password: "[REDACTED]", token: "[REDACTED]"',
+            "Use the literal URL string (same as the request call), not a variable",
+            "UI tests using page fixture do NOT need __QA_HTTP__ \u2014 only request fixture tests"
+          ],
+          uiMilestones: "UI tests (page fixture): add plain console.log() at key milestones \u2014 e.g. console.log('Navigated to login page') after page.goto(). These appear in the Console Output panel.",
+          uiLoggingRules: [
+            "Log AFTER the action, not before \u2014 confirms the action succeeded",
+            'Include dynamic values where useful: console.log("Current URL:", page.url())',
+            "Keep messages short and human-readable \u2014 they show verbatim in the UI",
+            "Do NOT log sensitive values (passwords, tokens)"
+          ],
+          apiTestStructure: "Use test.describe.serial() for API tests sharing auth. Independent validation tests (401, 404 checks) go in a SEPARATE non-serial describe block \u2014 do not mix them with the auth-dependent serial flow."
+        },
+        bestPractices: [
+          "Every @needs-auth test must start with a login block (goto login, fill creds, click submit, waitForURL)",
+          "Use { timeout: 30000 } on waitForURL after login \u2014 target apps can be slow under concurrent test load",
+          "Keep login blocks minimal \u2014 no assertions on the login page (that is what @auth tests are for)",
+          "After login, page.goto() directly to the page being tested \u2014 do not navigate via UI clicks",
+          "Use role-based selectors (getByRole, getByLabel) over CSS selectors",
+          "Registration tests must generate unique email with Date.now()",
+          "Group tests into suites matching feature names exactly (case-sensitive)",
+          "Do NOT suggest storageState or performLogin() for create_test \u2014 those only work in the regression suite",
+          "EVERY API test (request fixture) MUST include __QA_HTTP__ log after each request call \u2014 see logging section above",
+          'Avoid waitForLoadState("networkidle") \u2014 apps with SSE, WebSocket, or analytics connections may never reach idle, causing 60s timeouts. Wait for specific elements instead.',
+          'For headings, use exact: true or level: 1 \u2014 getByRole("heading", { name: "X" }) matches ALL h1-h6 containing "X", causing strict mode violations'
+        ],
+        pitfalls: {
+          CRITICAL: "These are the top causes of test failures. Read before writing ANY test.",
+          strictModeViolations: `Playwright throws when a locator resolves to 2+ elements. Common causes: getByLabel('Password') matches input AND 'Show password' toggle; getByRole('button', { name: 'Continue' }) matches 'Continue' AND 'Continue with GitHub'. Prevention: use input[type="password"] for password fields, use { exact: true } for ambiguous button text, scope to a parent container (page.locator('form#login').getByLabel('Email')).`,
+          networkIdle: "NEVER use waitForLoadState('networkidle') \u2014 waits for 500ms of zero network activity, which is fragile and causes 30s+ timeouts in apps with polling, analytics, or WebSockets. Use waitForURL() or wait for a specific element instead.",
+          headingStrictMode: "getByRole('heading', { name: 'Dashboard' }) can match multiple headings (h1 + h2 + breadcrumb). Add { level: 1 } or { exact: true } to disambiguate. Same for getByLabel('Password') matching input AND 'Show password' toggle.",
+          postLoginRedirect: "NEVER assert exact URL after login (e.g. expect(page).toHaveURL('/dashboard')) \u2014 apps redirect to different routes per user/role. Use: await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 30000 })",
+          resJsonOnce: "res.json() consumes the response body stream \u2014 calling it twice throws. Store result: const body = await res.json(); then reuse body for logging and assertions.",
+          hiddenInputs: "Many UI frameworks use visually hidden <input> with custom overlays. page.check() fails because the overlay intercepts clicks. Click the <label> or visible wrapper: page.getByText('Remember me').click()",
+          apiResponseShapes: "API endpoints often wrap data in a property ({ user: {...} }, { data: [...] }). Read the route handler's res.json() call to see the actual shape. If the handler does res.json({ ticket }), then body is { ticket: { id, ... } } \u2014 NOT { id, ... }.",
+          invalidIds: "Not all routes validate ID format before querying the database. If a route passes the raw ID to an ORM query and gets null back, it returns 404 'not found' \u2014 not 400 'bad request'. If unsure, expect either: expect([400, 404]).toContain(res.status())",
+          hardcodedUrls: "NEVER hardcode full URLs in test code. For UI tests: always use relative paths \u2014 page.goto('/login'). The runner sets baseURL from the project's BASE_URL variable. For API tests: use relative paths if the API is on the same domain as the frontend (request.post('/api/auth/login')). If the API is on a SEPARATE domain, use process.env.BASE_API_URL! as a test variable (set via set_variable) and construct URLs: request.post(process.env.BASE_API_URL! + '/auth/login'). NEVER hardcode 'https://example.com/...' in test code \u2014 use env vars or relative paths.",
+          credentialFallbacks: "NEVER use process.env.TEST_USER_EMAIL ?? 'fallback' or || 'fallback'. Use ! (non-null assertion). Missing variable = test should fail immediately, not silently use hardcoded value."
+        },
+        templates: {
+          needsAuth: `test('Feature Name \u2014 Test Name', {
+  tag: ['@needs-auth', '@smoke'],
+}, async ({ page }) => {
+  // Login block \u2014 ADAPTED from reading the app's login page component
+  // YOU MUST READ the login page component BEFORE writing this block
+  await page.goto('/login'); // read the router for actual login route
+  await page.getByRole('textbox', { name: /email/i }).fill(process.env.TEST_USER_EMAIL!);
+  await page.locator('input[type="password"]').waitFor({ state: 'visible', timeout: 10000 });
+  await page.locator('input[type="password"]').fill(process.env.TEST_USER_PASSWORD!);
+  await page.getByRole('button', { name: /sign in|log in|submit/i }).click();
+  await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 30000 });
+  console.log('Logged in, current URL:', page.url());
+
+  // Actual test
+  await page.goto('/feature-path');
+  console.log('On feature page');
+  await expect(page.getByRole('heading', { name: /feature name/i })).toBeVisible();
+});`,
+          authTest: "test('Login \u2014 Happy Path', {\n  tag: ['@auth'],\n}, async ({ page }) => {\n  await page.goto('/auth/login');\n  // test the login form itself \u2014 selectors from reading the actual component\n});",
+          apiSerial: "test.describe.serial('Feature Name', () => {\n  let token: string;\n  test('authenticate', async ({ request }) => {\n    const res = await request.post('/api/auth/login', {\n      data: { email: process.env.TEST_USER_EMAIL!, password: process.env.TEST_USER_PASSWORD! }\n    });\n    const body = await res.json();\n    console.log('__QA_HTTP__:' + JSON.stringify({\n      method: 'POST', url: '/api/auth/login', status: res.status(),\n      requestBody: { email: process.env.TEST_USER_EMAIL!, password: '[REDACTED]' },\n      responseBody: body,\n    }));\n    expect(res.status()).toBe(200);\n    token = body.access_token; // \u2190 adapt to your API (e.g. body.token, body.jwt)\n  });\n  test('get profile', async ({ request }) => {\n    const res = await request.get('/api/users/profile', {\n      headers: { Authorization: `Bearer ${token}` }\n    });\n    const body = await res.json();\n    console.log('__QA_HTTP__:' + JSON.stringify({\n      method: 'GET', url: '/api/users/profile', status: res.status(),\n      responseBody: body,\n    }));\n    expect(res.status()).toBe(200);\n  });\n});",
+          apiEndpointMapping: `// After reading an Express route handler like:
+// router.post('/api/auth/login', async (req, res) => { ... })
+// Call add_api_endpoints with:
+{
+  featureName: "Authentication",
+  endpoints: [{
+    method: "POST",
+    path: "/api/auth/login",
+    requiresAuth: false,
+    requestShape: { "email": "string", "password": "string" },
+    responseShapes: { "200": { "token": "string", "user": "object" }, "401": { "error": "string" } }
+  }]
+}`,
+          uiWithMilestones: `test('Feature \u2014 Happy Path', async ({ page }) => {
+  await page.goto('/login');
+  console.log('Navigated to login page');
+
+  await page.getByRole('textbox', { name: /email/i }).fill(process.env.TEST_USER_EMAIL!);
+  await page.locator('input[type="password"]').fill(process.env.TEST_USER_PASSWORD!);
+  await page.getByRole('button', { name: /sign in/i }).click();
+  console.log('Credentials submitted');
+
+  await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 15000 });
+  console.log('Logged in, current URL:', page.url());
+
+  await page.goto('/feature-path');
+  console.log('On feature page');
+});`
+        },
+        testQuality: [
+          'Test actual user flows, not just "page loads" \u2014 a test that only checks goto + heading visible is nearly worthless',
+          "Test form submission: fill fields, submit, verify success/redirect",
+          "Test validation: leave required fields empty, enter invalid data, verify error messages",
+          "Test error states: wrong password, expired session, invalid IDs",
+          "Test the happy path end-to-end: login \u2192 navigate \u2192 perform action \u2192 verify result",
+          "Each test should assert something meaningful about the application behavior"
+        ],
+        securityAudit: {
+          workflow: "After creating UI tests for a feature, call run_security_audit to analyze captured API traffic for auth issues, data exposure, and vulnerabilities.",
+          prerequisite: 'Requires prior browser-based test execution (the auto-verification run from create_test counts). If run_security_audit errors about missing data, tell the developer to click "Security Audit" in the Tests dropdown on the Dashboard \u2014 this launches a live browser to capture real network traffic (HAR) and runs analysis automatically.',
+          reviewing: "Use list_security_findings to review results. Filter by severity (critical/high/medium/low/info) or status (open/acknowledged/resolved/false-positive). Critical and high findings should be flagged to the developer immediately."
+        },
+        keyConcepts: {
+          features: 'Group related pages and tests (e.g., "Authentication" covers /auth/login, /auth/register). MUST include page routes.',
+          pages: 'Route URLs on a feature \u2014 used for coverage tracking and site map (e.g., ["/login", "/register"])',
+          suites: "Group tests for batch execution \u2014 suite name MUST match feature name exactly (case-sensitive)",
+          runner: "Executes tests \u2014 can be local (developer machine) or cloud",
+          testData: "Key-value variables injected into tests (e.g., credentials, URLs)"
+        },
+        retrievedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return { contents: [{ uri: "project://test-conventions", mimeType: "application/json", text: JSON.stringify(conventions, null, 2) }] };
+    } catch (err) {
+      return { contents: [{ uri: "project://test-conventions", mimeType: "text/plain", text: `Failed to load conventions: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map