@playwright-repl/mcp 0.13.0 → 0.15.0

package/README.md

@@ -20,7 +20,7 @@ It consists of two parts working together: **Dramaturg** (a Chrome extension tha
 
 | | `@playwright-repl/mcp` | Playwright MCP | Playwriter |
 |---|:---:|:---:|:---:|
-| MCP tools exposed | **1** `run_command` | ~70 tools | **1** `execute` |
+| MCP tools exposed | **2** (`run_command` + `run_script`) | ~70 tools | **1** `execute` |
 | Uses your real session | ✅ | ❌ | ✅ |
 | Playwright runs inside browser | ✅ | ❌ | ❌ |
 | `expect()` assertions | ✅ | ❌ | ❌ |
@@ -36,7 +36,7 @@ Claude Desktop / Claude Code (or any MCP client)
   ↕ MCP (stdio)
 playwright-repl MCP server
   ↕ WebSocket bridge
-Chrome extension (panel page)
+Chrome extension (offscreen document → service worker)
   ↕ CDP / chrome.debugger
 Playwright running in your real Chrome session
 ```
@@ -82,16 +82,17 @@ claude mcp add playwright-repl playwright-repl-mcp
 
 ### 4. Connect
 
-Open Chrome → click the **Dramaturg** icon to open the side panel. The extension connects to the MCP server automatically. You're ready.
+The extension connects to the MCP server automatically — no need to open the side panel. Just make sure Chrome is running with the Dramaturg extension installed.
 
 ## Dramaturg — The Extension
 
-Dramaturg is the other half of the system — it's what gives the MCP server access to your real browser session. While the MCP server is running, the Dramaturg panel acts as the live bridge between AI commands and Chrome.
+Dramaturg is the other half of the system — it's what gives the MCP server access to your real browser session.
 
 ### What the extension does
 
 - **Runs Playwright inside Chrome** — uses `playwright-crx` and `chrome.debugger` to execute commands directly in your existing session, no separate browser needed. Because Playwright runs inside the browser rather than relaying through an external process, the entire AI → command → result loop is faster.
-- **Connects automatically** — opens a WebSocket connection to the MCP server as soon as the side panel is visible; reconnects if the connection drops
+- **Connects automatically** — a persistent offscreen document maintains the WebSocket connection to the MCP server; reconnects if the connection drops. No side panel needed.
+- **Auto-attaches** — on the first command, automatically attaches to the active Chrome tab
 - **Executes commands** — receives `run_command` calls from the AI and runs them against the active tab
 
 ### Using the extension alongside AI
@@ -108,7 +109,7 @@ The extension panel is more than just a bridge — it's a full REPL you can use
 
 The extension connects to the MCP server on port `9876` by default. To check or change the port: extension icon → **Options** → **Bridge Port**. Changes take effect after reopening the panel.
 
-When the panel is open and connected, the MCP server logs `Extension connected` to stderr. When the panel is closed or Chrome is not open, `run_command` returns: `Browser not connected. Open Chrome with Dramaturg — it connects automatically.`
+When the extension is connected, the MCP server logs `Extension connected` to stderr. When Chrome is not open or the extension is not installed, `run_command` returns: `Browser not connected. Open Chrome with Dramaturg — it connects automatically.`
 
 ## Tool: `run_command`
 
@@ -147,6 +148,46 @@ window.location.href
 document.querySelectorAll('a').length
 ```
 
+## Tool: `run_script`
+
+Batch execution for multi-line scripts. Two language modes:
+
+### Keyword script (`language="pw"`)
+
+Splits by line, runs each command sequentially, returns ✓/✗ per line:
+
+```
+goto https://demo.playwright.dev/todomvc/
+fill "What needs to be done?" "Buy groceries"
+press Enter
+verify-text "Buy groceries"
+```
+
+### JavaScript (`language="javascript"`)
+
+Runs the entire block as one evaluation — use for Playwright API with assertions:
+
+```js
+await page.goto('https://demo.playwright.dev/todomvc/');
+await page.getByPlaceholder('What needs to be done?').fill('Buy groceries');
+await page.keyboard.press('Enter');
+await expect(page.getByText('Buy groceries')).toBeVisible();
+```
+
+## Prompt: `generate-test`
+
+A prompt template that guides the AI to generate a passing Playwright test from a described scenario.
+
+**Args:**
+- `steps` (required) — describe the test scenario, e.g. "log in with email/password, verify the dashboard loads". Also accepts pasted `.pw` scripts.
+- `url` (optional) — URL to navigate to first.
+
+**In Claude Desktop:** click "+" → select `generate-test` → fill in the form → send.
+
+**In Claude Code:** `/mcp__playwright-repl__generate-test`
+
+The AI navigates the page, takes snapshots, writes Playwright assertions, runs them via `run_script(language="javascript")`, and iterates until all pass.
+
 ## Tips for AI agents
 
 - **Call `snapshot` to understand the page** — it returns the accessibility tree with element refs (`e1`, `e5`, …) that you can use with `click`, `fill`, etc. Useful before interacting with an unfamiliar page.

package/dist/index.js

@@ -67,6 +67,70 @@ server.registerTool('run_command', {
         isError: result.isError,
     };
 });
