# pagesnap-mcp
MCP server that wraps existing PageSnap session packs so an LLM can list sessions, read locators, and map them to Playwright, Selenium, or Cypress.

This is NOT a capture tool. It does not open a browser, auto-scan URLs, or fetch browsers. Playwright is not a dependency.

Capture happens in pagesnap-playwright or pagesnap-selenium. Point this server at a parent folder of session packs (flow.md plus yaml plus optional PROMPT.md).

## How to run
```bash
npm install
npm run build
node dist/index.js
```

The process speaks MCP over stdio and waits on stdin. It looks hung in a terminal; that is expected. Stop it with Ctrl+C.
Optional env: PAGESNAP_SESSIONS_DIR (default ./sessions) is the parent directory of PageSnap session folders.

## Cursor MCP config
Example .cursor/mcp.json. Point PAGESNAP_SESSIONS_DIR at a PageSnap session parent, e.g. playwright-ts-framework/snapshots:
```json
{
  "mcpServers": {
    "pagesnap": {
      "command": "node",
      "args": [
        "/absolute/path/to/pagesnap-mcp/dist/index.js"
      ],
      "env": {
        "PAGESNAP_SESSIONS_DIR": "/absolute/path/to/playwright-ts-framework/snapshots"
      }
    }
  }
}
```

This server only reads packs already on disk. It is not a capture tool.

## Tools
Token-efficient: list_sessions and read_session return keys and summaries first. YAML file bodies are not dumped.
- list_sessions: no args. Sessions from PAGESNAP_SESSIONS_DIR.
- read_session: { session }. flow.md, yaml file names, parsed controls (cap 200).
- map_locator: { by, value, name?, framework? }. snippet, score, stability. framework: playwright|selenium|cypress (default playwright).
- get_prompt: { session, framework? }. PROMPT.md if present, else a synthesized prompt.

## Locators
YAML by values: testid, role, label, id, name, placeholder, linkText, css, xpath.
Scores match PageSnap: testid 98, role 95, label/id 90, name 88, placeholder 85, linkText 75, css 60, xpath 40.
Playwright testid always maps to page.getByTestId(...). Sauce Demo uses data-test via Playwright testIdAttribute; still emit getByTestId. Generic role-less data-testid nodes still map to getByTestId, never getByRole('generic').

## Tests
```bash
npx vitest run
```

## License

MIT