appshots-mcp

MCP server for generating ASO-optimized App Store screenshots. Generates up to 780 final images per app (39 locales x 5-10 screenshots x 1-2 devices).

AI logic lives in Claude Code; the server provides tools, rendering, and validation.

Why appshots-mcp?

Core problem: screenshot captions are disconnected from ASO keywords. Captions must reinforce keyword coverage, not be random marketing text. appshots-mcp solves this by integrating ASO keyword analysis directly into the screenshot generation pipeline.

Features

• 24 MCP tools for the complete screenshot pipeline
• 3 MCP prompts guiding app preparation, template design, and batch generation
• Simulator state management — pre-warm, seed UserDefaults, scroll/tap before capture
• Clean capture + Typst compositing — framebuffer screenshots with device frames added in templates
• Typst rendering — native RTL/CJK support, exact layout, sub-second renders
• OKLCH color space exclusively — perceptually uniform, no hex/RGB
• 39 ASO locales with fallback chains
• Granular regeneration — fix one screenshot without re-rendering all 780
• Keyword-aware captions — AI incorporates ASO keywords into every locale's captions
• Parallel rendering with configurable concurrency (4 concurrent by default)
• Auto font discovery from appshots/fonts/ directory
• Compilation timeout (30s) prevents infinite-loop templates
• Atomic file writes with advisory locking
• Path containment prevents symlink escape attacks

Quick Start

Installation

Homebrew (macOS/Linux):

brew install Murzav/tap/appshots-mcp

Cargo:

cargo install appshots-mcp

cargo-binstall (prebuilt binary):

cargo binstall appshots-mcp

Configuration

Claude Code:

claude mcp add appshots-mcp -- appshots-mcp --project-dir /path/to/your/app

Generic MCP client (stdio):

{
  "mcpServers": {
    "appshots-mcp": {
      "command": "appshots-mcp",
      "args": ["--project-dir", "/path/to/your/app"]
    }
  }
}

CLI Options

Usage

Typical Workflow

1. Prepare your app — use the prepare-app prompt to create ScreenshotMode enum in Swift
2. Design templates — use the design-template prompt to create Typst templates with preview_design
3. Generate all screenshots — use the generate-screenshots prompt for the full pipeline:

scan_project → analyze_keywords → plan_screens → save_captions (en-US)
→ translate captions (38 locales) → validate_layout
→ warm_simulator → seed_defaults → capture_screenshots
→ compose_screenshots → run_deliver

Tools

Capture & Setup

Discovery & Analysis

Strategy

Design & Rendering

Pipeline & Glossary

Prompts

Granular Regeneration

All rendering tools accept optional modes and locales filters. Omitting = process all.

"Fix screenshot 3"         → compose_screenshots(modes: [3])
"Fix German text on #5"    → compose_screenshots(modes: [5], locales: ["de-DE"])
"Re-capture stats screen"  → capture_screenshots(modes: [4])

Key Rules

• OKLCH Only: All colors use oklch(L%, C, Hdeg). No hex, RGB, or HSL.
• Template Resolution: templates/template-{mode}.typ -> templates/template.typ -> template.typ
• Locale Fallback: es-MX->es-ES, fr-CA->fr-FR, en-AU/CA/GB->en-US, pt-PT->pt-BR, zh-Hant->zh-Hans
• Required Sizes: iPhone 6.9" (1320x2868), iPad 13" (2064x2752). Max 10 per locale.

How Screenshot Modes Work

Each app screen is assigned a numeric mode (1-10). The app's ScreenshotMode Swift enum maps modes to specific UI states:

1. The app is launched with xcrun simctl launch --screenshot-N <udid> <bundle_id> where N is the mode number
2. ScreenshotDataProvider in the app checks ProcessInfo.processInfo.arguments for --screenshot-N and configures mock data accordingly
3. For complex state (e.g., streak counts, pro status), use seed_defaults to write UserDefaults before launching the app
4. capture_screenshots captures a clean framebuffer image per mode — no device bezels
5. compose_screenshots renders the final PNG via Typst, overlaying captions and optionally adding device frames

Project Directory Structure

project-root/
├── fastlane/
│   ├── metadata/{locale}/    ← keywords.txt, name.txt, subtitle.txt
│   └── screenshots/{locale}/ ← final output
├── appshots.json             ← project config (plan, captions, template)
├── appshots/
│   ├── template.typ          ← single template
│   ├── templates/            ← per-screen templates
│   ├── fonts/                ← custom fonts (.ttf, .otf, .woff2)
│   ├── captures/             ← simulator captures (clean framebuffer)
│   ├── previews/             ← design iteration previews
│   └── .seed-defaults.plist  ← temporary plist for defaults import
├── examples/                 ← reference Typst templates
└── glossary.json             ← shared with xcstrings-mcp

Device Frame Compositing

capture_screenshots produces clean framebuffer images without device bezels. Device frames are added during compose_screenshots via Typst templates. Three approaches:

1. Raw screenshot — no frame, just the capture with captions overlay
2. Rounded card — Typst rect(radius: ...) with clip: true to simulate device corners
3. PNG overlay — place a transparent device frame PNG on top of the screenshot (pixel-perfect Apple bezels)

See examples/template-with-frame.typ for a reference template demonstrating approach #2 with RTL support, auto-scaling text, and OKLCH colors.

Architecture

main.rs     → CLI (clap), tokio current_thread, stdio transport
server.rs   → #[tool_router] (24 tools) + #[prompt_router] (3 prompts)
tools/      → capture, scan, analyze, plan, captions, design, render,
              deliver, validate, glossary — all I/O via FileStore trait
service/    → metadata_parser, locale, keyword_matcher, font_resolver,
              template_resolver, typst_renderer, typst_world, validator,
              config_parser — pure functions, NO I/O
model/      → ProjectConfig, Caption, OklchColor, AsoLocale, Device,
              TemplateConfig — data types with serde + JsonSchema
io/         → FileStore trait + FsFileStore (atomic writes, flock)
error.rs    → AppShotsError enum (thiserror)
prompts.rs  → prompt content generators

Layer rule: server -> tools -> service -> model. Services have NO I/O.

Performance

Related

• MCP Protocol — Model Context Protocol specification
• xcstrings-mcp — Sister project for .xcstrings localization
• Typst — The typesetting system used for rendering
• fastlane — App Store automation

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Contributing

Contributions are welcome! Please open an issue or submit a PR.