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

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:

{
  "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

npx vitest run

License

MIT