npm package: @iflow-mcp/dhaval-patel262-cypress-mcp
Description: Cypress Tools for MCP
Latest version: 0.0.3

# Cypress MCP Server

A Model Context Protocol (MCP) server for Cypress that enables AI systems to create, execute, and analyze automated tests for web applications through the Model Context Protocol (MCP).

## 🎉 Enhanced Implementation

This project implements a robust HTTP transport with Server-Sent Events (SSE) support, following the same architecture as the Playwright MCP server. Our implementation leverages the official `@modelcontextprotocol/sdk` package to ensure full compliance with the MCP specification.

## Features

- **Standards-Compliant MCP Implementation**: Implements the Model Context Protocol using the official SDK
- **HTTP Transport with SSE Support**: Reliable server-client communication using Server-Sent Events
- **Streamable HTTP Support**: Alternative transport method for compatible clients
- **Natural Language Test Parsing**: Convert plain English test scenarios into structured test plans
- **Cypress Test Generation**: Generate executable Cypress tests from structured test plans
- **Test Execution**: Run tests against real websites
- **Test Reporting**: Generate detailed reports of test execution results
- **Containerized Deployment**: Easy deployment using Docker

## Available Tools

The Cypress MCP server provides the following categories of tools that AI systems can use to interact with web applications:

### Core Testing Tools

- **Test Generation**: Convert natural language descriptions into executable Cypress tests
- **Test Execution**: Run tests against real websites and gather results
- **Test Reporting**: Generate detailed reports of test execution

### Browser Automation Tools

#### Navigation Tools
- `cypress_navigate` - Navigate to a URL
- `cypress_go_back` - Go back in browser history
- `cypress_go_forward` - Go forward in browser history 
- `cypress_reload` - Reload the current page

#### Element Interaction Tools
- `cypress_click` - Click on an element
- `cypress_double_click` - Double-click on an element
- `cypress_type` - Type text into an input element
- `cypress_get_text` - Get the text content of an element
- `cypress_element_exists` - Check if an element exists

#### Assertion Tools
- `cypress_assert_text` - Assert element contains specific text
- `cypress_assert_visible` - Assert element visibility
- `cypress_assert_attribute` - Assert element has attribute with value
- `cypress_assert_url` - Assert URL matches pattern
- `cypress_assert_count` - Assert number of elements matching selector

#### Screenshot Tools
- `cypress_screenshot` - Take a screenshot of the page
- `cypress_element_screenshot` - Screenshot a specific element

#### Wait Tools
- `cypress_wait_for_element` - Wait for element to meet condition
- `cypress_wait_for_page_load` - Wait for page to finish loading
- `cypress_wait` - Wait for fixed time
- `cypress_wait_for_request` - Wait for network request

#### Network Tools
- `cypress_intercept_request` - Intercept network requests
- `cypress_mock_response` - Mock network responses
- `cypress_block_requests` - Block network requests

## Requirements

- Node.js 18 or newer
- Cypress 13.x or newer
- An MCP client (VS Code, Claude for VSCode, Anthropic Claude, GitHub Copilot, etc.)

## Installation

### Local Installation

1. Clone this repository
2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

4. Start the server:

```bash
node lib/cli-server.js http
```

To run in headless mode (recommended for production):

```bash
node lib/cli-server.js http --headless
```

### Docker Installation

For easier deployment and isolation, you can use Docker:

1. Build the Docker image:

```bash
docker build -t cypress-mcp .
```

2. Run the container:

```bash
docker run -d --name cypress-mcp -p 3000:3000 -e NODE_ENV=production -e OPENAI_API_KEY=your-api-key-here -e HEADLESS=true cypress-mcp
```

### Docker Compose Installation

Alternatively, you can use Docker Compose for easier management:

1. Create a `.env` file with your environment variables:

```
OPENAI_API_KEY=your-api-key-here
HEADLESS=true
```

2. Run with Docker Compose:

```bash
docker-compose up -d
```

## VSCode Configuration

To use the Cypress MCP Server with VSCode or other AI assistants, add the following to your `mcp_config.json` file:

```json
{
  "mcpServers": {
    "cypress": {
      "serverUrl": "http://localhost:3000/sse"
    }
  }
}
```

If your client supports streamable HTTP (check your client's documentation), you can also use:

```json
{
  "mcpServers": {
    "cypress": {
      "serverUrl": "http://localhost:3000/mcp"
    }
  }
}
```

## API Endpoints

The Cypress MCP server exposes the following endpoints:

- `/health` - Health check endpoint (responds with 200 OK if server is running)
- `/sse` - Server-Sent Events endpoint for MCP communication
- `/mcp` - Streamable HTTP endpoint for MCP communication (alternative transport)

## Environment Variables

- `OPENAI_API_KEY` - API key for OpenAI services (used for enhanced test generation)
- `HEADLESS` - Run Cypress in headless mode (default: false)
- `NODE_ENV` - Node environment (development, production, etc.)
- `PORT` - Port to run the server on (default: 3000)

## Development

### Project Structure

```
├── src/
│   ├── cli.js              # CLI entrypoint for stdin/stdout transport
│   ├── cli-server.js       # CLI entrypoint for HTTP transport
│   ├── server.ts           # HTTP server implementation
│   ├── connection.ts       # MCP connection management
│   ├── context.ts          # Test context management
│   ├── tools/
│   │   ├── tool.ts         # Base tool definitions
│   │   ├── navigate.ts     # Navigation tools
│   │   ├── element.ts      # Element interaction tools
│   │   ├── assertions.ts   # Assertion tools
│   │   ├── screenshot.ts   # Screenshot tools
│   │   ├── wait.ts         # Wait tools
│   │   ├── network.ts      # Network tools
│   │   └── ...
└── ...
```

### Extending the Server

To add new tools or functionality:

1. Create a new tool implementation in `src/tools/`
2. Register your tool in `src/tools.ts`
3. Build the project: `npm run build`
4. Test your changes

### Testing

Run the tests with:

```bash
npm test
```

## Troubleshooting

### Common Issues

#### Connection Issues

If your MCP client cannot connect to the server:

1. Ensure the server is running (`docker ps` or check your terminal)
2. Verify the correct port is exposed and not blocked by a firewall
3. Check your `mcp_config.json` is correctly configured
4. Make sure you're using the correct endpoint (/sse or /mcp)

#### Browser Crashes

If Cypress browser crashes:

1. Increase the Docker container's memory limits
2. Check for browser compatibility issues
3. Make sure HEADLESS is set to true in production environments

## License

MIT

## Additional Resources

- [Model Context Protocol (MCP) Documentation](https://github.com/anthropics/model-context-protocol)
- [Cypress Documentation](https://docs.cypress.io/)
- [Playwright MCP Server](https://github.com/microsoft/playwright-mcp)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

© 2025 Cypress MCP Server Contributors