# playread
Google search automation via Playwright MCP. Can be used as a CLI tool or as an MCP server.
## Installation
```bash
npm install -g playread
```
Or use directly with npx:
```bash
npx -y playread@latest google-search
```
## Usage
### As an MCP Server
Start playread as an MCP server to expose all flows as tools:
```bash
playread mcp
```
Or configure in your MCP client settings (e.g., Claude Desktop):
```json
{
"mcpServers": {
"playread": {
"command": "npx",
"args": ["-y", "playread@latest", "mcp"]
}
}
}
```
Available MCP tools:
- `fetch` - Fetch and extract main content from a web page URL
- `google-search` - Perform a Google search and extract results
### As a CLI Tool
### Google Search
```bash
playread google-search
```
Output format:
```json
{
"query": "Playwright automation testing",
"totalResults": 18,
"results": [
{
"title": "Playwright: Fast and reliable end-to-end testing for modern ...",
"url": "https://playwright.dev/",
"description": "Playwright enables reliable end-to-end testing for modern web apps..."
}
]
}
```
### Fetch URL Content
Extract important text content from any URL:
```bash
playread fetch https://example.com
```
Output format:
```json
{
"url": "https://example.com/",
"title": "Example Domain",
"contentLength": 129,
"content": "# Example Domain\nThis domain is for use in documentation examples..."
}
```
Perfect for:
- Extracting documentation from websites
- Fetching article content
- Parsing blog posts
- Getting README content from GitHub
- Any text-heavy webpage
## Creating Custom Flows
Flows are JavaScript modules that export a single async function. The function receives a connected `PlaywrightMCPClient` instance.
Create a new flow in the `flows/` directory:
```javascript
module.exports = async function(client) {
await client.navigate('https://example.com');
const snapshot = await client.snapshot();
console.log('Page loaded');
await client.close();
};
```
## Available Client Methods
### Connection
- `connect()` - Connect to Playwright MCP server
- `disconnect()` - Disconnect and cleanup
### Tools Discovery
- `listTools()` - List all available tools
- `callTool(name, args)` - Call any tool directly
### Browser Control
- `navigate(url)` - Navigate to URL
- `navigateBack()` - Go back
- `close()` - Close browser
- `resize(width, height)` - Resize window
- `install()` - Install browser
### Page Interaction
- `snapshot()` - Get accessibility snapshot
- `click(element, ref)` - Click element
- `type(element, ref, text, submit, slowly)` - Type text
- `pressKey(key)` - Press keyboard key
- `hover(element, ref)` - Hover over element
- `drag(startElement, startRef, endElement, endRef)` - Drag and drop
### Forms
- `fillForm(fields)` - Fill multiple form fields
- `selectOption(element, ref, values)` - Select dropdown option
- `fileUpload(paths)` - Upload files
### Page State
- `evaluate(func)` - Execute JavaScript
- `screenshot(filename, type, fullPage, element, ref)` - Take screenshot
- `consoleMessages(onlyErrors)` - Get console logs
- `networkRequests()` - Get network activity
### Dialogs
- `handleDialog(accept, promptText)` - Handle alerts/confirms
### Tabs
- `tabs(action, index)` - Manage browser tabs
### Wait
- `waitFor(text, textGone, time)` - Wait for conditions
## Flow Details
### google-search
- Navigates to Google
- Searches for "Playwright automation testing"
- Waits 30 seconds for results to load
- Extracts all result titles, URLs, and descriptions
- Returns comprehensive JSON output with full result metadata
### fetch
- Accepts a URL as an argument
- Navigates to the URL
- Intelligently extracts main content using heuristics:
- Prioritizes `<main>`, `<article>`, and semantic content areas
- Extracts structured text including headings, paragraphs, lists, and code blocks
- Removes duplicate content and navigation elements
- Formats output as clean markdown
- Returns JSON with URL, title, content length, and extracted content
- Limits output to 50,000 characters for conciseness
- Works universally across documentation sites, blogs, articles, and more
## Requirements
- Node.js 14+
- Playwright MCP server (installed automatically via npx)
## Notes
- Always close the browser before flows complete
- Supports `file://` URLs for local testing
- Use `browser_evaluate` for debugging window globals
- No hardcoded values - all flows use ground truth from snapshots
- Screenshots are automatically saved to `/tmp/playwright-mcp-output/<timestamp>/`
