# aiTest MCP Server

> **AI-native browser testing, directly from your coding agent.**

aiTest MCP Server connects AI coding tools (Cursor, Claude Desktop, Copilot) to the [aiTest](https://aitest.dev) cloud testing platform. Describe what you want to test in plain English, and the AI engine handles the rest — planning, browser execution, root-cause analysis, and UX insights.

## Quick Start

```bash
npx @aitest/mcp
```

### Prerequisites

- **Node.js** >= 18
- An **aiTest API key** ([get one here](https://aitest.dev)) or run against a local dev server
- One of: Cursor, Claude Desktop, or any MCP-compatible client

## Configuration

Set these environment variables (or use your MCP client's config):

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `AITEST_API_KEY` | ✅ | — | Your aiTest API key (`aitest_sk_...`) |
| `AITEST_API_URL` | — | `http://localhost:8000/api/v1` | aiTest REST API base URL |

### Cursor Setup

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "aitest": {
      "command": "npx",
      "args": ["@aitest/mcp"],
      "env": {
        "AITEST_API_KEY": "aitest_sk_your_key_here"
      }
    }
  }
}
```

### Claude Desktop Setup

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aitest": {
      "command": "npx",
      "args": ["@aitest/mcp"],
      "env": {
        "AITEST_API_KEY": "aitest_sk_your_key_here"
      }
    }
  }
}
```

## Tools

### `aitest_run`

Submit a new browser test job.

```
Parameters:
  url          — Target URL to test
  description  — What to test (natural language)
  credentials? — Login credentials { email, password }
  options?     — Test config { max_retries, screenshot_mode, timeout_seconds }

Returns: job_id + estimated completion time
```

Example: *"Test that the login page accepts valid credentials, rejects invalid ones, and shows appropriate error messages."*

### `aitest_status`

Check the current status of a test job.

```
Parameters:
  job_id — The job ID from aitest_run

Returns: status (created/queued/executing/completed/failed) + timing
```

### `aitest_report`

Get the full test report (only available when job is completed).

```
Parameters:
  job_id — The job ID from aitest_run

Returns: Summary, step-by-step results, root-cause analysis, UX insights
```

## Development

```bash
# Clone
git clone git@github.com:rongxianzhuo/aitest-mcp.git
cd aitest-mcp

# Install
npm install

# Build
npm run build

# Run locally (against local aiTest API)
AITEST_API_URL=http://localhost:8000/api/v1 \
AITEST_API_KEY=aitest_sk_test \
  node dist/index.js
```

## Architecture

```
AI Coding Agent (Cursor / Claude)
        │
        │  MCP Protocol (stdio)
        ▼
  aitest-mcp (thin proxy)
        │
        │  REST HTTPS
        ▼
  aiTest Cloud Platform
        │
        ├── FastAPI Server (Railway)
        ├── AI Engine (test planning + agent loop + analysis)
        ├── Supabase (auth + db + storage)
        └── Browser Sandbox (Playwright / Browserbase)
```

The MCP server is intentionally **thin** — zero AI logic, zero browser automation. It translates MCP tool calls into REST API requests and formats the responses for LLM consumption.

## License

MIT — see [LICENSE](./LICENSE)