@playwright-repl/mcp 0.13.0

package/README.md

@@ -0,0 +1,189 @@
+# @playwright-repl/mcp
+
+MCP server that lets AI agents (Claude Desktop, Claude Code, or any MCP client) control your real Chrome browser through the **Dramaturg** Chrome extension.
+
+## Why
+
+Most browser MCP servers work by launching a separate browser instance — a clean, isolated context with no history, no cookies, no authentication. They control the browser from the outside using Node.js running Playwright.
+
+**`@playwright-repl/mcp` is different.**
+
+It consists of two parts working together: **Dramaturg** (a Chrome extension that runs Playwright inside your existing Chrome session), and a MCP server that gives AI agents a natural language interface to control it.
+
+**Your real browser. Your real sessions.**
+
+- **No re-authentication** — Gmail, Notion, Salesforce, your banking portal — already logged in, ready to automate
+- **No separate browser window** — AI works in the browser you're already using
+- **No ephemeral context** — cookies, localStorage, session tokens — all intact
+
+### vs. other browser MCP servers
+
+| | `@playwright-repl/mcp` | Playwright MCP | Playwriter |
+|---|:---:|:---:|:---:|
+| MCP tools exposed | **1** `run_command` | ~70 tools | **1** `execute` |
+| Uses your real session | ✅ | ❌ | ✅ |
+| Playwright runs inside browser | ✅ | ❌ | ❌ |
+| `expect()` assertions | ✅ | ❌ | ❌ |
+| Full Playwright API | ✅ | ✅ | ✅ |
+| JS/DOM eval | ✅ | ❌ | ✅ |
+
+> Playwright MCP and Playwriter control Chrome from outside via CDP relay. `@playwright-repl/mcp` runs Playwright natively inside Chrome via `playwright-crx` — enabling `expect()`, recording, and a full DevTools panel alongside AI.
+
+## Architecture
+
+```
+Claude Desktop / Claude Code (or any MCP client)
+  ↕ MCP (stdio)
+playwright-repl MCP server
+  ↕ WebSocket bridge
+Chrome extension (panel page)
+  ↕ CDP / chrome.debugger
+Playwright running in your real Chrome session
+```
+
+## Setup
+
+### 1. Install the MCP server
+
+```bash
+npm install -g @playwright-repl/mcp
+```
+
+### 2. Install Dramaturg (Chrome extension)
+
+Load `packages/extension/dist/` as an unpacked extension in Chrome (`chrome://extensions` → Enable Developer mode → Load unpacked).
+
+Or install from the Chrome Web Store (coming soon).
+
+### 3. Configure your MCP client
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "playwright-repl": {
+      "command": "playwright-repl-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+**Claude Code** — run once in a terminal:
+
+```bash
+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.
+
+## 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.
+
+### 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
+- **Executes commands** — receives `run_command` calls from the AI and runs them against the active tab
+
+### Using the extension alongside AI
+
+The extension panel is more than just a bridge — it's a full REPL you can use at the same time as the AI:
+
+- **Watch AI commands execute** — the panel stays open while Claude drives the browser; you can see the page react in real time
+- **Intervene manually** — type a command in the panel console at any time, e.g. `snapshot` to check state or `goto` to navigate while the AI pauses
+- **Script editor** — write and run multi-line `.pw` or JS scripts side-by-side with AI automation; useful for building test flows interactively
+- **Tab switcher** — the toolbar dropdown lets you switch the panel (and the MCP server's active target) to any open tab
+- **Record your own flows** — stop the AI, click **Record**, interact with the page yourself to capture a `.pw` script, then hand it back to Claude for replay or modification. Recording only captures human interactions, not AI-driven commands.
+
+### Connection status
+
+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.`
+
+## Tool: `run_command`
+
+One tool, three input modes:
+
+### Keyword commands (`.pw` syntax)
+
+```
+snapshot                              # accessibility tree — always start here
+goto https://example.com             # navigate
+click Submit                         # click by text/label
+fill "Email" user@example.com        # fill a form field
+press Enter                          # key press
+verify-text Welcome                  # assert text is visible
+screenshot                           # capture page (returned as image to AI)
+scroll-down                          # scroll
+check "Remember me"                  # check a checkbox
+select "Country" "United States"     # select dropdown option
+localstorage-list                    # list localStorage
+```
+
+### Playwright API
+
+```
+await page.url()
+await page.title()
+await page.locator('button').count()
+await page.getByRole('link', { name: 'Get started', exact: true }).click()
+```
+
+### JavaScript / DOM
+
+```
+document.title
+window.location.href
+document.querySelectorAll('a').length
+```
+
+## 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.
+- **Use `screenshot` to verify state** — especially after navigation or complex interactions
+- **Prefer keyword commands** for common actions — they're shorter and more reliable than raw Playwright API
+- **Fall back to Playwright API** when keyword commands are ambiguous (e.g. two elements match the same text) — use `exact: true` or scope with a locator chain
+
+## Custom port
+
+By default the MCP server listens on port `9876`. To use a different port:
+
+**Claude Desktop** — via args or env in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "playwright-repl": {
+      "command": "playwright-repl-mcp",
+      "args": ["--port", "9877"]
+    }
+  }
+}
+```
+
+```json
+{
+  "mcpServers": {
+    "playwright-repl": {
+      "command": "playwright-repl-mcp",
+      "env": { "BRIDGE_PORT": "9877" }
+    }
+  }
+}
+```
+
+`--port` takes precedence over `BRIDGE_PORT`. Default is `9876`.
+
+Update Dramaturg's Bridge Port setting to match (Dramaturg icon → Options → Bridge Port).
+
+> **Note:** Claude Desktop and Claude Code cannot run simultaneously on the same port — close one before opening the other.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { BridgeServer } from '@playwright-repl/core';
+const argv = process.argv.slice(2);
+const portIdx = argv.indexOf('--port');
+const port = portIdx !== -1
+    ? parseInt(argv[portIdx + 1])
+    : (process.env.BRIDGE_PORT ? parseInt(process.env.BRIDGE_PORT) : 9876);
+const srv = new BridgeServer();
+try {
+    await srv.start(port);
+}
+catch (err) {
+    if (err?.code === 'EADDRINUSE') {
+        console.error(`Error: port ${port} is already in use. Another playwright-repl bridge or MCP inspector may be running. Stop it and restart Claude Desktop.`);
+        process.exit(1);
+    }
+    throw err;
+}
+console.error(`playwright-repl bridge listening on ws://localhost:${port}`);
+srv.onConnect(() => console.error('Extension connected'));
+srv.onDisconnect(() => console.error('Extension disconnected'));
+const RUN_COMMAND_INPUT_DESCRIPTION = `\
+A keyword command ('snapshot', 'goto https://example.com', 'click Submit', \
+'fill "Email" user@example.com'), a Playwright expression \
+('await page.url()'), or a JavaScript expression ('document.title')`;
+const RUN_COMMAND_DESCRIPTION = `\
+Run a command in the connected Chrome browser. Supports three input modes:
+
+1. KEYWORD (.pw) — playwright-repl commands:
+   snapshot, goto <url>, click <text>, fill <label> <value>, press <key>,
+   verify-text <text>, verify-no-text <text>, screenshot, scroll-down,
+   check <label>, select <label> <value>, localstorage-list, localstorage-clear
+
+2. PLAYWRIGHT — Playwright API (page.* / crxApp.*):
+   await page.url(), await page.title(),
+   await page.locator('button').count()
+
+3. JAVASCRIPT — any JS expression evaluated in the browser:
+   document.title, window.location.href,
+   document.querySelectorAll('a').length
+
+Use snapshot to understand the page structure before interacting. Use screenshot to visually verify the current state.`;
+const server = new McpServer({ name: 'playwright-repl', version: '0.12.0' });
+server.registerTool('run_command', {
+    description: RUN_COMMAND_DESCRIPTION,
+    inputSchema: {
+        command: z.string().describe(RUN_COMMAND_INPUT_DESCRIPTION),
+    },
+}, async ({ command }) => {
+    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.run(command);
+    if (result.image) {
+        const [header, data] = result.image.split(',');
+        const mimeType = (header.match(/data:(.*);base64/) ?? [])[1] ?? 'image/png';
+        return { content: [{ type: 'image', data, mimeType }] };
+    }
+    return {
+        content: [{ type: 'text', text: result.text || 'Done' }],
+        isError: result.isError,
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@playwright-repl/mcp",
+    "version": "0.13.0",
+    "type": "module",
+    "bin": {
+        "playwright-repl-mcp": "./dist/index.js"
+    },
+    "main": "./dist/index.js",
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "tsc --build tsconfig.build.json"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.10.0",
+        "@playwright-repl/core": "workspace:*",
+        "zod": "^3.24.0"
+    }
+}