Nx Cypress Code Gen MCP Server

A comprehensive Model Context Protocol (MCP) server that analyzes Nx monorepo applications to identify user journeys and generates production-ready Cypress E2E tests following industry best practices.

✨ Key Features

🔍 Advanced Nx Workspace Analysis

• Smart Application Discovery: Automatically detects and parses Nx applications across monorepos
• Deep Route Analysis: Extracts routing information from Angular, React, Vue, and Next.js applications
• Component Relationship Mapping: Maps components to routes, pages, and user interactions
• Dependency Graph Analysis: Understands application architecture and navigation flows

🛤️ Intelligent User Journey Detection

• AI-Powered Pattern Recognition: Identifies complex user flow patterns (authentication, e-commerce, content management, admin workflows)
• Navigation Flow Discovery: Analyzes inter-route navigation patterns and user behavior
• Journey Optimization: Creates efficient test paths covering maximum functionality
• Edge Case Identification: Discovers error states and boundary conditions

🧪 Enterprise-Grade Cypress Test Generation

• Production-Ready Tests: Generates comprehensive Cypress tests following official best practices
• Multiple Test Scenarios: Happy path, error handling, validation, accessibility, and performance tests
• Modern Selector Strategies: Uses data-test attributes and Testing Library patterns
• API-First Approach: Programmatic authentication and state management for faster, more reliable tests

🛠️ Advanced Configuration & Tooling

• Project-Specific Configs: Optimized Cypress configurations for different frameworks
• CI/CD Integration: Ready-made pipeline configurations for GitHub Actions, GitLab CI, and more
• Page Object Models: Generates maintainable page object patterns with method chaining
• Custom Commands: Provides reusable Cypress commands following best practices

🚀 Enhanced Capabilities

New MCP Tools

1. analyze-nx-app - Enhanced workspace analysis with deeper insights
2. generate-cypress-tests - Comprehensive test generation with multiple scenarios
3. generate-cypress-config ⭐ NEW - Project-specific configuration templates
4. generate-page-objects ⭐ NEW - Maintainable page object model generation

Best Practices Integration

• ✅ Element Selection: data-test attributes instead of brittle CSS selectors
• ✅ Test Organization: Independent, isolated tests that can run with .only
• ✅ Authentication: Programmatic login via API for 5x faster execution
• ✅ Network Handling: Smart waiting with cy.intercept() and aliases
• ✅ State Management: Database seeding and proper test isolation
• ✅ Error Handling: Comprehensive error scenarios and retry logic
• ✅ Accessibility: Built-in a11y testing with cypress-axe
• ✅ Performance: Optimized configurations for CI/CD environments

Installation & Setup

# Clone and install
git clone <repository-url>
cd nx-cypress-code-gen
npm install
npm run build

Quick Start

# Build the MCP server
npm run build

# The server will be available at ./build/index.js

Usage as MCP Server

This server is designed to work with VS Code Copilot in agent mode through the Model Context Protocol.

Configuration

Add the following to your Claude Desktop configuration or VS Code MCP settings:

{
  "mcpServers": {
    "nx-cypress-code-gen": {
      "command": "node",
      "args": ["/absolute/path/to/nx-cypress-code-gen/build/index.js"]
    }
  }
}

🔧 Available Tools

1. analyze-nx-app - Workspace Analysis

Analyzes an Nx monorepo application to identify user journeys and navigation patterns.

Parameters:

• workspacePath (string): Path to the Nx workspace root directory
• appName (string, optional): Specific application name to analyze

2. generate-cypress-tests - Enhanced Test Generation

Generates comprehensive Cypress E2E tests following best practices with multiple test scenarios.

Parameters:

• workspacePath (string): Path to the Nx workspace root directory
• appName (string): Application name to generate tests for
• journeyName (string, optional): Specific user journey to generate tests for

Features:

• ✅ Happy path testing with robust assertions
• ✅ Network error handling and retry logic
• ✅ Form validation and edge case testing
• ✅ Accessibility testing with cypress-axe
• ✅ API verification and state management

3. generate-cypress-config ⭐ NEW - Configuration Templates

