screenshot-aso

Deterministic App Store screenshot composition as an MCP server.

This package gives your agent a stable rendering backend with persisted state so screenshot sets stay consistent across runs.

What It Is

• An MCP server (stdio) distributed via npm
• A deterministic screenshot renderer (no AI image generation)
• A simple persisted state layer for consistency

Core Capabilities

• screenshots.validate_state
  • Validates an existing screenshot-config.json file at explicit statePath
• screenshots.render_generic
  • Renders one screenshot with fallback resolution from state and writes output under screenshots-asc
• screenshots.render_batch
  • Renders many screenshots from a config file and writes outputs under screenshots-asc
• screenshots.how_to_use_tools (resource)
  • Agent-facing workflow and quality guidance
• screenshots.discover_benefits_and_brand_color (prompt)
  • Agent-facing discovery prompt scaffold

What It Does Not Do

• It does not run LLM discovery itself.
• Discovery is done by the client agent.
• The server stores and applies decisions consistently.

Install

Use without global install:

npx -y screenshot-aso

Or install globally:

npm install -g screenshot-aso

Then run:

screenshot-aso

Use In an MCP Client

Example stdio config:

{
  "mcpServers": {
    "screenshot-aso": {
      "command": "npx",
      "args": ["-y", "screenshot-aso"]
    }
  }
}

State and Consistency

Required state path:

• You must provide statePath on related MCP calls.
• statePath must be a path ending with screenshot-config.json.
• The server does not auto-discover project roots or default state locations.

State includes:

• brandColor (#RRGGBB)
• benefits (headline-ready textLines)
• defaults (backgroundColor, fixed size: "6.9", frameColor)
• breakouts (array of per-screenshot breakout entries identified by screenshotKey; latest matching entry wins)

Important behavior:

• render_* tools do not modify screenshot-config.json.
• agents/users edit screenshot-config.json directly, then run screenshots.validate_state.
• Render outputs are written under:
  • <dirname(statePath)>/screenshots-asc

Typical Agent Flow

1. Choose a project-specific statePath ending with screenshot-config.json.
2. Read/edit that screenshot-config.json directly.
3. Run screenshots.validate_state with the same statePath.
4. If brandColor or benefits are missing, infer and add them in screenshot-config.json.
5. Render via screenshots.render_generic or screenshots.render_batch with same statePath.
6. For breakout tuning, iterate render_generic and persist accepted breakout values by editing screenshot-config.json.

Render Rules (screenshots.render_generic)

Input requirements:

• statePath is required
• inputPath image should be 1320x2868, or very close in aspect ratio (near 0.460251) to prevent content cutoff from cover-cropping
• Provide exactly one text source:
  • textLines, or
  • benefitId (resolved from state)

Resolution order:

• background color:
  1. input.backgroundColor
  2. state.defaults.backgroundColor
  3. state.brandColor
• size:
  • fixed to 6.9 (if input.size is provided, it must be 6.9)
• frame color:
  1. input.frameColor
  2. state.defaults.frameColor
• breakout:
  1. input.breakout
  2. state.breakouts[screenshotKey]
  3. none

Breakout coordinate modes:

• rectPx: crop in raw input screenshot pixels (x,y,width,height), with origin at the input image top-left before cover-cropping
• rectNorm: normalized crop (0..1) over the visible phone-screen area in the frame, with origin at the phone-screen top-left (x=0,y=0) and bottom-right at (x=1,y=1)
• when input aspect ratio differs, renderer maps coordinates through cover-cropping and clamps final source pixels to image bounds

Output behavior:

• render_generic writes to <dirname(statePath)>/screenshots-asc
• output file name is <inputBase>-generic.png

Batch Config (screenshots.render_batch)

screenshots.render_batch accepts a configPath pointing to JSON:

{
  "shots": [
    {
      "input": "raw/shot-1.png",
      "textLines": [{ "text": "TRACK CARD PRICES" }],
      "bg": "#07163F",
      "frameColor": "natural",
      "breakout": {
        "rectNorm": { "x": 0.05, "y": 0.18, "width": 0.9, "height": 0.2 },
        "edgeOverflow": 0.08
      }
    }
  ]
}

render_batch also requires statePath; generated outputs are written to <dirname(statePath)>/screenshots-asc. Output files are named as <NN>-<inputBase>.png (for example 01-home.png). Each shots[].input image should be 1320x2868, or very close in aspect ratio.

Contributing

For local development and contribution workflow, see CONTRIBUTING.md.