<div align="center">

# 🎭 Playwright SPA MCP

**The Playwright MCP server built for modern web apps — persistent sessions, React/Vue/Angular support, 143+ devices and smart DOM waiting.**

[![License: MIT](https://img.shields.io/github/license/manganate006/playwright-spa-mcp)](LICENSE)
![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.25%2B-purple)

**[Installation](#installation) · [Why](#why-this-server) · [Tools](#tools) · [Examples](#examples) · [Limitations](#limitations)**

</div>

## Overview

An [MCP](https://modelcontextprotocol.io) server that drives a real Chromium browser, purpose-built for Single Page Applications. Your assistant can log in, click, type and screenshot — and the SPA's state survives across calls:

> **You:** Log into app.example.com, open the dashboard and screenshot it.
>
> **Assistant:** *(calls `spa_session_start`, then `spa_chain` [type-realistic → click → wait-for-idle], then `spa_screenshot`)*
> Logged in and captured the dashboard — React state preserved across the session.

## Why this server?

| Feature | playwright-spa-mcp | Other Playwright MCPs |
|---------|:------------------:|:---------------------:|
| Persistent sessions | ✅ | ❌ |
| React/Vue/Angular detection | ✅ | ❌ |
| Smart DOM idle waiting | ✅ | ❌ |
| Realistic typing | ✅ | ❌ |
| Device emulation | 143+ | Limited |
| Action chains | ✅ | ❌ |
| HTTP with browser cookies | ✅ | ❌ |

## Installation

```bash
# One command — no clone needed
claude mcp add playwright-spa -- npx -y github:manganate006/playwright-spa-mcp

# Install the Chromium browser Playwright drives
npx playwright install chromium
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "playwright-spa": {
      "command": "npx",
      "args": ["-y", "github:manganate006/playwright-spa-mcp"]
    }
  }
}
```

<details>
<summary>Alternative: clone &amp; install locally</summary>

```bash
git clone https://github.com/manganate006/playwright-spa-mcp.git
cd playwright-spa-mcp
npm install
npx playwright install chromium
claude mcp add playwright-spa -- node $(pwd)/src/index.js
```
</details>

## Tools

22 tools, `spa_` prefix. Chain-action list, 143+ device shortcuts and CLI usage: **[docs/ADVANCED.md](docs/ADVANCED.md)**.

| Group | Tools |
|---|---|
| 📸 Screenshot & navigation | `spa_screenshot`, `spa_navigate`, `spa_go_back`, `spa_go_forward`, `spa_wait_idle` |
| 📝 Interactions | `spa_click`, `spa_fill`, `spa_type_realistic`, `spa_upload`, `spa_drag` |
| ⛓️ Chains | `spa_chain` (run many actions in one call) |
| 🔐 Sessions | `spa_session_start`, `spa_session_end`, `spa_session_list` |
| 🔎 Inspection | `spa_get_text`, `spa_assert`, `spa_evaluate`, `spa_http_request` |
| 🖼️ iframes | `spa_iframe_click`, `spa_iframe_fill` |
| ℹ️ Discovery | `spa_list_devices`, `spa_list_actions` |

## Examples

**Log into a React app and keep the session** — realistic typing fires React's `onChange`:

```js
spa_session_start({ session: "myapp" })

spa_chain({
  session: "myapp",
  url: "https://app.example.com/login",
  spaMode: "react",
  chain: [
    { action: "type-realistic", selector: "#email", value: "user@example.com" },
    { action: "type-realistic", selector: "#password", value: "secret123" },
    { action: "click", selector: "button[type=submit]" },
    { action: "wait-for-idle" },
    { action: "screenshot" }
  ]
})

// Same session — React state is preserved
spa_click({ session: "myapp", selector: ".dashboard-item" })
```

**Mobile device emulation:**

```js
spa_screenshot({ url: "https://example.com", device: "iPhone 15 Pro", fullPage: true })
```

**Authenticated API call reusing the session cookies:**

```js
spa_http_request({ session: "myapp", url: "https://api.example.com/user/profile", method: "GET" })
```

## Limitations

- **Chromium only** — Firefox/WebKit are not wired up; requires `npx playwright install chromium`
- **Local browser** — spawns a real browser process; not suited to sandboxes without one
- **SPA heuristics** — React/Vue/Angular readiness is detected heuristically (`spaMode: "auto"`); heavy custom frameworks may need explicit `wait-for` / `wait-for-idle`
- **Sessions are in-memory** — they live with the server process and don't persist across restarts

## SPA framework support

Detects and waits correctly for **React** (finishes rendering, proper `onChange`), **Vue** (v-model bindings) and **Angular** (Zone.js stability). Use `spaMode: "auto"` to detect automatically. Details in [docs/ADVANCED.md](docs/ADVANCED.md#spa-framework-support).

## Built with this MCP

| Project | Description |
|---|---|
| [atp.mangi.fr](https://atp.mangi.fr) | 🎾 ATP tennis stats since 1968 |
| [piscinade.com](https://piscinade.com) | 🏊 Pool-party finder in France |

## License

[MIT](LICENSE) © manganate006