+const RUN_SCRIPT_DESCRIPTION = `\
+Run a multi-line script, returning combined pass/fail results.
+Useful for replaying a known script without per-step round trips.
+Prefer run_command for AI-driven exploration where you need to observe and adapt after each step.
+
+language='pw': each line is a .pw keyword command, run sequentially. Lines starting with # are skipped. Stops on first error.
+language='javascript': the entire script is run as a single JavaScript/Playwright block.`;
+server.registerTool('run_script', {
+    description: RUN_SCRIPT_DESCRIPTION,
+    inputSchema: {
+        script: z.string().describe('The script to execute'),
+        language: z.enum(['pw', 'javascript']).describe("'pw' for keyword commands (one per line), 'javascript' for a JS/Playwright block"),
+    },
+}, async ({ script, language }) => {
+    if (!srv.connected) {
+        return {
+            content: [{ type: 'text', text: 'Browser not connected. Open Chrome with the playwright-repl extension — it connects automatically.' }],
+            isError: true,
+        };
+    }
+    const result = await srv.runScript(script, language);
+    return {
+        content: [{ type: 'text', text: result.text || 'Done' }],
+        isError: result.isError,
+    };
+});
+const GENERATE_TEST_PROMPT = (steps, url) => `\
+Generate a passing Playwright test for the following scenario:
+${steps}
+
+Workflow:
+1. ${url ? `Navigate to ${url} using run_command('goto ${url}').` : 'Navigate to the target URL using run_command.'}
+2. Take a snapshot using run_command('snapshot') to understand the page structure.
+3. Interact with the page as needed (click, fill, press) using run_command.
+4. After each interaction, take another snapshot to verify the state before asserting.
+5. Write assertions using \`expect\`.
+
+Example pattern:
+  await page.goto('https://example.com');
+  await expect(page).toHaveTitle('Example', { exact: true });
+  await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+  await page.getByRole('link', { name: 'Get started', exact: true }).click();
+  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
+
+Code constraints:
+- Use only \`page\` and \`expect\` — available as globals, do NOT import them
+- Plain \`await\` statements only — no \`import\`, no \`test()\` wrapper, no \`describe()\`
+- Use \`exact: true\` when a locator text might match multiple elements
+
+Once you have the code, run it with run_script(language="javascript").
+If any assertion fails, read the error, fix the code, and run again until all pass.
+Show the final passing code.`;
+server.registerPrompt('generate-test', {
+    description: 'Generate a passing Playwright test from a described scenario',
+    argsSchema: {
+        steps: z.string().describe('Describe the test scenario, e.g. "log in with email/password, verify the dashboard loads"'),
+        url: z.string().optional().describe('URL to navigate to first (optional)'),
+    },
+}, ({ steps, url }) => ({
+    messages: [{
+            role: 'user',
+            content: { type: 'text', text: GENERATE_TEST_PROMPT(steps, url) },
+        }],
+}));
 const transport = new StdioServerTransport();
 await server.connect(transport);
 //# sourceMappingURL=index.js.map

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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playwright-repl/mcp",
-    "version": "0.13.0",
+    "version": "0.15.0",
     "type": "module",
     "bin": {
         "playwright-repl-mcp": "./dist/index.js"