chore(claude): add playwright mcp (#15447)

- Add Playwright MCP server configuration for Claude Code (.mcp.json),
Cursor (.cursor/mcp.json) and VSCode (.vscode/mcp.json)
- Enable the MCP server in Claude settings (.claude/settings.json)
- Document Playwright MCP usage in CLAUDE.md to make sure the agent
knows when to use it

Author: AlessioGr

.claude/settings.json

@@ -23,6 +23,8 @@
       }
     ]
   },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": ["playwright"],
   "permissions": {
     "allow": [
       "Bash(gh issue view:*)",

.cursor/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "pnpm",
+      "env": {},
+      "args": [
+        "dlx",
+        "@playwright/mcp@latest",
+        "--caps=vision,verify,tracing,devtools",
+        "--isolated",
+        "--headless"
+      ]
+    }
+  }
+}

.gitignore

@@ -263,6 +263,7 @@ GitHub.sublime-settings
 !.vscode/launch.json
 !.vscode/extensions.json
 !.vscode/*.code-snippets
+!.vscode/mcp.json
 
 # Local History for Visual Studio Code
 .history/
@@ -353,3 +354,6 @@ licenses.csv
 
 # SQLite DB
 payload.db
+
+# Screenshots created by Playwright MCP
+.playwright-mcp

.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "pnpm",
+      "env": {},
+      "args": [
+        "dlx",
+        "@playwright/mcp@latest",
+        "--caps=vision,verify,tracing,devtools",
+        "--isolated",
+        "--headless"
+      ]
+    }
+  }
+}

.vscode/mcp.json

@@ -0,0 +1,15 @@
+{
+  "servers": {
+    "playwright": {
+      "command": "pnpm",
+      "env": {},
+      "args": [
+        "dlx",
+        "@playwright/mcp@latest",
+        "--caps=vision,verify,tracing,devtools",
+        "--isolated",
+        "--headless"
+      ]
+    }
+  }
+}

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) and Cursor when working with code in this repository.
 
 ## Project Structure
 
@@ -84,6 +84,45 @@ Payload is a monorepo structured around Next.js, containing the core CMS platfor
 - Default database is MongoDB (in-memory). Switch to Postgres with `PAYLOAD_DATABASE=postgres`
 - Docker services: `pnpm docker:start` / `pnpm docker:stop` / `pnpm docker:restart`
 
+### Playwright MCP
+
+You should have access to the Playwright MCP server. This MCP server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.
+
+**Prerequisites:**
+
+- The dev server MUST be running (`pnpm run dev`) before using the MCP
+- First call `browser_install` to set up the browser if needed
+
+**Key tools (not exhaustive):**
+
+- `browser_navigate` - Navigate to a URL
+- `browser_snapshot` - Get accessibility snapshot of current page
+- `browser_click` - Click elements (requires `ref` from snapshot)
+- `browser_fill_form` - Fill form fields
+- `browser_take_screenshot` - Capture screenshot (use `fullPage: true` for full page)
+
+**Screenshots for visual verification:**
+
+Use `browser_take_screenshot` to visually verify UI state. Useful for:
+
+- Confirming layout and styling look correct
+- Checking component rendering (tags, forms, tables)
+- Debugging UI issues that aren't visible in accessibility snapshots
+
+```
+browser_take_screenshot()                    # Viewport only
+browser_take_screenshot({ fullPage: true })  # Full scrollable page
+```
+
+Screenshots are saved to `.playwright-mcp/` and displayed inline.
+
+**Usage flow:**
+
+1. Ensure dev server is running on `localhost:3000`
+2. Call `browser_navigate` to open a page
+3. Call `browser_snapshot` to get element refs
+4. Use refs to interact with `browser_click`, `browser_fill_form`, etc.
+
 ## Testing
 
 ### Writing Tests - Required Practices