shotframe

shotframe

Need App Store or Google Play screenshots for a store listing? shotframe hands the AppScreen API a set of screen layouts plus the image files they reference, and gives you back either a render job you can poll or a direct download link for the finished screenshots.

How a render flows:

• screens — the layouts, as JSON objects. Their structure is defined by the AppScreen API; shotframe passes them through untouched and cannot validate them for you.
• files — the images the layouts use. Each item names a file and carries exactly one source: a local path (the client reads the bytes off disk and encodes them; a leading ~/ expands to your home directory) or inline base64 (meant only for tiny synthetic test images). An unreadable path fails the call before any request is made.
• The reply preserves the API's own fields — a jobId for keyed/async renders or a download link for anonymous/inline ones, plus balance and cost when reported. Quota metadata the API reports is surfaced on the MCP result's _meta (quota, and balance / cost / upgradeUrl when present).

Poll a job with its jobId to learn its status and, when it is done, get a signed download URL. Signed URLs expire after about an hour; poll again to refresh one.

Configuration

The API key is optional — anonymous use works, capped by the service at 5 lifetime renders:

export APPSCREEN_API_KEY="your key"   # optional

Rendering spends your own AppScreen workspace credits; when they run out the API answers 402 and the tool reports it as an insufficient_credits error carrying the API's cost and balance text. shotframe itself holds no payment instrument.

Other environment variables:

• APPSCREEN_BASE_URL — API base URL (https://api.appscreen.co by default)
• APPSCREEN_MCP_CLIENT — sent as the X-MCP-Client header, identifying the calling client

CLI

npx @reneturcios/shotframe render_screenshots '{"screens":[{"device":"iphone"}], "files":[{"name":"icon.png","path":"~/shots/icon.png"}]}'
npx @reneturcios/shotframe get_render_status '{"job_id":"job-123"}'
npx @reneturcios/shotframe --version

Output is the API result body as JSON. Exit codes: 0 on success, 1 on a runtime error (including a validation failure, an unreadable file, or an upstream error), 2 on a usage error.

MCP server

npx -y @reneturcios/shotframe mcp

MCP client config:

{
  "mcpServers": {
    "shotframe": {
      "command": "npx",
      "args": ["-y", "@reneturcios/shotframe", "mcp"],
      "env": { "APPSCREEN_API_KEY": "your key" }
    }
  }
}

Tools

• render_screenshots — Render App Store and Google Play screenshots from screens (layout JSON) and image files. Returns a jobId for keyed/async renders or a download link for anonymous/inline renders. screens is required; files is optional.
• get_render_status — Poll a render job by jobId. Returns the status and a signed download URL when done. Signed URLs expire after about an hour; re-poll to refresh.

Docker

docker run -i -e APPSCREEN_API_KEY="your key" ghcr.io/cloudcorprecords/shotframe
docker run --rm ghcr.io/cloudcorprecords/shotframe get_render_status '{"job_id":"job-123"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch + temp files, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios