npm package: @ratl/ratl-mcp
Description: HTTP bridge for RATL.ai MCP servers - enables Claude Desktop to connect to HTTP-based MCP servers
Author: RATL.ai
Latest version: 1.0.1

# RATL.ai MCP

**RATL.ai MCP** provides intelligent, workflow-oriented tools for AI-powered test generation and execution. Access **30+ MCP tools** for API testing, load testing, and web testing through any MCP-compatible client.

## What is RATL.ai MCP?

RATL.ai MCP (Model Context Protocol) server exposes comprehensive testing capabilities as MCP tools that AI assistants can use to:

- **Generate API Tests**: Automatically create pytest-based functional and E2E tests from your codebase
- **Generate Load Tests**: Automatically create Gatling-based performance tests
- **Generate Web Tests**: Automatically analyze URLs and generate web UI test scenarios
- **Execute Tests**: Run tests on cloud infrastructure and get detailed reports
- **Analyze Results**: Get AI-powered insights and recommendations

### Available Tools

**API Test Tools (10 tools):**
- Codebase analysis for API testing
- Test plan generation (E2E scenarios + functional tests)
- Pytest code generation
- Test execution and reporting
- Local test result onboarding

**Load Test Tools (15 tools):**
- Codebase analysis for load testing
- Test plan generation (end-to-end scenarios)
- Gatling code generation
- Load test execution on cloud infrastructure
- Performance analysis and optimization
- Test comparison and benchmarking

**Web Test Tools (6 tools):**
- Auto-generate test scenarios from URLs
- Review and approve test scenarios
- Execute web tests (webshot)
- Monitor test execution
- Get detailed test reports

### Workflows

**API Test Workflow:**
```
Codebase Analysis → Test Plan → Code Generation → Validation → Execution → Reports
```

**Load Test Workflow:**
```
Codebase Analysis → Test Plan → Gatling Code → Validation → URL Validation → Execution → Analysis
```

**Web Test Workflow:**
```
Auto-Generate Scenario → Review & Approve → Execute → Monitor → Reports
```

For complete workflow documentation, see [MCP.md](../MCP.md).

## MCP Server Endpoint

The RATL.ai MCP server is available at:
- **Production**: `https://api.rattlez0.de/public/api/v1/mcp`
- **Development**: `http://localhost:8000/api/v1/mcp` (if running locally)

## Supported MCP Clients

RATL.ai MCP works with any MCP-compatible client:

- **Cursor IDE** - Native HTTP/SSE support (no bridge needed)
- **Claude Desktop** - Requires bridge (see setup below)
- **Claude API** - Native HTTP support
- **OpenAI GPT Models** - Native HTTP support
- **Other MCP Clients** - Use HTTP transport if supported, or bridge for stdio-based clients

## Quick Start

### Step 1: Get Your API Key

