shotframe

shotframe

需要用于商店列表的 App Store 或 Google Play 截图？shotframe 会将一组屏幕布局及其引用的图像文件交给 AppScreen API，并返回可供轮询的渲染任务，或已完成截图的直接下载链接。

渲染流程：

• screens — 布局，以 JSON 对象表示。其结构由 AppScreen API 定义；shotframe 会原样传递这些对象，无法替你验证。
• files — 布局使用的图像。每项指定一个文件，并且恰好包含一个来源：本地 path（客户端会读取磁盘上的字节并对其编码；开头的 ~/ 会展开为你的主目录），或内联 base64（仅用于极小的合成测试图像）。如果路径无法读取，调用会在发出任何请求前失败。
• 回复会保留 API 自身的字段——带密钥的／异步渲染会返回 jobId，匿名／内联渲染会返回下载链接；API 有报告时还会附带 balance 和 cost。API 报告的配额元数据会显示在 MCP 结果的 _meta 中（quota，以及存在时的 balance／cost／upgradeUrl）。

使用 jobId 轮询任务，以查看其状态，并在任务完成时获取签名下载 URL。签名 URL 约一小时后过期；再次轮询即可刷新。

配置

API 密钥是可选的——匿名使用也可行，但服务会将终身渲染次数限制为 5 次：

export APPSCREEN_API_KEY="your key"   # optional

渲染会消耗你自己的 AppScreen 工作区点数；点数用完后，API 会返回 402，工具会将其报告为 insufficient_credits 错误，并附带 API 返回的费用和余额文本。shotframe 本身不持有任何支付工具。

其他环境变量：

• APPSCREEN_BASE_URL — API 基础 URL （默认值为 https://api.appscreen.co）
• APPSCREEN_MCP_CLIENT — 作为 X-MCP-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

输出是 API 响应正文的 JSON。退出代码：成功时为 0，运行时错误（包括验证失败、文件无法读取或上游错误）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/shotframe mcp

MCP 客户端配置：

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

工具

• render_screenshots — 根据屏幕（布局 JSON）和图像文件渲染 App Store 与 Google Play 截图。带密钥的／异步渲染会返回 jobId，匿名／内联渲染会返回下载链接。screens 为必填项；files 为可选项。
• get_render_status — 按 jobId 轮询渲染任务。返回任务状态，并在完成后提供签名下载 URL。签名 URL 约一小时后过期；再次轮询即可刷新。

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"}'

开发

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

许可证

MIT — 版权所有 (c) 2026 Rene Turcios