Generates optimized Cypress configuration files for different project types and CI environments.

Parameters:

• projectType (enum): "angular" | "react" | "vue" | "next" | "generic"
• includePlugins (array, optional): ["accessibility", "coverage", "testing-library", "visual"]
• ciEnvironment (enum, optional): "github" | "gitlab" | "jenkins" | "azure" | "generic"

Features:

• ✅ Project-specific optimizations
• ✅ CI/CD pipeline configurations
• ✅ Performance tuning for different environments
• ✅ Plugin integration setup
• ✅ Browser-specific configurations

4. generate-page-objects ⭐ NEW - Page Object Models

Generates maintainable page object models following Cypress best practices.

Parameters:

• workspacePath (string): Path to the Nx workspace root directory
• appName (string): Application name to generate page objects for
• pageType (enum, optional): "auth" | "dashboard" | "ecommerce" | "admin" | "content" | "custom"

Features:

• ✅ Base page class with common functionality
• ✅ Method chaining for fluent API design
• ✅ Encapsulated selectors following DRY principles
• ✅ Built-in wait strategies and error handling
• ✅ Accessibility verification methods

📝 Usage Examples

Analyze the Nx workspace at /path/to/my-nx-workspace

2. generate-cypress-tests

Generates Cypress E2E tests based on identified user journeys.

Parameters:

• workspacePath (string): Path to the Nx workspace root directory
• appName (string): Application name to generate tests for
• journeyName (string, optional): Specific user journey to generate tests for

Example:

Generate Cypress tests for the "my-app" application in /path/to/my-nx-workspace

Example Output

Analysis Results

# Nx Application Analysis

## Applications Analyzed
- **my-frontend-app** (application)
  - Root: apps/my-frontend-app
  - Source: apps/my-frontend-app/src

## Routes Discovered
### my-frontend-app
- `/login` → LoginComponent
- `/dashboard` → DashboardComponent
- `/products` → ProductListComponent
- `/product/:id` → ProductDetailComponent

## User Journeys Identified
### Authentication Flow
User login and authentication process

**Journey Steps:**
1. Navigate to login page (navigate)
2. Enter credentials and submit (login)
3. Redirect to dashboard (navigate)

**Path:** /login → /dashboard

Generated Tests

describe("Authentication Flow - my-frontend-app", () => {
  beforeEach(() => {
    cy.visit("/login");
  });

  it("should complete user login and authentication process", () => {
    // Step 1: Navigate to login page
    cy.get('[data-cy="username"]').type("testuser");
    cy.get('[data-cy="password"]').type("testpass");
    cy.get('[data-cy="login-button"]').click();

    // Step 2: Redirect to dashboard
    cy.get('[data-cy="nav-dashboard"]').click();

    // Verify final state
    cy.url().should("include", "/dashboard");
    cy.get('[data-cy="success-indicator"]').should("be.visible");
  });
});

Supported Frameworks

• Angular: Full support for Angular routing and components
• React: Support for React Router and component analysis
• Vue: Basic support for Vue Router (experimental)

Architecture

Core Components

1. Workspace Parser: Analyzes Nx workspace structure and configuration
2. Route Extractor: Parses routing files and extracts route definitions
3. Journey Identifier: Uses pattern matching to identify common user flows
4. Test Generator: Creates comprehensive Cypress test suites
5. MCP Interface: Provides tools through Model Context Protocol

Journey Detection Patterns

The server recognizes common patterns:

• Authentication Flow: Login → Dashboard → Profile
• E-commerce Flow: Products → Product Detail → Cart → Checkout
• Content Management: Create → Edit → Publish
• User Registration: Register → Verify → Welcome

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
└── types/            # TypeScript type definitions

build/                # Compiled JavaScript output
cypress/              # Example Cypress tests

Building

npm run build

Development Mode

npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

ISC

Troubleshooting

Common Issues

1. "No Nx workspace found": Ensure the path contains an nx.json file
2. "No applications found": Check that your workspace has applications in apps/ directory
3. "No routes discovered": Verify your routing files follow standard conventions

Debug Mode

Set environment variable DEBUG=1 for verbose logging:

DEBUG=1 node build/index.js