1. Visit [ril.ratl.ai](https://ril.ratl.ai)
2. Navigate to **Settings** > **API Keys**
3. Create a new API key or copy an existing one

### Step 2: Configure Your MCP Client

#### Cursor IDE (Native HTTP Support)

1. Open **Cursor Settings** (Cmd/Ctrl + ,)
2. Navigate to **Features** > **MCP**
3. Click **+ Add New MCP Server**
4. Configure:
   - **Name**: `ratl.ai`
   - **Transport**: **Streamable HTTP** (or **SSE**)
   - **URL**: `https://api.rattlez0.de/public/api/v1/mcp`
   - **Headers**: Add `x-api-key` header with your API key
5. Click **Save**

#### Claude Desktop (Requires Bridge)

Claude Desktop currently only supports stdio-based MCP servers. Use the bridge to connect:

**Install the bridge:**

```bash
# Option 1: Using npx (Recommended - No Installation)
# Just use npx in configuration (see below)

# Option 2: Install globally
npm install -g @ratl/ratl-mcp

# Option 3: Direct download
# Download index.js from this repository
```

**Configure Claude Desktop:**

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration (using npx - recommended):**

```json
{
  "mcpServers": {
    "ratl.ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ratl/ratl-mcp@latest",
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}
```

**Configuration (using global installation):**

```json
{
  "mcpServers": {
    "ratl.ai": {
      "command": "ratl-mcp",
      "args": [
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}
```

**Configuration (using direct path):**

```json
{
  "mcpServers": {
    "ratl.ai": {
      "command": "node",
      "args": [
        "/path/to/mcp-bridge/index.js",
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}
```

**Restart Claude Desktop** after configuration.

#### Other MCP Clients

For clients that support HTTP-based MCP:

```json
{
  "mcpServers": {
    "ratl.ai": {
      "url": "https://api.rattlez0.de/public/api/v1/mcp",
      "transport": "sse",
      "headers": {
        "x-api-key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

For clients that only support stdio, use the bridge tool (see Claude Desktop setup above).

## Example Use Cases

### Creating API Tests

**You:** "Help me create API tests for the OTT API at https://ott.ratl.app"

**AI Assistant (using RATL.ai MCP tools):**
1. Analyzes your codebase/OpenAPI spec
2. Generates E2E test scenarios and functional test plan
3. Creates pytest test files
4. Validates the code
5. Executes tests and provides reports

### Creating Load Tests

**You:** "Generate load tests for my authentication flow"

**AI Assistant (using RATL.ai MCP tools):**
1. Analyzes your API endpoints
2. Creates a comprehensive end-to-end load test scenario
3. Generates Gatling Java code
4. Validates code and URL
5. Executes load test on cloud infrastructure
6. Provides performance analysis and recommendations

### Creating Web Tests

**You:** "Test the login page at https://example.com/login"

**AI Assistant (using RATL.ai MCP tools):**
1. Analyzes the URL and detects page elements (forms, buttons, links)
2. Auto-generates a test scenario with actions and assertions
3. Reviews and approves the generated scenario
4. Executes web test with screenshots and video recording
5. Provides detailed test reports with visual evidence

## What You Get

### API Testing
- **E2E Test Scenarios**: User journey tests that test complete workflows
- **Functional Tests**: Individual endpoint tests with comprehensive coverage
- **Automatic Code Generation**: AI generates pytest code from your API
- **Validation**: Automatic code validation before execution (mandatory)
- **Detailed Reports**: E2E and functional test reports with request/response details
- **Size Limit**: Total test file contents must be under 50 KB (strictly enforced)
- **Local Execution Support**: Onboard local test results to track in the platform

### Load Testing
- **End-to-End Scenarios**: Complete user flows tested under load
- **Gatling Code Generation**: Production-ready Gatling Java code
- **Cloud Execution**: Tests run on scalable cloud infrastructure
- **Performance Metrics**: Response times, throughput, error rates
- **AI Analysis**: Automated insights and optimization recommendations
- **URL Validation**: Automatic validation of baseUrl before execution (blocks localhost URLs)

### Web Testing
- **Auto-Generation**: Automatically analyzes URLs and generates test scenarios
- **Page Analysis**: Detects forms, buttons, links, and key UI elements
- **Visual Evidence**: Screenshots, GIFs, and video recordings of test execution
- **Inline Mode**: No filesystem access required - perfect for URL-based testing
- **Review Workflow**: Mandatory review step before execution to ensure quality

## Authentication

The MCP server supports **multiple authentication methods** for flexibility and security:

### Authentication Methods (Priority Order)

1. **HTTP Header: `x-api-key`** (Recommended for Cursor, Claude, and other HTTP clients)
2. **Session Token: `x-session-token`** (Recommended for workflow tools - valid for 1 hour)
3. **Parameter: `api_key`** (Backward compatibility - can be passed in tool arguments)

### Getting Started

1. **Get API Key**: From [ril.ratl.ai](https://ril.ratl.ai) Settings > API Keys
2. **Pass in Configuration**: 
   - For HTTP clients: Include `x-api-key` header
   - For bridge: Include `--api-key YOUR_API_KEY` in args
3. **Session Tokens** (Optional): Initialize with API key to get session token (valid for 1 hour)

### Session-Based Authentication (Recommended)

**Step 1: Initialize with API key**
```json
POST /api/v1/mcp
Headers: x-api-key: your-api-key
Body: {
  "method": "initialize",
  "params": {"api_key": "your-api-key"}
}
Response: {
  "result": {
    "sessionToken": "abc123...",
    "authenticated": true
  }
}
```

**Step 2: Use session token for subsequent calls**
```json
POST /api/v1/mcp
Headers: x-session-token: abc123...
Body: {
  "method": "tools/call",
  "params": {...}
}
```

**Benefits:**
- ✅ Authenticate once, reuse session token
- ✅ No need to pass API key in every tool call
- ✅ More secure (token expires after 1 hour)
- ✅ Better for workflow automation

**Note:** Session tokens require Redis for storage. If Redis is unavailable, session creation will fail gracefully, and you can continue using API key authentication directly (via `x-api-key` header or `api_key` parameter). The application will not crash if Redis is unavailable - it will simply operate without session support.

## Important Requirements

### Test Name Parameter (REQUIRED)

All test executions require a descriptive `testName` parameter:

- **Purpose**: Provides a meaningful name displayed in the execution dashboard
- **Required For**:
  - `ratl_execute_api_test_suite` - API test executions
  - `ratl_execute_load_test_suite` - Load test executions
  - `ratl_execute_web_test` - Web test executions
  - `ratl_onboard_api_test_local_results` - Local test result onboarding
- **Examples**:
  - API Tests: "E-commerce Platform - User Registration & Checkout", "API Test Suite - 5 E2E scenarios"
  - Load Tests: "Authentication Flow - 100 users/sec", "Payment Gateway - Spike Traffic"
  - Web Tests: "Login Page Test", "Checkout Flow Validation"

### Code Validation (MANDATORY)

- **API Tests**: Code validation is automatic before execution. Execution is blocked if validation fails.
- **Load Tests**: Code validation is automatic before execution. URL validation also occurs automatically. Execution is blocked if either validation fails.
- **Validation Tools**: Use `ratl_validate_api_test_pytest_code` or `ratl_validate_load_test_gatling_code` to validate code before execution.

### URL Validation (Load Tests)

- **Automatic**: URL validation occurs automatically after code validation passes
- **Blocks Localhost**: Localhost URLs are blocked (cloud infrastructure cannot reach localhost)
- **Tunneling Support**: Use tunneling services (ngrok, localtunnel, Cloudflare Tunnel) for local testing
- **Guidance Provided**: Detailed instructions provided when URL validation blocks execution

## Troubleshooting

### "command not found: npx" or "command not found: node"

**Solution:**
- Install Node.js: https://nodejs.org/
- Or use direct path to `index.js` in configuration

### "HTTP 401: Unauthorized"

**Solution:**
- Verify your API key is correct
- Check API key hasn't expired
- Get a new API key from [ril.ratl.ai](https://ril.ratl.ai)

### Bridge Not Working (Claude Desktop)

**Solution:**
1. Test bridge manually:
   ```bash
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
     npx @ratl/ratl-mcp@latest https://api.rattlez0.de/public/api/v1/mcp --api-key YOUR_KEY
   ```
2. Check client logs for errors
3. Verify file paths are absolute (not relative)

### Tools Not Appearing

**Solution:**
1. Restart your MCP client after configuration changes
2. Verify API key is correct
3. Check client logs for connection errors
4. For HTTP clients, verify the URL is accessible

### Session Token Not Working

**Solution:**
- Session tokens require Redis. If Redis is unavailable, use API key authentication directly
- Session tokens expire after 1 hour - re-authenticate if needed
- Use `x-api-key` header as an alternative to session tokens

## Bridge Tool (For stdio-based MCP Clients)

The bridge is a technical implementation that enables stdio-based MCP clients (like Claude Desktop) to connect to RATL.ai's HTTP-based MCP server:

1. Client sends JSON-RPC requests via stdin
2. Bridge forwards requests to RATL.ai MCP server over HTTP
3. Bridge receives responses and writes to stdout
4. Client reads responses and processes them

**Note:** When your MCP client adds native HTTP MCP support, the bridge will no longer be needed.

### Bridge Installation

```bash
# Install globally
npm install -g @ratl/ratl-mcp

# Or use npx (no installation)
npx @ratl/ratl-mcp@latest <url> [options]
```

### Bridge Command Line Options

```bash
ratl-mcp <url> [options]

Options:
  --api-key <key>        API key for authentication (sets x-api-key header)
  --header <name:value>  Additional header (can be used multiple times)
  --transport <type>    Transport type (default: http)
```

## Execution Management

All MCP-executed tests are automatically tracked in the platform:

- **Execution Dashboard**: View all test executions via REST API endpoints
- **Status Tracking**: Execution status automatically synced from backend services
- **Platform Identification**: Executions marked with `platform: "MCP"` (MCP client-initiated) or `platform: "ratl"` (frontend rerun)
- **Rerun Capability**: Execution payloads include full manifest and fileContents for rerunning tests
- **Local Execution Onboarding**: Track local test executions in the platform using `ratl_onboard_api_test_local_results`

For more details, see [MCP.md](../MCP.md) section on "MCP Execution Management".

## Documentation

- **Complete MCP Documentation**: See [MCP.md](../MCP.md) for detailed tool documentation, workflows, and examples
- **API Documentation**: See [README.md](../README.md) for REST API documentation
- **Website**: https://ratl.ai

## Support

- **Website**: https://ratl.ai
- **Get API Keys**: https://ril.ratl.ai (Settings > API Keys)
- **Documentation**: [MCP.md](../MCP.md) - Complete MCP server documentation

## License

MIT License - See LICENSE file for details.

---

**RATL.ai** - Intelligent testing tools powered by AI. Generate, execute, and analyze tests with ease.