# @shiplightai/mcp

UI automation MCP for agentic development workflows. Lets AI coding agents (Claude Code, Cursor, Windsurf, etc.) verify the UI changes they make — closing the build-verify loop automatically. Every interaction is captured as a human-readable step, producing rerunnable regression tests.

## Quick Start

### Claude Code

```bash
claude mcp add shiplight -e PWDEBUG=console -- npx -y @shiplightai/mcp@latest
```

### Cursor / Windsurf / Other MCP Clients

Add to your MCP config (e.g., `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"]
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `PWDEBUG` | Yes | Must be set to `console`. Enables Playwright semantic locator generation (e.g., `getByRole`, `getByTestId`) for action entities. Without this, only XPath locators are available. |
| `ANTHROPIC_API_KEY` | One AI key required | Anthropic API key (for Claude models) |
| `GOOGLE_API_KEY` | One AI key required | Google AI API key (for Gemini models) |
| `SHIPLIGHT_API_TOKEN` | No | Shiplight cloud API token (enables cloud features) |

At least one AI API key is needed for the test execution agent. The model is auto-detected from the key (`ANTHROPIC_API_KEY` → `claude-haiku-4-5`, `GOOGLE_API_KEY` → `gemini-2.5-pro`).

Pass environment variables through your MCP config:

```json
{
  "mcpServers": {
    "shiplight": {
      "command": "npx",
      "args": ["-y", "@shiplightai/mcp@latest"],
      "env": {
        "PWDEBUG": "console",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

The server resolves environment variables in this order:

1. Variables passed explicitly by your MCP client config
2. Inherited host environment variables
3. A `.env` file in the current working directory where the MCP server starts

Existing environment variables are never overridden by `.env`, so project-local `.env` values act as a fallback.

## What It Does

Once connected, your AI coding agent can:

- **Verify its own UI changes** — Open pages, interact with elements, and assert visual conditions using AI ("Verify the success message is displayed")
- **Debug UI issues** — Inspect console errors and network failures directly from the browser session
- **Generate regression tests** — Every action is captured as a human-readable step, so sessions can be exported as `.test.yaml` files for fast, deterministic replay
- **Sync to the cloud** — Manage test cases on Shiplight's cloud platform for team-wide regression coverage (automatically enabled when `SHIPLIGHT_API_TOKEN` is set)
- **Attach to existing Chrome tabs** — Control your existing Chrome tabs via the Shiplight AI extension without recreating login state or complex setups

## Links

- [Shiplight](https://shiplight.ai)
- [shiplightai npm package](https://www.npmjs.com/package/shiplightai) — Playwright plugin for running `.test.yaml` files locally
