# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Playwright MCP is a Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. It enables LLMs to interact with web pages through structured accessibility snapshots rather than screenshots.
## Build and Test Commands
```bash
# Run all tests (Chrome by default)
npm test
# Run tests for specific browsers
npm run ctest # Chrome
npm run ftest # Firefox
npm run wtest # WebKit
# Run a single test file
npx playwright test tests/core.spec.ts
# Run a single test by name
npx playwright test -g "browser_navigate"
# Run tests in Docker
npm run dtest
# Lint/update README (generates tool docs from code)
npm run lint
# Copy config.d.ts from upstream Playwright repo
npm run copy-config
# Roll (copy-config + lint)
npm run roll
```
## Architecture
This is a thin wrapper package around the MCP implementation in the main Playwright repository. The core MCP logic lives in `playwright/lib/mcp/` - this package just re-exports it.
**Entry points:**
- `cli.js` - CLI entry point that patches MCP Server before loading Playwright modules. Adds usage tracking (writes to `usage.txt`) and tool filtering via config file. Uses `playwright-core/lib/utilsBundle` for command parsing and `playwright/lib/mcp/program` for MCP commands.
- `index.js` - Library entry point, exports `createConnection` from `playwright/lib/mcp/index`
- `config.d.ts` - TypeScript configuration types (copied from main Playwright repo via `npm run copy-config`)
**Test structure:**
- `tests/fixtures.ts` - Custom Playwright test fixtures providing MCP client setup via `@modelcontextprotocol/sdk`
- `tests/testserver/` - HTTP/HTTPS test server for testing browser automation
- Tests use `StdioClientTransport` to communicate with the MCP server spawned as a subprocess
**Browser extension:**
- `extension/` - Chrome extension ("Playwright MCP Bridge") that allows connecting to existing browser tabs
- Has its own build system (Vite), tests, and tsconfig
## Key Patterns
- Tests extend base Playwright test with `startClient` fixture that spawns the MCP server and connects via stdio
- Response parsing uses section-based format (sections start with `### `)
- The `mcpBrowser` option controls which browser to test against
- Set `PWMCP_DEBUG=1` to see MCP server stderr in test output
## Local Modifications
This fork adds features on top of upstream:
- **Usage tracking**: `cli.js` intercepts `CallToolRequestSchema` to count tool invocations, persisted to `usage.txt`
- **Tool filtering**: Config file can specify `tools.include` (allowlist) or `tools.exclude` (blocklist) to filter available tools
