# app-store-screenshots-mcp

MCP server that turns **raw in-app screenshots** into **beautiful, store-ready marketing images** for the **iOS App Store** and **Google Play**.

## Creative split (same session)

| Who | Does what |
|-----|-----------|
| **Host AI agent (you)** | In **this session**: write titles/subtitles, generate backgrounds, generate clipart, choose layouts & alignment, pick brand colors |
| **This MCP server** | Device frames, composite layers, typography render, exact pixel export |

The server does **not** invent marketing art. Call `get_session_design_guide` first, generate assets with your image tools, then compose.

## Features

- **Session design guide** — prompts + plan for backgrounds, clipart, copy, alignment
- **AI clipart overlays** — transparent PNGs with position/rotate/opacity
- **AI-directed layout** — presets + `custom` with `devicePlacement` / `captionStyle`
- iPhone mockup + CSS Android frame
- Exact App Store / Play sizes, opaque PNG, batch + `manifest.json`

## Install

```bash
npm install
npx playwright install chromium
npm run build
```

### Grok (`~/.grok/config.toml`)

```toml
[mcp_servers.app-store-screenshots]
command = "node"
args = ["/absolute/path/to/app-store-screenshots-mcp/dist/index.js"]
startup_timeout_sec = 60
tool_timeout_sec = 300
```

## Tools

| Tool | Purpose |
|------|---------|
| `get_session_design_guide` | **Start here** — per-slide AI prompts, copy rules, layout plan |
| `list_export_sizes` | Size ids and dimensions |
| `list_layouts` | Layout templates including `custom` |
| `generate_screenshot` | Compose one slide |
| `generate_screenshot_set` | Compose 1–10 slides + manifest |

## Same-session agent workflow

1. **Guide** — `get_session_design_guide({ appName, features, styleDirection, brandColors, platform })`
2. **Copy** — write headline + optional subheadline per slide (from guide rules)
3. **Backgrounds** — image-gen one portrait BG per slide (guide `promptTemplate`; **no text/phone/UI**)
4. **Clipart** — image-gen transparent decorative PNGs; place with `clipart[]`
5. **Alignment** — pick layout or `custom` + `devicePlacement` / `captionStyle`
6. **Compose** — `generate_screenshot_set` with absolute paths
7. **Ship** — deliver numbered PNGs to the user

### Example compose payload

```json
{
  "platform": "ios",
  "sizes": ["ios-6.9"],
  "outputDir": "/tmp/store-shots",
  "brand": {
    "textColor": "#FFFFFF",
    "accentColor": "#A5B4FC",
    "fontFamily": "Inter, system-ui, sans-serif"
  },
  "slides": [
    {
      "appScreenshot": "/path/to/home.png",
      "backgroundImage": "/path/to/session/bg-01.png",
      "headline": "Track every\ncoffee you buy",
      "subheadline": "A home for every bag",
      "label": "Brew Log",
      "layout": "hero",
      "captionStyle": { "align": "center", "textShadow": true },
      "clipart": [
        {
          "path": "/path/to/session/clipart-01.png",
          "xPercent": 70,
          "yPercent": 16,
          "widthPercent": 24,
          "rotateDeg": -10,
          "opacity": 0.95
        }
      ]
    },
    {
      "appScreenshot": "/path/to/detail.png",
      "backgroundImage": "/path/to/session/bg-02.png",
      "headline": "Never waste\na great bag",
      "layout": "custom",
      "devicePlacement": {
        "widthPercent": 80,
        "leftPercent": 15,
        "bottomPercent": -8,
        "rotateDeg": 3
      },
      "captionStyle": {
        "position": "top",
        "align": "left",
        "offsetTopPercent": 6,
        "offsetXPercent": 8,
        "textShadow": true
      }
    }
  ]
}
```

## Export sizes

| Id | Platform | Pixels |
|----|----------|--------|
| `ios-6.9` (primary) | iOS | 1320×2868 |
| `ios-6.5` | iOS | 1284×2778 |
| `ios-6.3` | iOS | 1206×2622 |
| `ios-6.1` | iOS | 1125×2436 |
| `play-phone` (primary) | Android | 1080×1920 |
| `play-phone-tall` | Android | 1080×2340 |

## Development

```bash
npm test
npm run build
```

## License

MIT