# Screenshot Analyzer MCP

> AI-powered screenshot analysis for UI/UX issues using GPT-5.2

A Model Context Protocol (MCP) server that acts as "eyes" for AI coding assistants, analyzing app screenshots to identify UI/UX problems, compare designs with implementations, and provide actionable fixes.

## Features

- **Single/Multi Screenshot Analysis** - Analyze 1-10 screenshots at once
- **Batch Analysis** - Process entire folders with automatic batching
- **Design Comparison** - Compare design mockups vs actual screenshots
- **Fast Mode** - Quick scans with gpt-4o-mini at lower cost
- **Report History** - Store and retrieve past analysis reports
- **Concurrent Loading** - Parallel URL fetching (10x faster)
- **Auto Retry** - Exponential backoff for rate limits

## Requirements

- Python 3.10+
- OpenAI API key (with GPT-5.2 or GPT-4o access)
- Claude Code CLI (for MCP integration)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/YOUR_USERNAME/screenshot-mcp.git
cd screenshot-mcp
```

### 2. Install Dependencies

```bash
pip install mcp httpx pillow
```

Or with requirements.txt:

```bash
pip install -r requirements.txt
```

### 3. Add to Claude Code

Add to your global settings (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "screenshot-analyzer": {
      "command": "python3",
      "args": ["/path/to/screenshot-mcp/server.py"]
    }
  }
}
```

Or use Claude CLI:

```bash
claude mcp add screenshot-analyzer python3 /path/to/screenshot-mcp/server.py
```

### 4. Set Your API Key

In Claude Code, run:

```
Use set_api_key tool with your OpenAI API key
```

Or create `config.json` in the same directory:

```json
{
  "api_key": "sk-proj-your-api-key-here",
  "default_reasoning_effort": "high"
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `analyze_screenshots` | Analyze screenshots for UI/UX issues |
| `batch_analyze` | Batch analyze folder or multiple files |
| `compare_designs` | Compare design mockup vs implementation |
| `set_fast_mode` | Toggle fast/precise mode |
| `get_report_history` | List recent analysis reports |
| `get_report_by_id` | Retrieve a specific report |
| `get_last_report` | Get the most recent report |
| `set_api_key` | Configure OpenAI API key |
| `set_reasoning_effort` | Set reasoning level (none/low/medium/high/xhigh) |
| `get_config` | View current configuration |

## Usage Examples

### Basic Analysis

```python
analyze_screenshots(
    platform="ios",
    image_paths=["/path/to/screenshot.png"],
    app_description="E-commerce app for fashion retail"
)
```

### Batch Analysis

```python
batch_analyze(
    platform="android",
    folder_path="/path/to/screenshots",
    batch_size=5,
    generate_summary=True
)
```

### Design Comparison

```python
compare_designs(
    design_path="/path/to/figma-export.png",
    screenshot_path="/path/to/actual-screenshot.png",
    platform="ios",
    tolerance="normal"  # strict | normal | relaxed
)
```

### Fast Mode (Lower Cost)

```python
# Enable fast mode (uses gpt-4o-mini)
set_fast_mode(enabled=True)

# Run analysis at ~80% lower cost
analyze_screenshots(platform="web", image_paths=[...])

# Disable for detailed analysis
set_fast_mode(enabled=False)
```

## Output Format

### Analysis Report

```markdown
## Summary
[X critical, Y major, Z minor issues found]

## Critical Issues (Must Fix)
- [Location]: [Problem] → [Fix]

## Major Issues
- [Location]: [Problem] → [Fix]

## Minor Issues
- [Location]: [Problem] → [Fix]

## Suggestions
- [Enhancement idea]
```

### Comparison Report

```markdown
## Consistency Score: XX/100

## Critical Differences (Design Intent Broken)
- [Element]: Design [value] → Actual [value]

## Major Differences (Noticeable)
- [Element]: Design [value] → Actual [value]

## Minor Differences (Acceptable)
- [Element]: Design [value] → Actual [value]
```

## Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `api_key` | (required) | OpenAI API key |
| `default_model` | `gpt-5.2` | Model for analysis |
| `default_reasoning_effort` | `high` | Reasoning level |
| `max_image_size` | `1024` | Max dimension in pixels |
| `jpeg_quality` | `85` | Compression quality |
| `fast_mode` | `false` | Use faster/cheaper model |
| `fast_mode_model` | `gpt-4o-mini` | Model for fast mode |
| `fast_mode_reasoning` | `low` | Reasoning in fast mode |

## Tolerance Levels (Design Comparison)

| Level | Description |
|-------|-------------|
| `strict` | Flag all differences, even 1px variations |
| `normal` | Flag noticeable differences (2-4px, visible color mismatches) |
| `relaxed` | Only flag significant differences affecting UX |

## Technical Details

- Uses OpenAI GPT-5.2 Responses API (`/v1/responses`)
- Automatic image compression (max 1024px, JPEG 85%)
- Concurrent URL loading with `asyncio.gather()`
- Exponential backoff retry (429/5xx errors)
- Report history cache (last 20 reports)
- Supports PNG, JPEG, GIF, WebP, BMP formats
- **Auto-repair corrupted images** (e.g., Android screencap with text header)

## Platform Support

| Platform | Guidelines |
|----------|------------|
| `ios` | Human Interface Guidelines (HIG) |
| `android` | Material Design |
| `web` | WCAG, modern web standards |
| `desktop` | Platform-specific guidelines |

## Troubleshooting

### "API key not configured"

Run `set_api_key` tool or create `config.json` with your key.

### "Request timed out"

- Reduce number of images per request
- Enable fast mode for quicker responses
- Use `batch_analyze` for many images

### "429 Rate Limit"

The server automatically retries with exponential backoff. If persistent, wait a few minutes or upgrade your OpenAI plan.

### Corrupted Images (Android screencap)

If your screenshots have text/warnings embedded at the beginning (common with Android `adb exec-out screencap`), the MCP will **automatically repair** them by finding the actual image data.

To prevent this in your capture scripts:

```bash
# Redirect stderr to suppress warnings
adb exec-out screencap -p 2>/dev/null > screenshot.png

# Or specify display ID explicitly
adb exec-out screencap -d 0 -p > screenshot.png
```

## License

MIT License - see LICENSE file for details.

## Contributing

Pull requests welcome! Please ensure:

1. Code follows existing style
2. Add tests for new features
3. Update README for new tools

---

Made with Claude Code