# Riddle MCP Server

MCP server that wraps the [Riddle API](https://riddledc.com) for Claude Code integration. Take screenshots, run browser automation, and capture console logs + network HAR data.

## Installation

1. Clone this repo
2. Install dependencies: `npm install`
3. Add to your Claude Code MCP settings (`~/.claude.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "riddle": {
      "command": "node",
      "args": ["/path/to/riddle-mcp-server/index.js"],
      "env": {
        "RIDDLE_API_KEY": "rdc_live_your_key_here"
      }
    }
  }
}
```

4. Restart Claude Code

## Available Tools

### `riddle_screenshot`
Take a screenshot of any URL. Returns base64-encoded PNG.

```
riddle_screenshot(url: "https://example.com", device: "iphone")
```

Options:
- `url` (required): URL to screenshot
- `device`: "desktop" | "ipad" | "iphone"
- `width`, `height`: Custom viewport (if not using device preset)

### `riddle_batch_screenshot`
Screenshot multiple URLs at once.

```
riddle_batch_screenshot(urls: ["https://site.com", "https://site.com/page2"], device: "desktop")
```

### `riddle_automate`
Run a Playwright script, wait for completion, and get all artifacts including console logs and network HAR.

```
riddle_automate(
  url: "https://example.com",
  script: "await page.click('button'); await page.screenshot({path: 'result.png'});",
  device: "ipad"
)
```

Returns:
- Screenshots saved to `/tmp/`
- Console logs (errors, warnings, last 20 log entries)
- Network HAR summary (total requests, failed requests, last 10 requests)

### `riddle_run_script`
Run a Playwright script asynchronously. Returns job_id to check later.

```
riddle_run_script(
  url: "https://example.com",
  script: "await page.click('button'); await page.screenshot({path: 'result.png'});"
)
```

### `riddle_get_job`
Check status and get artifacts of an async job.

```
riddle_get_job(job_id: "job_abc123")
```

### `riddle_click_and_screenshot`
Simple automation: load URL, click a selector, take screenshot.

```
riddle_click_and_screenshot(url: "https://example.com", click: "button.start", wait_ms: 2000)
```

## Device Presets

| Device  | Width | Height |
|---------|-------|--------|
| desktop | 1280  | 720    |
| ipad    | 820   | 1180   |
| iphone  | 390   | 844    |

## Benefits

- No permission prompts - tools are pre-approved in Claude Code
- Direct image return - Claude can see screenshots immediately
- Console + Network capture - Debug issues without manual browser inspection
- Cleaner workflow - no bash/curl needed

## License

MIT