playwright-e2e-mcp 0.3.0 → 0.3.2

package/README.md

@@ -3,6 +3,10 @@
 [![CI](https://github.com/xsignon-secure/E2E/actions/workflows/ci.yml/badge.svg)](https://github.com/xsignon-secure/E2E/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/xsignon-secure/E2E)](https://github.com/xsignon-secure/E2E/releases) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.xsignon--secure%2FE2E-2563eb)](https://registry.modelcontextprotocol.io/)
 [![M8ven Score](https://m8ven.ai/badge/mcp/trajectiq-ai/e2e)](https://m8ven.ai/mcp/trajectiq-ai/e2e?s=readme)
 
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=playwright-e2e&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBsYXl3cmlnaHQtZTJlLW1jcCJdfQ==)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright-e2e%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522playwright-e2e-mcp%2522%255D%257D)
+[![Add to Claude Desktop](https://img.shields.io/badge/Claude_Desktop-.mcpb_bundle-D97757)](https://github.com/xsignon-secure/E2E/releases/latest)
+
 An [MCP](https://modelcontextprotocol.io) server that **diagnoses and fixes failing Playwright
 tests**. It is the layer that sits next to a browser-driving MCP: Playwright MCP gives an agent
 hands in the browser; this server gives it a test runner, a failure analyst and a verified fixer.
@@ -62,16 +66,36 @@ against the bundled `examples/sample-test.spec.ts` (actual output, unedited):
 Images are rendered with `node scripts/gen-demo-images.mjs`: the run-test card is real
 captured output; the endpoint card is an illustration of the authenticated listing.
 
+> If this saves you a debugging session, a ⭐ on the repo helps other Playwright users find it.
+
 ## Install
 
 Works with Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Freebuff
 and every other MCP client — pick whichever route fits:
 
+**Let your agent do it.** Paste this into Claude Code, Cursor, Codex, Gemini CLI or any
+other coding agent:
+
+> Install the playwright-e2e-mcp server and skill by following
+> https://raw.githubusercontent.com/xsignon-secure/E2E/main/llms-install.md
+
+or run the installer yourself from the project root. It merges the server into each
+client's project config it finds (Claude Code, Cursor, VS Code, Gemini CLI, Codex) and
+installs the agent skill, leaving your other servers alone:
+
+```bash
+npx -y playwright-e2e-mcp init            # --client all | cursor,vscode … · --dry-run
+```
+
 | Route | How |
 | --- | --- |
+| **One command, any project** | `npx -y playwright-e2e-mcp init` |
+| **Claude Code plugin (server + skill)** | `/plugin marketplace add xsignon-secure/E2E` then `/plugin install playwright-e2e-mcp@xsignon-secure` |
+| **Gemini CLI extension (server + skill)** | `gemini extensions install https://github.com/xsignon-secure/E2E` |
+| **Skill only, any agent** | `npx skills add xsignon-secure/E2E` |
 | **npm (canonical, fastest)** | `npx -y playwright-e2e-mcp` |
 | **MCP Registry** (registry-aware clients discover it automatically) | `io.github.xsignon-secure/E2E` — [listing](https://registry.modelcontextprotocol.io/) |
-| **Any client, no npm account needed** | `npx -y github:xsignon-secure/E2E#v0.3.0` (pin a release tag) |
+| **Any client, no npm account needed** | `npx -y github:xsignon-secure/E2E#v0.3.2` (pin a release tag) |
 | **Claude Desktop, zero Node setup** | double-click the [`.mcpb` extension](https://github.com/xsignon-secure/E2E/releases) |
 | **Remote-only clients (ChatGPT connectors)** | `https://playwright-e2e-mcp.vercel.app/api/mcp` |
 
@@ -394,8 +418,8 @@ builds `dist/` automatically on install). Pin a release tag: an unpinned
 `github:xsignon-secure/E2E` runs whatever is on the default branch at that moment.
 
 ```bash
-npx -y github:xsignon-secure/E2E#v0.3.0
-npm install -D github:xsignon-secure/E2E#v0.3.0 @playwright/test   # or as a project dependency
+npx -y github:xsignon-secure/E2E#v0.3.2
+npm install -D github:xsignon-secure/E2E#v0.3.2 @playwright/test   # or as a project dependency
 npx playwright install chromium
 ```
 
@@ -403,7 +427,7 @@ Or grab the packaged tarball from the repo's **GitHub Releases** page and instal
 it locally:
 
 ```bash
-npm install -D https://github.com/xsignon-secure/E2E/releases/download/v0.3.0/playwright-e2e-mcp-0.3.0.tgz
+npm install -D https://github.com/xsignon-secure/E2E/releases/download/v0.3.2/playwright-e2e-mcp-0.3.2.tgz
 ```
 
 Listed in the **official [MCP Registry](https://registry.modelcontextprotocol.io/)** as
@@ -419,7 +443,7 @@ Listed in the **official [MCP Registry](https://registry.modelcontextprotocol.io
   "mcpServers": {
     "playwright-e2e": {
       "command": "npx",
-      "args": ["-y", "github:xsignon-secure/E2E#v0.3.0"],
+      "args": ["-y", "github:xsignon-secure/E2E#v0.3.2"],
       "env": { "PW_MCP_PROJECT_ROOT": "/absolute/path/to/your/project" }
     }
   }
@@ -433,8 +457,8 @@ when the client launches it somewhere else (e.g. your home directory).
 **Codex / VS Code / Copilot CLIs:**
 
 ```bash
-codex mcp add playwright-e2e -- npx -y github:xsignon-secure/E2E#v0.3.0
-code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","github:xsignon-secure/E2E#v0.3.0"]}'
+codex mcp add playwright-e2e -- npx -y github:xsignon-secure/E2E#v0.3.2
+code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","github:xsignon-secure/E2E#v0.3.2"]}'
 ```
 
 Codex's defaults fight this server: the first launch clones the repo and runs
@@ -445,7 +469,7 @@ Codex's defaults fight this server: the first launch clones the repo and runs
 ```toml
 [mcp_servers.playwright-e2e]
 command = "npx"
-args = ["-y", "github:xsignon-secure/E2E#v0.3.0"]
+args = ["-y", "github:xsignon-secure/E2E#v0.3.2"]
 startup_timeout_sec = 60
 tool_timeout_sec = 600
 ```
@@ -460,7 +484,7 @@ into `PW_MCP_PROJECT_ROOT`, so the tools point at a real project from the first
 **Claude Code:**
 
 ```bash
-claude mcp add playwright-e2e -- npx -y github:xsignon-secure/E2E#v0.3.0
+claude mcp add playwright-e2e -- npx -y github:xsignon-secure/E2E#v0.3.2
 ```
 
 **Gemini CLI / Qwen Code:** paste the `mcpServers` block above into
@@ -595,7 +619,7 @@ steps:
   - uses: actions/setup-node@v6
     with: { node-version: 24 }
   - run: npm ci && npx playwright install --with-deps chromium
-  - uses: xsignon-secure/E2E@v0.3.0
+  - uses: xsignon-secure/E2E@v0.3.2
     with:
       flaky-runs: 3      # 0 skips the flaky verdict
       suggest: 2         # suggest-fix diffs for the first 2 failures
@@ -892,8 +916,8 @@ job requests for itself; if it is refused, the run names the setting to change.
 ### Verifying a published release
 
 ```bash
-git checkout v0.3.0 && npm ci && npm run mcpb
-npm run release:verify -- v0.3.0
+git checkout v0.3.2 && npm ci && npm run mcpb
+npm run release:verify -- v0.3.2
 ```
 
 The release notes promise that the tag rebuilds the published bundle byte for

package/dist/cli/init.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `playwright-e2e-mcp init`: one command an agent (or a person) runs to wire
+ * the server and the agent skill into a project, for whichever clients the
+ * project uses. Config files are merged, never replaced: other servers and
+ * settings stay as they are, an existing playwright-e2e entry is updated in
+ * place, and a file that is not valid JSON is left untouched and reported.
+ *
+ * Exit codes: 0 done (or nothing to do), 1 a file could not be updated,
+ * 2 bad arguments.
+ */
+export declare const SERVER_NAME = "playwright-e2e";
+export declare const SKILL_NAME = "playwright-e2e-mcp";
+export declare const CLIENTS: readonly ["claude", "cursor", "vscode", "gemini", "codex", "windsurf"];
+export type Client = (typeof CLIENTS)[number];
+export declare const INIT_USAGE: string;
+export interface InitOptions {
+    projectRoot: string;
+    clients?: Client[];
+    tools?: string;
+    skill: boolean;
+    dryRun: boolean;
+}
+export declare function parseInitArgs(argv: string[], cwd?: string): InitOptions;
+/** Clients whose project folder or config file already exists. */
+export declare function detectClients(root: string): Client[];
+export interface PlannedChange {
+    client: Client | 'skill';
+    file: string;
+    action: 'create' | 'update' | 'unchanged' | 'error';
+    content?: string;
+    error?: string;
+}
+export declare function planInit(options: InitOptions, home?: string): {
+    clients: Client[];
+    changes: PlannedChange[];
+};
+/** The skill folder shipped in the npm package (dist/cli → ../../skill). */
+export declare function bundledSkillDir(): string;
+export declare function applyInit(changes: PlannedChange[], skillSource?: string): void;
+export declare function runInit(argv: string[], out?: (line: string) => void): number;

package/dist/cli/init.js

@@ -0,0 +1,218 @@
+/**
+ * `playwright-e2e-mcp init`: one command an agent (or a person) runs to wire
+ * the server and the agent skill into a project, for whichever clients the
+ * project uses. Config files are merged, never replaced: other servers and
+ * settings stay as they are, an existing playwright-e2e entry is updated in
+ * place, and a file that is not valid JSON is left untouched and reported.
+ *
+ * Exit codes: 0 done (or nothing to do), 1 a file could not be updated,
+ * 2 bad arguments.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+export const SERVER_NAME = 'playwright-e2e';
+export const SKILL_NAME = 'playwright-e2e-mcp';
+export const CLIENTS = ['claude', 'cursor', 'vscode', 'gemini', 'codex', 'windsurf'];
+export const INIT_USAGE = [
+    'Usage: playwright-e2e-mcp init [options]',
+    '',
+    'Adds the playwright-e2e MCP server and the playwright-e2e-mcp agent skill to a',
+    'project. Existing config files are merged, never overwritten.',
+    '',
+    '  --client <list>        comma separated: claude, cursor, vscode, gemini, codex,',
+    '                         windsurf, or all (default: the clients the project already',
+    '                         uses, or claude,cursor,vscode when none is found)',
+    '  --project-root <dir>   project directory (default: cwd)',
+    '  --tools <list>         expose only these tools/profiles (e.g. core), see --help',
+    '  --no-skill             do not install the agent skill',
+    '  --dry-run              print what would change without writing',
+    '',
+    'Files (project scope): claude .mcp.json · cursor .cursor/mcp.json ·',
+    'vscode .vscode/mcp.json · gemini .gemini/settings.json · codex .codex/config.toml.',
+    'windsurf has no project file; it writes ~/.codeium/windsurf/mcp_config.json.',
+    'Skill: .agents/skills/ (read by Codex, Gemini, Cursor and others) and',
+    '.claude/skills/ when claude is selected.',
+    '',
+].join('\n');
+export function parseInitArgs(argv, cwd = process.cwd()) {
+    const { values } = parseArgs({
+        args: argv,
+        strict: true,
+        options: {
+            client: { type: 'string' },
+            'project-root': { type: 'string' },
+            tools: { type: 'string' },
+            'no-skill': { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+        },
+    });
+    let clients;
+    if (values.client !== undefined) {
+        const names = values.client.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+        if (names.includes('all'))
+            clients = [...CLIENTS];
+        else {
+            const unknown = names.filter((n) => !CLIENTS.includes(n));
+            if (unknown.length || !names.length) {
+                throw new Error(`--client must list ${CLIENTS.join(', ')} or all (got: ${unknown.join(', ') || 'nothing'})`);
+            }
+            clients = [...new Set(names)];
+        }
+    }
+    return {
+        projectRoot: path.resolve(cwd, values['project-root'] ?? '.'),
+        clients,
+        tools: values.tools,
+        skill: !values['no-skill'],
+        dryRun: Boolean(values['dry-run']),
+    };
+}
+/** Clients whose project folder or config file already exists. */
+export function detectClients(root) {
+    const has = (p) => existsSync(path.join(root, p));
+    const found = [];
+    if (has('.mcp.json') || has('.claude') || has('CLAUDE.md'))
+        found.push('claude');
+    if (has('.cursor'))
+        found.push('cursor');
+    if (has('.vscode'))
+        found.push('vscode');
+    if (has('.gemini') || has('GEMINI.md'))
+        found.push('gemini');
+    if (has('.codex'))
+        found.push('codex');
+    return found;
+}
+function serverArgs(tools) {
+    return tools ? ['-y', 'playwright-e2e-mcp', `--tools=${tools}`] : ['-y', 'playwright-e2e-mcp'];
+}
+/** Merges our entry into a JSON config under `key`, keeping everything else. */
+function planJson(file, key, entry, client) {
+    let data = {};
+    let existed = false;
+    if (existsSync(file)) {
+        existed = true;
+        const raw = readFileSync(file, 'utf8');
+        if (raw.trim()) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('not a JSON object');
+                data = parsed;
+            }
+            catch (err) {
+                return { client, file, action: 'error', error: `not valid JSON (${err.message}); left unchanged` };
+            }
+        }
+    }
+    const current = data[key];
+    const servers = current && typeof current === 'object' && !Array.isArray(current) ? { ...current } : {};
+    const before = JSON.stringify(servers[SERVER_NAME]);
+    servers[SERVER_NAME] = entry;
+    if (existed && before === JSON.stringify(entry))
+        return { client, file, action: 'unchanged' };
+    return { client, file, action: existed ? 'update' : 'create', content: `${JSON.stringify({ ...data, [key]: servers }, null, 2)}\n` };
+}
+/** Codex reads TOML; append our table unless one is already there. */
+function planCodex(file, args) {
+    const table = `[mcp_servers.${SERVER_NAME}]`;
+    const block = `${table}\ncommand = "npx"\nargs = [${args.map((a) => JSON.stringify(a)).join(', ')}]\n`;
+    if (!existsSync(file))
+        return { client: 'codex', file, action: 'create', content: block };
+    const raw = readFileSync(file, 'utf8');
+    if (raw.includes(table))
+        return { client: 'codex', file, action: 'unchanged' };
+    const sep = raw.length === 0 || raw.endsWith('\n\n') ? '' : raw.endsWith('\n') ? '\n' : '\n\n';
+    return { client: 'codex', file, action: 'update', content: `${raw}${sep}${block}` };
+}
+export function planInit(options, home = os.homedir()) {
+    const root = options.projectRoot;
+    let clients = options.clients ?? detectClients(root);
+    if (!clients.length)
+        clients = ['claude', 'cursor', 'vscode'];
+    const args = serverArgs(options.tools);
+    const stdio = { command: 'npx', args };
+    const changes = [];
+    for (const client of clients) {
+        switch (client) {
+            case 'claude':
+                changes.push(planJson(path.join(root, '.mcp.json'), 'mcpServers', { type: 'stdio', ...stdio }, client));
+                break;
+            case 'cursor':
+                changes.push(planJson(path.join(root, '.cursor', 'mcp.json'), 'mcpServers', stdio, client));
+                break;
+            case 'vscode':
+                changes.push(planJson(path.join(root, '.vscode', 'mcp.json'), 'servers', { type: 'stdio', ...stdio }, client));
+                break;
+            case 'gemini':
+                changes.push(planJson(path.join(root, '.gemini', 'settings.json'), 'mcpServers', stdio, client));
+                break;
+            case 'codex':
+                changes.push(planCodex(path.join(root, '.codex', 'config.toml'), args));
+                break;
+            case 'windsurf':
+                changes.push(planJson(path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', stdio, client));
+                break;
+        }
+    }
+    if (options.skill) {
+        const targets = [path.join(root, '.agents', 'skills', SKILL_NAME)];
+        if (clients.includes('claude'))
+            targets.push(path.join(root, '.claude', 'skills', SKILL_NAME));
+        for (const dir of targets) {
+            changes.push({ client: 'skill', file: dir, action: existsSync(path.join(dir, 'SKILL.md')) ? 'update' : 'create' });
+        }
+    }
+    return { clients, changes };
+}
+/** The skill folder shipped in the npm package (dist/cli → ../../skill). */
+export function bundledSkillDir() {
+    return fileURLToPath(new URL(`../../skill/${SKILL_NAME}/`, import.meta.url));
+}
+export function applyInit(changes, skillSource = bundledSkillDir()) {
+    for (const change of changes) {
+        if (change.action === 'error' || change.action === 'unchanged')
+            continue;
+        if (change.client === 'skill') {
+            mkdirSync(change.file, { recursive: true });
+            cpSync(skillSource, change.file, { recursive: true, force: true });
+            continue;
+        }
+        mkdirSync(path.dirname(change.file), { recursive: true });
+        writeFileSync(change.file, change.content ?? '');
+    }
+}
+export function runInit(argv, out = (l) => process.stdout.write(`${l}\n`)) {
+    let options;
+    try {
+        options = parseInitArgs(argv);
+    }
+    catch (err) {
+        out(`init: ${err.message}\n`);
+        out(INIT_USAGE);
+        return 2;
+    }
+    const { clients, changes } = planInit(options);
+    if (options.skill && !existsSync(path.join(bundledSkillDir(), 'SKILL.md'))) {
+        out('init: the skill files are missing from this install; skipping the skill.');
+        for (const c of changes)
+            if (c.client === 'skill')
+                c.action = 'unchanged';
+    }
+    if (!options.dryRun)
+        applyInit(changes);
+    const rel = (p) => (p.startsWith(options.projectRoot) ? path.relative(options.projectRoot, p) || '.' : p);
+    out(`${options.dryRun ? 'Would set up' : 'Set up'} playwright-e2e for: ${clients.join(', ')}`);
+    for (const c of changes) {
+        const what = c.client === 'skill' ? 'skill' : c.client;
+        out(`  ${c.action.padEnd(9)} ${rel(c.file)} (${what})${c.error ? `: ${c.error}` : ''}`);
+    }
+    out('');
+    out('Next: make sure browsers are installed (npx playwright install chromium), then');
+    out('restart or reload the agent so it picks up the new server.');
+    return changes.some((c) => c.action === 'error') ? 1 : 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

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

package/dist/index.js

@@ -31,6 +31,15 @@ async function main() {
         process.exitCode = await runCi(process.argv.slice(3));
         return;
     }
+    if (process.argv[2] === 'init') {
+        const { runInit, INIT_USAGE } = await import('./cli/init.js');
+        if (process.argv.includes('--help') || process.argv.includes('-h')) {
+            process.stdout.write(INIT_USAGE);
+            return;
+        }
+        process.exitCode = runInit(process.argv.slice(3));
+        return;
+    }
     if (process.argv.includes('--version') || process.argv.includes('-v')) {
         process.stdout.write(`${SERVER_VERSION}\n`);
         return;
@@ -41,6 +50,7 @@ async function main() {
             '',
             'Usage: playwright-e2e-mcp [--tools=<list>] [--version] [--help]',
             '       playwright-e2e-mcp ci [options]   run the suite and print a Markdown diagnosis (ci --help)',
+            '       playwright-e2e-mcp init [options] add the server + agent skill to a project (init --help)',
             '',
             'Connects over stdio (MCP). Configuration via environment:',
             '  PW_MCP_PROJECT_ROOT        default project root (default: cwd)',

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,SAAS,YAAY;IACnB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACtD,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;QAC/B,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;QAC9D,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;YACE,4EAA4E;YAC5E,EAAE;YACF,iEAAiE;YACjE,mGAAmG;YACnG,kGAAkG;YAClG,EAAE;YACF,2DAA2D;YAC3D,kEAAkE;YAClE,sFAAsF;YACtF,wFAAwF;YACxF,0EAA0E;YAC1E,uFAAuF;YACvF,mFAAmF;YACnF,4DAA4D;YAC5D,EAAE;YACF,6CAA6C;YAC7C,8EAA8E;YAC9E,wEAAwE;YACxE,kEAAkE;YAClE,2DAA2D;YAC3D,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACzE,IAAI,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAE7E,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACpD,MAAM,WAAW,EAAE,CAAC;AACtB,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,CAAC,CAAC;QACvE,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,oBAAoB,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1H,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-e2e-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server that runs, diagnoses and fixes failing Playwright end-to-end tests: trace analysis, verified locator fixes, flaky ranking",
   "author": "xsignon-secure (https://github.com/xsignon-secure)",
   "mcpName": "io.github.xsignon-secure/E2E",
@@ -26,7 +26,10 @@
     "selectors",
     "flaky-tests",
     "github-action",
-    "ci"
+    "ci",
+    "agent-skills",
+    "claude-code-plugin",
+    "gemini-cli-extension"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -42,6 +45,7 @@
   "files": [
     "dist",
     "examples",
+    "skill/playwright-e2e-mcp",
     "README.md",
     "LICENSE"
   ],

package/skill/README.md

@@ -0,0 +1,34 @@
+# Agent skill: playwright-e2e-mcp
+
+`playwright-e2e-mcp/` is an [Agent Skill](https://agentskills.io/specification)
+that teaches an agent when and how to use this repo's MCP server: the run, read
+the failure, inspect, validate, fix and re-run loop, self-healing fixes with
+`suggest-fix`, signed-in page inspection, background runs, run-history triage,
+flaky-test diagnosis, test generation and visual comparison. It targets
+playwright-e2e-mcp 0.3.0 (and works with 0.2.0 or newer). It works with any agent that reads
+`SKILL.md` skills (Claude Code, Codex CLI, OpenClaw and others) once the MCP
+server is connected.
+
+```
+playwright-e2e-mcp/
+├── SKILL.md                     # when to use the skill and the step-by-step workflow
+└── references/
+    ├── setup.md                 # server install per client, env vars, skill install
+    ├── tools.md                 # every tool's arguments
+    ├── failure-kinds.md         # failure kinds, error codes and what to do
+    └── example-session.md       # a worked fix-a-failing-test session
+```
+
+The skill contains only Markdown: no scripts, binaries or symlinks, and no
+credentials.
+
+## Packaging for a marketplace (Agensi)
+
+Agensi expects one top-level folder named after the skill, with `SKILL.md` at
+its root, text files only and no OS junk files. From this `skill/` directory:
+
+```bash
+zip -r playwright-e2e-mcp.zip playwright-e2e-mcp -x "*.DS_Store" "*Thumbs.db"
+```
+
+Keep the skill's `name` in `SKILL.md` equal to the folder name.

package/skill/playwright-e2e-mcp/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: playwright-e2e-mcp
+description: Runs, debugs and fixes Playwright end-to-end tests through the playwright-e2e-mcp server, using structured run results, trace-based failure diagnostics, verified locators, self-healing fixes that re-run and revert if still red, per-test flaky verdicts that separate parallelism bugs from races, signed-in page inspection and local run history. Use when the user asks to run Playwright tests, fix a failing or broken e2e test, find out why a test is flaky or which tests are unstable, repair a selector that no longer matches, write a new Playwright test, or check a page for visual regressions.
+---
+
+# Playwright E2E with playwright-e2e-mcp
+
+This skill drives the `playwright-e2e-mcp` MCP server. The server runs Playwright
+for you and returns structured results instead of raw terminal output: pass/fail
+stats, each failure with `file:line`, a failure kind, the DOM at the moment of
+failure (read from the Playwright trace), failed network requests, console errors
+and concrete next steps. It can also propose and apply a verified fix for a broken
+locator, inspect pages behind a login, run long suites in the background and keep
+a local history of every run.
+
+This skill is written for playwright-e2e-mcp 0.3.0 and works with 0.2.0 or
+newer. If `suggest-fix`, `get-run-status` or `analyze-history` is missing, the
+server is older than 0.2.0: use the steps that do not need those tools and tell
+the user to update it. `diagnose-flaky`'s per-test table and `isolate` option
+arrived in 0.3.0.
+
+## Before you start
+
+1. Check that the server's tools are available. They are named `run-test`,
+   `get-run-status`, `get-failure`, `suggest-fix`, `inspect-page`,
+   `validate-selector`, `list-tests`, `generate-e2e-test`,
+   `compare-visual-state`, `diagnose-flaky` and `analyze-history` (your client
+   may prefix them, e.g. `mcp__playwright-e2e__run-test`).
+2. If they are all missing, stop and tell the user the MCP server is not
+   connected. Point them to `references/setup.md` for the one-line install for
+   their client. Do not fall back to shelling out to `npx playwright test` unless
+   the user asks. If only some are missing, the server may run a smaller tool
+   profile (`--tools=core` exposes `run-test`, `get-run-status`, `get-failure`,
+   `suggest-fix`, `diagnose-flaky` and `list-tests`); work with what is there and
+   mention the profile when a task needs a page tool.
+3. Every tool except `get-run-status` takes an optional `projectRoot`. Leave it
+   out unless the user works in a sub-project; the server defaults to `PW_MCP_PROJECT_ROOT` or its working
+   directory, and rejects any root outside its allowed roots.
+4. If the client offers the server's prompts as slash commands,
+   `/fix-failing-test` and `/triage-flaky-tests` start the two main workflows
+   below.
+
+## The core loop: fix a failing test
+
+Follow these steps in order. Do not edit code before step 3.
+
+1. **Run.** Call `run-test` with the narrowest scope you know:
+   `{ "testFiles": ["tests/checkout.spec.ts"] }`, or `file:line`, or `grep`.
+   Omit `testFiles` only when the user asks for the whole suite. Failing tests are
+   retried once by default, so a test that passes on retry is reported as
+   **flaky**, not failed. For a long suite pass `background: true` and poll
+   `get-run-status` with `waitSeconds: 30`.
+2. **Read the failure.** For each failure, call `get-failure` with its 1-based
+   `index`. Read the message and code frame, expected vs actual, the failure kind,
+   the DOM snapshot at failure, the failed action and its selector, failed network
+   requests and console errors.
+3. **Decide what is wrong** using the failure kind (see
+   `references/failure-kinds.md`):
+   - `server-unreachable` / `SERVER_NOT_RUNNING`: the app is not running. Tell the
+     user to start the dev server, or suggest `webServer` in the Playwright config.
+     Do not edit tests.
+   - A locator or selector in the message, or "0 elements": call `suggest-fix`
+     with the same `index`. If it returns a diff with `high` confidence, call it
+     again with `apply: true`; it re-runs the test and reverts if still red. If it
+     says the element is missing, treat it as an app bug and report the evidence.
+     Otherwise go to the selector loop below.
+   - `assertion` with a sensible selector: compare expected vs actual and the DOM
+     snapshot. Decide whether the app regressed or the test expectation is stale,
+     and say which before changing anything.
+   - `timeout`: check the DOM snapshot and failed requests for a slow or failed
+     API call before raising any timeout.
+   - Failed network request (4xx/5xx/no response) right before the failure: the
+     backend is the likely cause; report it.
+4. **Fix** the spec or the app code, the smallest change that addresses the cause.
+5. **Re-run only what failed:** `run-test` with `{ "lastFailed": true }`. Repeat
+   from step 2 until green.
+
+## Selector loop: a locator no longer matches
+
+1. `inspect-page` with the page URL and `view: "locators"`
+   (e.g. `{ "url": "http://localhost:3000/checkout", "view": "locators" }`).
+   Behind a login, pass `storageState` (the project's saved auth file); to reach a
+   modal or later step, pass `actions`. Every locator listed was checked to match
+   exactly one element.
+2. Pick a replacement. Prefer, in order: role + accessible name (`getByRole`),
+   `getByTestId`, label/placeholder, then a short stable CSS selector. Avoid
+   positional selectors such as `:nth-child` and generated class names.
+3. `validate-selector` with `{ "url": ..., "selector": ... }` before editing the
+   spec. It accepts locator expressions as written in the spec. Only use one that
+   comes back `✅ VALID` with exactly 1 match.
+4. Update the spec and re-run with `lastFailed: true`.
+
+## Pages behind a login
+
+`inspect-page`, `validate-selector` and `compare-visual-state` open the page in a
+fresh browser, so a signed-in page shows the login screen unless you pass state:
+
+- `storageState`: path inside the project to a Playwright storageState JSON, such
+  as `playwright/.auth/user.json` written by the project's setup project. Look for
+  it in `playwright.config.*` before asking the user. The server can default to
+  `PW_MCP_STORAGE_STATE`.
+- `headers`: extra HTTP headers, e.g. an API token the user gave you. Never invent
+  or log credentials.
+- `actions`: up to 20 steps after load (`click`, `fill`, `press`, `check`,
+  `select`, `hover`, `wait`, `goto`, ...) to open a modal or reach a later step.
+- `viewport`: `{ "width": 390, "height": 844 }` for mobile layouts.
+
+When a response says the page landed on a login screen, retry with
+`storageState`. `suggest-fix` takes `storageState` and `headers` too when you heal
+against a live `url`.
+
+## Flaky or intermittent failures
+
+Start with `analyze-history` (default view `flaky`) to see which tests flip
+between pass and fail across recorded runs, which regressed, and which are simply
+broken; `view: "patterns"` groups failures that share a cause. Then call
+`diagnose-flaky` on the worst ones (optionally `{ "testFiles": [...], "runs": 5 }`;
+with no `testFiles` it takes the tests that failed in the last run). It repeats
+them with retries disabled, in one Playwright process, and returns a table with
+one verdict **per test** (passes, failures, duration spread, first error):
+
+- **CONSISTENTLY FAILING**: not flaky; treat it as a real failure (core loop).
+- **FLAKY**: some runs passed. Same error signature each time points to a real
+  race in the app or test; varying errors point to timing or environment. Look for
+  missing awaits, assertions without auto-waiting, shared state between tests and
+  fixed `waitForTimeout` sleeps. Never "fix" flakiness by only adding retries or
+  sleeps.
+- **NOT REPRODUCING**: passed every run. Report that the failure was one-off.
+
+When a test is FLAKY and the suite runs in parallel, call `diagnose-flaky` again
+with `isolate: true`. It repeats the tests fully parallel, then repeats the
+failing ones with one worker, and reads each one:
+
+- **fails only in parallel**: the test shares state with others (same user or
+  account, DB rows, files, ports, a global fixture). Fix the data isolation, for
+  example per-worker data from `testInfo.workerIndex`; do not just serialize the
+  whole suite.
+- **flaky even alone**: the race is inside the test or the app.
+- **fails alone too**: a real bug, not parallelism.
+
+Pass `separateProcesses: true` only when the flake seems tied to global setup or
+a cold start, since one process per run is slower. `get-failure` works on the
+last failing diagnose run straight after, and each repetition is recorded in the
+history, so `diagnose-flaky` with `runs: 5` is also the quickest way to seed
+history for `analyze-history`.
+
+Every `run-test`, `diagnose-flaky` and `suggest-fix` run is recorded in
+`<project>/.playwright-e2e-mcp/history.jsonl` on the user's machine;
+`analyze-history` with `view: "test"` and a `test` filter shows one test's
+pass/fail timeline.
+
+## Other tasks
+
+- **List tests:** `list-tests`, with `filter` for a substring of `file › title`.
+- **Write a new test:** `generate-e2e-test` with a `description` (and `pageUrl` if
+  there is no `baseURL`). It scaffolds a spec from selectors the project actually
+  declares, from recent git changes, and reports each selector's source. Review the
+  file it writes, then `run-test` it. Pass `write: false` to preview without
+  writing.
+- **Set up CI:** when the user wants the same diagnosis on every pull request,
+  point them to the GitHub Action (`uses: xsignon-secure/E2E@v0.3.0`) or the
+  `npx -y playwright-e2e-mcp ci` command in `references/setup.md`. It writes the
+  run, flaky verdicts and fix diffs to the job summary and one PR comment.
+- **Visual regression:** `compare-visual-state` with `url` and a `name`. The first
+  call saves a baseline under `.pw-mcp/visual/`; later calls report changed
+  regions and color shifts and write a diff image. Use `action: "baseline"` only
+  when the user confirms the new look is intended.
+
+## Reporting back
+
+When you finish, tell the user, in this order:
+
+1. The result: which tests now pass, fail or are flaky (counts from the last
+   `run-test`).
+2. The cause of each failure you fixed, with the `file:line` you changed.
+3. Anything you did not fix and why (app bug, server down, needs a decision).
+
+## Things to avoid
+
+- Do not raise timeouts, add retries, add `waitForTimeout`, or delete or
+  `test.skip` a test to make a run green, unless the user explicitly asks.
+- Do not accept a new visual baseline without the user's confirmation.
+- Do not pass `allowExpectationUpdate: true` to `suggest-fix` unless the user
+  confirms the new text is intended; a changed expected value can be a real bug.
+- Do not point `inspect-page` or `validate-selector` at sites the user did not
+  name; they open real pages in a headless browser.
+- `run-test` executes the project's own test code. Run it only in projects the
+  user has asked you to work on.
+
+## References
+
+- `references/setup.md`: install and client configuration, environment variables.
+- `references/tools.md`: every tool's arguments.
+- `references/failure-kinds.md`: failure kinds and error codes, and what to do.
+- `references/example-session.md`: a worked fix-a-failing-test session with
+  `suggest-fix`.

package/skill/playwright-e2e-mcp/references/example-session.md

@@ -0,0 +1,53 @@
+# Example session: fixing a failing checkout test
+
+**User:** The checkout test started failing after the redesign. Can you fix it?
+
+1. Agent calls `run-test` with `{ "testFiles": ["tests/checkout.spec.ts"] }`.
+
+   ```
+   ## Playwright run — ❌ FAILED
+   | passed | failed | flaky | skipped |
+   | 2 | 1 | 0 | 0 |
+   ### 1 of 1. checkout.spec.ts › pays with card
+   File: checkout.spec.ts:18 | failed · timeout
+   ```
+
+2. Agent calls `get-failure` with `{ "index": 1 }`. The failed action is
+   `locator('#pay-now').click()`. The DOM snapshot at failure has no `#pay-now`,
+   but it does have a `Pay now` button. No network requests failed and the console
+   is clean, so the app itself looks healthy.
+
+3. The failure kind is `timeout`, but the cause is a locator that no longer
+   matches, so the agent calls `suggest-fix` with `{ "index": 1 }`:
+
+   ```
+   ### Proposed locator fix — confidence **high**
+   The button's accessible name matches "pay", and
+   `getByRole('button', { name: 'Pay now' })` is proven to resolve to exactly
+   that element.
+   -  await page.locator('#pay-now').click();
+   +  await page.getByRole('button', { name: 'Pay now' }).click();
+   ```
+
+4. Confidence is high, so the agent calls `suggest-fix` with
+   `{ "index": 1, "apply": true }`. The server writes the change, re-runs the test
+   with retries off, and reports `✅ Verified — the test passes with the fix`.
+   Had the test still failed, the server would have restored the original file.
+
+5. Agent calls `run-test` with `{ "lastFailed": true }` to confirm, then
+   `{ "testFiles": ["tests/checkout.spec.ts"] }` for the whole file: 3 passed.
+
+**Agent's reply:**
+
+> All 3 checkout tests pass now. "pays with card" failed because the redesign
+> removed the `#pay-now` id from the pay button. I changed the locator at
+> `tests/checkout.spec.ts:18` to `getByRole('button', { name: 'Pay now' })`,
+> which matches exactly one element, and the server re-ran the test to confirm
+> the fix.
+
+## When suggest-fix refuses
+
+If `suggest-fix` says the element is most likely missing, do not weaken the test.
+Read `get-failure` again for failed network requests and console errors, check the
+page with `inspect-page` (with `storageState` if it needs a login), and report it
+to the user as a probable app bug with that evidence.

package/skill/playwright-e2e-mcp/references/failure-kinds.md

@@ -0,0 +1,32 @@
+# Failure kinds and error codes
+
+## Per-test failure kinds (from `run-test` and `get-failure`)
+
+| Kind | Meaning | What to do |
+| --- | --- | --- |
+| `assertion` | An `expect` did not hold | Compare expected vs actual and the DOM snapshot; decide whether the app regressed or the expectation is stale, and say which before editing |
+| `timeout` | An action or the test ran out of time | Check the DOM snapshot and failed network requests for the real cause (element never appeared, API failed) before touching timeouts |
+| `server-unreachable` | The app under test did not respond | Ask the user to start the dev server, or configure `webServer` in the Playwright config; do not edit tests |
+| `browser-crash` | The browser or page closed unexpectedly | Re-run once; if it repeats, suggest `npx playwright install` to repair browsers |
+| `syntax` | The spec or config does not compile | Fix the reported `file:line` first; nothing else will run until it does |
+| `config` | The Playwright config is invalid | Read the message and fix the config |
+| `unknown` | Not classified | Read the message, stack and DOM snapshot directly |
+
+A test reported as **flaky** passed on the automatic retry. Run
+`diagnose-flaky` before deciding how to treat it.
+
+## Tool error codes
+
+| Code | Meaning | What to do |
+| --- | --- | --- |
+| `NO_PLAYWRIGHT` | `@playwright/test` is not installed in the project | Show the user the install command the error includes |
+| `NO_CONFIG` | No `playwright.config.*` found | Ask where the config is, or pass `projectRoot` / `config` |
+| `MULTIPLE_CONFIGS` | Several configs found; the error lists them numbered | Ask the user which one, or pick the obvious one, and pass `config: "2"` or its path |
+| `INVALID_PATH` | A path or `projectRoot` leaves the allowed roots | Use a path inside the project; to allow another root the user must set `PW_MCP_ALLOWED_ROOTS` |
+| `SERVER_NOT_RUNNING` | The app is not reachable | As `server-unreachable` above |
+| `TIMEOUT` | The whole run hit `timeoutMs`; results are partial | Narrow the run (`testFiles`, `grep`) or raise `timeoutMs` for this call |
+| `BROWSER_CRASH` | Browser failed | As `browser-crash` above |
+| `SYNTAX_ERROR` | A spec has a syntax error | Fix the reported file; `list-tests` still works via a source scan |
+| `DISK_FULL` | No space left on device | Ask the user to free disk space |
+| `SPAWN_FAILED` / `REPORT_MISSING` | Playwright could not start or wrote no report | Check Node and Playwright are installed; re-run with `LOG_LEVEL=debug` |
+| `CLIENT_DISCONNECT` | The run was cancelled | Re-run if still needed |

package/skill/playwright-e2e-mcp/references/setup.md

@@ -0,0 +1,120 @@
+# Setup: connecting the playwright-e2e-mcp server
+
+This skill only gives the agent instructions. The tools come from the
+`playwright-e2e-mcp` MCP server, which must be connected to the agent.
+
+## Requirements
+
+- playwright-e2e-mcp **0.2.0 or newer**, 0.3.0 recommended. `suggest-fix`,
+  `get-run-status`, `analyze-history`, verified locators and signed-in page
+  inspection arrived in 0.2.0; per-test flaky verdicts, `isolate`, tool profiles
+  and the `ci` command in 0.3.0. Check with
+  `npx -y playwright-e2e-mcp --version`.
+
+- Node.js 20 or newer.
+- A project with `@playwright/test` installed and a browser available:
+  `npx playwright install chromium`.
+
+## Install the server
+
+The server is published on npm as `playwright-e2e-mcp` and in the official MCP
+Registry as `io.github.xsignon-secure/E2E`. Pin a version in shared configs
+(`playwright-e2e-mcp@<version>`) so every machine runs the same build.
+
+**Claude Code**
+
+```bash
+claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp
+```
+
+**Claude Desktop, Cursor, Windsurf, Gemini CLI, Qwen Code and other JSON-config clients**
+
+```json
+{
+  "mcpServers": {
+    "playwright-e2e": {
+      "command": "npx",
+      "args": ["-y", "playwright-e2e-mcp"],
+      "env": { "PW_MCP_PROJECT_ROOT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+Claude Desktop also has a one-click `.mcpb` extension on the project's
+[GitHub releases](https://github.com/xsignon-secure/E2E/releases); it asks for the
+project root on install.
+
+**Codex CLI**
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.playwright-e2e]
+command = "npx"
+args = ["-y", "playwright-e2e-mcp"]
+startup_timeout_sec = 60
+tool_timeout_sec = 600
+```
+
+Raise the timeouts as shown: a Playwright run with retries takes longer than
+Codex's 60-second default tool timeout.
+
+## Install the skill
+
+Copy the `playwright-e2e-mcp/` folder (the one holding `SKILL.md`) into your
+agent's skills directory, for example:
+
+- Claude Code: `~/.claude/skills/` (personal) or `.claude/skills/` (project)
+- Codex CLI: `~/.codex/skills/`
+- Other agents: their documented skills folder
+
+## Environment variables
+
+Set these in the server's `env` block. None of them are secrets except
+`PW_MCP_HTTP_TOKEN`; never put a token in a committed config file.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PW_MCP_PROJECT_ROOT` | server working directory | Default project root for every tool |
+| `PW_MCP_TOOLS` | all | Tools to expose: names and/or profiles `core`, `triage`, `inspect`, `author` (same as the `--tools=` flag). `core` halves the tool-definition context |
+| `PW_MCP_ALLOWED_ROOTS` | none | Extra directories allowed as `projectRoot` (`:`-separated, `;` on Windows) |
+| `PW_MCP_BLOCK_PRIVATE_URLS` | off for stdio | `1` makes the URL tools refuse loopback, private-network and cloud-metadata addresses |
+| `PW_MCP_STORAGE_STATE` | none | Default Playwright storageState JSON (inside the project) for the page tools, so signed-in pages open logged in |
+| `PW_MCP_HISTORY` | on | `0` stops recording runs to `<project>/.playwright-e2e-mcp/history.jsonl` (this turns off `analyze-history`) |
+| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` or `silent` |
+| `PW_MCP_HTTP_TOKEN` | none | HTTP bridge only: bearer token that unlocks all tools |
+
+## Hosted endpoint
+
+Clients that only accept remote MCP servers can use the Streamable HTTP bridge
+(`https://playwright-e2e-mcp.vercel.app/api/mcp`, or your own deployment of the
+repo). Without a bearer token the bridge serves only `list-tests`,
+`get-failure` and `analyze-history`, so the core loop in `SKILL.md` needs a local install or a token.
+
+## Check it works
+
+Ask the agent to "list my Playwright tests". It should call `list-tests` and
+return files and titles. Clients that show MCP prompts also list
+`/fix-failing-test` and `/triage-flaky-tests`. If it says the tools are missing, the server is not
+connected: restart the client after editing its config.
+
+## CI (0.3.0+)
+
+The same diagnosis runs without an agent:
+
+```bash
+npx -y playwright-e2e-mcp ci --flaky-runs 3 --suggest 2 --output report.md
+```
+
+Exit code 0 means passed, 1 tests failed, 2 the run itself failed. On GitHub
+Actions it also writes to the job summary. As an Action:
+
+```yaml
+- uses: xsignon-secure/E2E@v0.3.0
+  with:
+    flaky-runs: 3
+    suggest: 2
+```
+
+It keeps one PR comment up to date when the run fails (needs
+`pull-requests: write`).

package/skill/playwright-e2e-mcp/references/tools.md

@@ -0,0 +1,161 @@
+# Tool reference
+
+All paths are relative to the project root. Every tool except `get-run-status`
+accepts an optional `projectRoot`, which must sit inside the server's allowed roots.
+
+## run-test
+
+Runs Playwright and returns stats, failures, failure kinds and fix hints.
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `testFiles` | string[] | Files or directories; `file:line` supported. Omit to run everything |
+| `grep` | string | Only tests whose title matches this regex |
+| `browser` | `chromium` \| `firefox` \| `webkit` | Matched against config project names |
+| `background` | boolean | Return a run id at once and keep running; follow it with `get-run-status` |
+| `headed` | boolean | Visible browser window |
+| `timeoutMs` | number | Wall-clock limit for the run (default 120000); partial results are returned past it |
+| `testTimeoutMs` | number | Per-test timeout |
+| `workers`, `retries` | number | Passed to Playwright |
+| `config` | string | Config path, or 1-based index when there are several |
+| `retryOnFailure` | boolean | Retry failures once before reporting (default true; ignored when `retries` is set) |
+| `lastFailed` | boolean | Re-run only the tests that failed last time |
+| `args` | string[] | Allowlisted Playwright flags such as `--repeat-each=N`, `--max-failures=N`, `--update-snapshots`, `--shard=1/3`, `--trace=on`; path-taking flags are rejected |
+
+Traces are captured on failure automatically so `get-failure` can show the DOM.
+Clients that send a progress token get live progress while the run goes.
+
+## get-failure
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `index` | number | 1-based failure index from the last run (default 1) |
+
+Returns the message and code frame, expected vs actual, stack, failure kind and
+diagnosis, console output, the DOM snapshot at failure with the failed action and
+its selector, failed network requests, console errors and warnings, and next steps.
+
+## inspect-page
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required, full http(s) URL |
+| `selector` | string | Inspect only matches of this CSS selector |
+| `waitFor` | string | Wait for a selector (CSS or `text=...`) first |
+| `waitUntil` | `load` \| `domcontentloaded` \| `networkidle` | Navigation wait |
+| `includeHtml` | boolean | Include rendered HTML (capped by `maxHtmlChars`, default 20000) |
+| `timeoutMs` | number | Default 45000 |
+| `view` | `elements` \| `locators` | `locators`: compact map of interactive elements with verified locators |
+| `storageState` | string | Playwright storageState JSON inside the project (signed-in session); defaults to `PW_MCP_STORAGE_STATE` |
+| `headers` | object | Extra HTTP headers |
+| `actions` | array | Up to 20 steps after load: `{ type: click\|dblclick\|fill\|press\|check\|uncheck\|select\|hover\|wait\|goto, locator?, value?, url?, ms? }` |
+| `viewport` | object | `{ width, height }` |
+
+Returns each element's Playwright locators proven unique on the page (role +
+name first), unique CSS selector, tag, visibility, box, text and attributes,
+plus console messages. `validate-selector` and `compare-visual-state` take the
+same `storageState`, `headers`, `actions` and `viewport`.
+
+## validate-selector
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required |
+| `selector` | string | Required: CSS, a Playwright selector, or a locator such as `getByRole('button', { name: 'Save' })` |
+| `timeoutMs` | number | Default 45000 |
+
+Verdicts: `✅ VALID — N matches` with samples and a unique locator for each,
+a strict-mode warning when more than one matches, `✅ VALID — 0 matches` with
+advice, or `❌ INVALID` with the parse error.
+
+## list-tests
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `config` | string | Config path or index |
+| `testDir` | string | Restrict to a directory |
+| `filter` | string | Case-insensitive substring of `file › title` |
+| `limit` | number | Default 500 |
+
+Falls back to a source scan when Playwright cannot list (broken install or spec).
+
+## generate-e2e-test
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `description` | string | Required: what the test should cover |
+| `pageUrl` | string | Start page (default: `baseURL` / `webServer.url`) |
+| `testDir`, `file` | string | Where to write; `file` must end in `.spec.*` or `.test.*` |
+| `write` | boolean | Write to disk (default true) |
+| `overwrite` | boolean | Replace a spec this tool generated earlier |
+| `liveInspect` | boolean | Cross-check selectors on the live page |
+| `config` | string | As above |
+
+## compare-visual-state
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required |
+| `name` | string | Baseline id, e.g. `checkout-page` |
+| `action` | `compare` \| `baseline` | Default `compare`; `baseline` re-captures the reference |
+| `selector` | string | Capture one element |
+| `fullPage` | boolean | Full scrollable page |
+| `tolerance` | number | Percent of pixels allowed to differ (default 0.1) |
+| `pixelThreshold` | number | Per-pixel channel delta (default 60) |
+| `waitUntil`, `waitFor`, `timeoutMs` | | As `inspect-page` |
+
+Baselines live in `.pw-mcp/visual/`.
+
+## diagnose-flaky
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `testFiles` | string[] | Default: tests that failed in the last run |
+| `runs` | number | 2 to 10 (default 3) |
+| `isolate` | boolean | Repeat fully parallel (`workers` default 4), then repeat the failing tests with one worker (0.3.0+) |
+| `separateProcesses` | boolean | One Playwright process per run instead of one `--repeat-each` process; slower (0.3.0+) |
+| `browser`, `headed`, `workers`, `config` | | As `run-test` |
+| `timeoutMs` | number | Per run (default 120000); the single `--repeat-each` process gets this × `runs` |
+
+Runs with retries disabled and returns, per test, passes, failures, duration
+spread, first error and `CONSISTENTLY FAILING`, `FLAKY` or `NOT REPRODUCING`,
+plus the verdict block for the worst test. With `isolate`, a second table reads
+each failing test as "fails only in parallel", "flaky even alone" or "fails
+alone too". Versions before 0.3.0 return one run-level verdict and a per-run
+table instead.
+
+## suggest-fix
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `index` | number | 1-based failure index from the last run (default 1) |
+| `apply` | boolean | Write the fix (default false: diff only) |
+| `verify` | boolean | After applying, re-run and revert if still failing (default true) |
+| `allowExpectationUpdate` | boolean | Allow applying a changed expected text (default false) |
+| `url`, `storageState`, `headers` | | Heal against a live page instead of the trace snapshot |
+| `config`, `timeoutMs` | | As `run-test` |
+
+Returns a unified diff: a locator fix rated `high` or `medium` confidence, or an
+expectation update rated `low` that is applied only with
+`allowExpectationUpdate: true`. Otherwise it refuses and says the element is most
+likely missing.
+
+## get-run-status
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `runId` | string | From `run-test` with `background: true` (default: latest) |
+| `waitSeconds` | number | Wait up to this long (max 55) |
+| `cancel` | boolean | Stop the run |
+
+## analyze-history
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `view` | `flaky` \| `patterns` \| `test` | Default `flaky` |
+| `test` | string | Substring of a test's file or title |
+| `lastRuns` | number | Default 30 |
+| `limit` | number | Default 15 |
+
+Reads `.playwright-e2e-mcp/history.jsonl`, written by every run
+(`PW_MCP_HISTORY=0` disables it).