# QA Testing MCP Server

An AI-driven testing and QA MCP (Model Context Protocol) server that enables AI agents like Claude, Claude Code, or Cursor to perform comprehensive web application testing without requiring API keys.

## Features

- **Visual Testing**: Screenshot capture, responsive design analysis, layout consistency checks
- **Functional Testing**: Form validation, link integrity, interactive element testing, navigation analysis
- **Performance Testing**: Core Web Vitals measurement, resource analysis, optimization opportunities
- **Accessibility Testing**: WCAG compliance (A, AA, AAA), color contrast, ARIA validation
- **SEO Analysis**: Meta tags, heading structure, content analysis, technical SEO
- **Report Generation**: Comprehensive Markdown reports with prioritized recommendations

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        User (Cursor/Claude)                     │
│                   "Test https://example.com"                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      QA Testing MCP Server                      │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│  │   Visual    │ │ Functional  │ │ Performance │ │Accessibility│ │
│  │   Testing   │ │   Testing   │ │   Testing   │ │  Testing   │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │
│  │    SEO      │ │   Report    │ │    Full Test Suite Runner   │ │
│  │  Analysis   │ │  Generator  │ │                             │ │
│  └─────────────┘ └─────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    chrome-devtools-mcp                          │
│            (Browser automation & inspection)                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Chrome Browser                            │
│                    (Web application under test)                 │
└─────────────────────────────────────────────────────────────────┘
```

## Prerequisites

- **Node.js** v22.12.0 or newer
- **npm** (comes with Node.js)
- **Chrome** browser (stable, beta, or canary)
- **Cursor** IDE or **Claude** with MCP support

## Installation

### 1. Clone and Build

```bash
# Clone the repository
git clone <repository-url>
cd emerge

# Install dependencies
npm install

# Build the project
npm run build
```

### 2. Configure MCP Servers

Add the following to your MCP client configuration:

**For Cursor** (Settings → MCP → Add Server):

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"]
    },
    "qa-testing": {
      "command": "node",
      "args": ["/absolute/path/to/emerge/dist/index.js"]
    }
  }
}
```

**For Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"]
    },
    "qa-testing": {
      "command": "node",
      "args": ["/absolute/path/to/emerge/dist/index.js"]
    }
  }
}
```

### 3. Verify Installation

After configuring, restart your MCP client and verify the tools are available:

```
List all available MCP tools
```

You should see tools like `run_visual_test`, `run_performance_test`, `run_full_test`, etc.

## Usage

### Quick Start

Simply ask the AI to test a website:

```
Test https://example.com and generate a full QA report
```

### Available Tools

| Tool | Description |
|------|-------------|
| `run_visual_test` | Screenshots, viewport analysis, layout checks |
| `run_functional_test` | Forms, links, interactions, navigation |
| `run_performance_test` | Core Web Vitals, resource metrics |
| `run_accessibility_test` | WCAG compliance, ARIA, contrast |
| `run_seo_test` | Meta tags, headings, technical SEO |
| `run_full_test` | All tests + comprehensive report |
| `generate_report` | Compile results into Markdown report |

### Example Prompts

**Full Test Suite:**
```
Run a comprehensive test on https://mywebsite.com including visual, functional, performance, accessibility, and SEO analysis. Generate a detailed report.
```

**Specific Testing:**
```
Check the accessibility of https://mywebsite.com against WCAG 2.1 Level AA standards.
```

```
Analyze the performance of https://mywebsite.com - measure Core Web Vitals and identify optimization opportunities.
```

```
Test the mobile responsiveness of https://mywebsite.com at 375px, 768px, and 1440px viewports.
```

**Combined with chrome-devtools-mcp:**
```
Navigate to https://mywebsite.com, take screenshots at mobile and desktop sizes, then run a performance trace and accessibility check. Generate a report with all findings.
```

See [sample-prompts/test-prompts.md](sample-prompts/test-prompts.md) for more example prompts.

## Report Structure

Generated reports include:

```markdown
# Web Application Test Report

## Executive Summary
- Overall score and status
- Test coverage
- Issues overview (critical, major, minor)
- Key highlights

## Visual Testing Results
- Viewports tested
- Layout issues
- Responsiveness checks

## Functional Testing Results
- Forms analysis
- Links analysis
- Interactive elements
- Navigation structure

## Performance Testing Results
- Core Web Vitals
- Resource metrics
- Optimization opportunities

## Accessibility Testing Results
- WCAG compliance level
- Violations found
- ARIA usage
- Color contrast

## SEO Analysis Results
- Meta tags
- Heading structure
- Content analysis
- Technical SEO

## Recommendations
- High priority
- Medium priority
- Low priority

## Raw Data
- Complete JSON data (collapsible)
```

## Chrome DevTools MCP Options

The chrome-devtools-mcp server supports various configuration options:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--headless=true",           // Run headless for CI/CD
        "--isolated=true",           // Use temporary profile
        "--channel=canary"           // Use Chrome Canary
      ]
    }
  }
}
```

**Connect to Running Chrome:**

```bash
# Start Chrome with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile
```

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode (development)
npm run dev

# Run tests
npm test
```

## Project Structure

```
emerge/
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── README.md                 # This file
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── tools/
│   │   ├── index.ts          # Tool exports
│   │   ├── visual-test.ts    # Visual testing
│   │   ├── functional-test.ts# Functional testing
│   │   ├── performance-test.ts# Performance testing
│   │   ├── accessibility-test.ts# Accessibility testing
│   │   └── seo-test.ts       # SEO analysis
│   ├── report/
│   │   ├── generator.ts      # Report generation
│   │   └── templates.ts      # Markdown templates
│   └── types/
│       └── index.ts          # TypeScript types
├── prompts/
│   └── test-prompts.md       # Example prompts
├── mcp-config.example.json   # MCP configuration example
└── cursor-mcp-settings.json  # Cursor-specific config
```

## How It Works

1. **User Input**: You provide a URL and testing scope through Cursor or Claude
2. **AI Processing**: The AI interprets your request and calls the appropriate testing tools
3. **Browser Automation**: chrome-devtools-mcp controls Chrome to load pages and gather data
4. **Analysis**: Each tool analyzes specific aspects (visual, performance, etc.)
5. **Report Generation**: Results are compiled into a comprehensive Markdown report
6. **Recommendations**: Prioritized suggestions for improvement

## Security Considerations

- The chrome-devtools-mcp server exposes browser content to MCP clients
- Avoid testing pages with sensitive information during sessions
- Use `--isolated=true` for temporary profiles that clear after testing
- Be cautious with `--remote-debugging-port` as it opens browser control

## Limitations

- Real-time metrics require actual browser automation via chrome-devtools-mcp
- Some tests provide guidance for AI to execute rather than direct measurements
- Performance metrics are most accurate with multiple test runs
- Accessibility testing should be complemented with manual review

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## License

MIT License - see LICENSE file for details.

## Resources

- [Chrome DevTools MCP](https://github.com/AiCodeLabs/chrome-devtools-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Cursor Editor](https://cursor.com/)
- [WCAG Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)
- [Core Web Vitals](https://web.dev/vitals/)