MCP Cypress Page Object Generator

This MCP (Model Context Protocol) server automatically generates complete Cypress Page Object classes for any web page provided.

Features

• Web Scraping: Uses Puppeteer to fetch and render web pages
• HTML Parsing: Uses Cheerio to parse HTML and extract element information
• Page Object Generation: Creates complete TypeScript Page Object classes with:
  • Private element locators
  • Public getter methods
  • Interaction methods (click, type, select, etc.)

Sample prompt:

Create a page object file using the following url: https://www.saucedemo.com/ 

Generated Output

The server generates:

1. Page Object Class ({ClassName}.ts)

export class ExampleComLoginPage {
  // Private elements
  #elements = {
    button_login: () => cy.get('#login-button'),
    input_username: () => cy.get('input[name="username"]'),
    link_home: () => cy.contains('a', 'Home')
  }

  // Public getters
  get ButtonLogin() { return this.#elements.button_login() }
  get InputUsername() { return this.#elements.input_username() }
  get LinkHome() { return this.#elements.link_home() }

  // Interaction methods
  clickButtonLogin() { return this.#elements.button_login().click() }
  typeInputUsername(text: string) { return this.#elements.input_username().type(text) }
  clickLinkHome() { return this.#elements.link_home().click() }

}

Element Types Supported

• Buttons: Click interactions with validation
• Input Fields: Type, clear, check/uncheck (for checkboxes/radio)
• Links: Click interactions with navigation verification
• Select Dropdowns: Select options with validation
• Textareas: Type and clear with content verification
• Forms: Submit interactions with success/error handling

Installation

Follow standard procedures to install an MCP in the client of your choice

Usage

1. Start the server:

   node index.js

2. Use with an MCP client: The server exposes a generatePageObjectFile tool that accepts a URL parameter.

   Example tool call:

   {
     "method": "tools/call",
     "params": {
       "name": "generatePageObjectFile",
       "arguments": {
         "url": "https://example.com/login"
       }
     }
   }

3. Response format: The server returns both the Page Object class:

   // ===== PAGE OBJECT CLASS =====
   // Save this as: ExampleComLoginPage.ts
   export class ExampleComLoginPage { ... } 
   

Dependencies

• @modelcontextprotocol/sdk: MCP server implementation
• puppeteer: Web scraping and page rendering
• cheerio: HTML parsing and element selection
• zod: Schema validation
• typescript: Type safety

Error Handling

The server includes comprehensive error handling for:

• Invalid URLs
• Network connectivity issues
• Page loading failures
• HTML parsing errors

Browser Configuration

The server uses Puppeteer with the following settings:

• Headless mode for server environments
• No-sandbox mode for containerized deployments
• Network idle waiting for dynamic content

Contributing

To add support for new element types, interaction methods, or test patterns, modify the generatePageObjectClass function in index.js.

Troubleshooting: Updating to the Latest MCP Version

If you are intending to update to the latest version of this MCP server package but the new version is not being pulled by npm, try this:

1. Clear the NPM cache and reinstall the package:

   npm cache clean --force
   npm install @jprealini/cypress-mcp@latest --save-dev

2. If using a lockfile (package-lock.json or yarn.lock), delete it and run:

   npm install

3. For global installs, update globally:

   npm install -g @jprealini/cypress-mcp@latest

4. Verify the installed version:

   npm list @jprealini/cypress-mcp

These steps ensure consumers always get the latest published MCP version and avoid issues with cached or locked old versions.

Example: Generated Page Object Format (saucedemo.com)

Below is an example of the expected Page Object format generated by MCP for saucedemo.com:

export class Swag_labsPage {
  // Private elements
  #elements = {
    inputUsername: () => cy.get('[data-test="username"]'),
    inputPassword: () => cy.get('[data-test="password"]'),
    inputLoginButton: () => cy.get('[data-test="login-button"]')
  }

  // Element meta (currently not used for bulk actions)

  // Public getters
  get inputUsername() { return this.#elements.inputUsername() }
  get inputPassword() { return this.#elements.inputPassword() }
  get inputLoginButton() { return this.#elements.inputLoginButton() }

  // Value/State getters
  getValueInputUsername() { return this.#elements.inputUsername().invoke('val') }
  getValueInputPassword() { return this.#elements.inputPassword().invoke('val') }
  getTextInputLoginButton() { return this.#elements.inputLoginButton().invoke('text') }

  // Interaction methods (per-element actions)
  typeInputUsername(text) { return this.#elements.inputUsername().type(text) }
  clearInputUsername() { return this.#elements.inputUsername().clear() }
  typeInputPassword(text) { return this.#elements.inputPassword().type(text) }
  clearInputPassword() { return this.#elements.inputPassword().clear() }
  clickInputLoginButton() { return this.#elements.inputLoginButton().click() }
}

This format follows one of the mostly used page object standards, using data attributes for selectors, private element encapsulation, public getters, value/state getters, and interaction methods for each element.

If you need or expect a different pattern, you can generate this base structure using this MCP, and then use your own instruction set to edit it to fit your needs, using a prompt like:

Create a page object file using the following url: https://www.saucedemo.com/ and after creating it, edit it to meet the requirements described in my instructions.md file