storeshots-mcp

storeshots-mcp

从命令行生成 App Store 和 Google Play 截图，或者让你的 AI 编码 Agent 来完成。

storeshots 将原始应用截图转换为成品商店展示视觉素材——设备外框、以卖点为导向的标题、品牌背景，以及 iOS 和 Android 的精确商店尺寸。在一个 storeshots.json 中描述你的整个商店列表，运行 storeshots build，即可获得所有平台、所有语言的成品。你的 AI Agent（或你自己）负责撰写和翻译文案；storeshots 负责渲染像素。它首先是一个 CLI，同时为没有 shell 的 Agent 提供 MCP 服务。无需设计工具，无需订阅，无需 API 密钥。

_{来自两款已发布应用的真实截图：bombo（面板 1–3）和 Studio Zero（面板 4）。面板 3 是 Android 预设，带有土耳其语标题，使用符合区域设置的 İ 和 Ğ 大写形式。}

---

核心理念

商店截图是两项伪装成一项的工作。一项是创意工作（说什么、哪个屏幕展示哪个功能、如何用六种语言表达），另一项是制作工作（外框、排版、精确像素尺寸、无 alpha 通道）。设计工具让你两项都手动完成；截图 SaaS 则将制作工作锁在订阅之后。

storeshots-mcp 将两者拆分，并把每项交给最擅长的一方：

你的 AI Agent 决定	storeshots 渲染
展示哪些屏幕	精确比例的设备外框
每个屏幕的标题	排版、对比度和布局
地道的翻译	每种语言的正确大小写（土耳其语 İ、德语 ß）
品牌颜色和顺序	精确商店尺寸的确定性 PNG

由于渲染路径是纯本地且确定性的，相同的输入总是产生相同的像素——没有模型参与，也不会向任何地方上传任何内容。

快速开始

npx storeshots init --langs en,tr --bg "#E31837"   # finds ./screenshots, writes storeshots.json
# replace the TODO headlines in storeshots.json
npx storeshots build --watch                       # renders everything, re-renders on save

init 会在如下配置中列出你的原始截图（来自 screenshots/、raw-shots/、raw/、shots/ 或 fastlane/screenshots/，或 --screens <dir>）：

{
  "background": "#E31837",
  "presets": ["ios-phone", "android-phone"],
  "languages": ["en", "tr"],
  "outputDir": "output",
  "screens": [
    { "screenshot": "screenshots/home.png",
      "copy": { "en": ["Track", "your daily mood"], "tr": ["İzle", "günlük ruh halini"] } },
    { "screenshot": "screenshots/stats.png", "variant": "tilted",
      "copy": { "en": ["Discover", "weekly insights"], "tr": ["Keşfet", "haftalık içgörüler"] } }
  ],
  "featureGraphic": { "screen": 1 },   // optional: Play Store 1024 × 500 header
  "showcase": true                     // optional: one preview strip per set
}

build 会渲染每个屏幕 × 预设 × 语言：

output/
  en/ios-phone/en_01.png … en_06.png
  en/android-phone/en_01.png …
  en/play-feature-graphic/en_feature.png
  tr/ios-phone/tr_01.png …
  showcase/en_ios-phone.png …

渲染是确定性的，因此 build 只会重绘发生变化的内容：编辑一个土耳其语标题，只会重新渲染那个文件。删除一个屏幕，其旧文件也会被移除。每个输出在写入之前都会根据其所属商店的规则进行检查。

如果你更愿意输入 storeshots 而不是 npx storeshots，可以用 npm i -g storeshots-mcp 全局安装。

命令

命令	作用
storeshots init	从原始截图的文件夹创建 storeshots.json，并向 AGENTS.md / CLAUDE.md 添加 storeshots 部分
storeshots build	渲染整个配置。--watch、--lang tr、--preset ios-phone、--dry-run、--force、--jobs 4
storeshots compose	通过参数渲染单张截图，无需配置
storeshots showcase	将图片或文件夹拼接成一条预览长图
storeshots validate	按商店规则检查文件或整个文件夹（失败时以 1 退出，因此适合 CI）
storeshots presets	列出预设及其确切尺寸

首次成功构建后，storeshots 会询问一次是否愿意在 GitHub 上为其加星。它在 CI 中从不询问；设置 STORESHOTS_NO_STAR=1 可将其关闭。每条命令都支持 --json 以输出机器可读结果，支持 --help 查看详情。退出码：0 正常，1 渲染或验证失败，2 用法或配置错误。配置错误会一次性列出所有问题，每个问题都带其路径（screens[2].copy.tr: missing）。

配置参考

字段
background	品牌色，6 位十六进制。必填。
presets	ios-phone、android-phone、ipad-13、android-tablet 中的任意项。默认：两种手机。
languages	BCP-47 代码。默认：第一屏 copy 中的语言。
screens[]	最多 10 个，按商店顺序排列。每个包含一个 screenshot、每种语言一份 copy（["verb", "descriptor"] 或 {"verb", "descriptor"}），以及可选的自身 variant 或 background。
screens[].screenshot	相对于配置的路径。使用 {lang}、{preset} 和 {platform}（ios/android）来表示本地化或按平台的截图，例如 "shots/{platform}/{lang}/home.png"。你还可以给出以预设 id 为键、带 "default" 回退的对象。
variant	text-top（默认）、text-bottom 或 tilted。适用于整个集合；某一屏自身的 variant 会覆盖它。
panorama	{ "to": "#hex" }：一条从 background 贯穿每个面板的渐变。
frame	一个自定义边框，或每个预设 id 一个。
featureGraphic	{ "screen": n } 复用某一屏的截图和文案。你也可以直接给出 screenshot、copy 和 background。
showcase	true 会为每种语言和预设向 output/showcase/ 写入一条预览长图。
outputDir、noGradient	输出文件夹（默认 output）。noGradient 关闭细微的垂直渐变。

配合 AI Agent 使用

storeshots 将创意工作与生产工作分开。你的 Agent 读取你的应用，为每一屏挑选一个卖点，撰写标题并翻译到 storeshots.json，然后运行 storeshots build。在任何具备 shell 的 Agent 中都无需设置：Claude Code、Cursor、Codex、Windsurf 等。如需引导式流程，请安装 Claude Code 插件。

"把 ./raw-shots 里的截图做成一整套 App Store 和 Play Store 素材。品牌色 #E31837，英语和土耳其语。"

MCP 服务。 对于没有 shell 的客户端（例如 Claude Desktop），同一引擎以 stdio MCP 服务运行：

claude mcp add storeshots -- npx -y storeshots-mcp

{ "mcpServers": { "storeshots": { "command": "npx", "args": ["-y", "storeshots-mcp"] } } }

Codex CLI 使用 ~/.codex/config.toml：

[mcp_servers.storeshots]
command = "npx"
args = ["-y", "storeshots-mcp"]

产出内容

5 个预设，每个都符合其商店要求的确切尺寸：

预设	商店	尺寸
ios-phone	App Store，iPhone 6.9"	1320 × 2868
android-phone	Google Play，手机	1080 × 1920
ipad-13	App Store，iPad Pro 13"	2064 × 2752
android-tablet	Google Play，10" 平板	1600 × 2560
play-feature-graphic	Google Play 特色图形	1024 × 500

以及让整套图看起来经过精心设计的点睛之笔：

• 内置设备边框——iPhone（灵动岛）、Pixel 风格 Android（挖孔）、iPad 和平板，均以精确比例程序化绘制。也可以通过自定义边框自带边框。
• 布局变体——text-top、text-bottom 和 tilted；在一套图中混用它们，就不会看起来像同一个模板复制了六次。
• 全景套图——一个渐变在所有面板上连续流动，因此在商店中整行看起来是一张完整的图。参见全景图。
• 以利益点为先的标题——一个醒目的动词加一个简短描述，自动转为大写，并正确处理区域设置的特殊字符和对比度感知的颜色。
• 展示图合成器——为整个套图生成一张宽幅预览图，用于你的仓库、发布帖或客户演示。
• 展示图合成器——为整个套图生成一张宽幅预览图，用于你的仓库、发布帖或客户演示。

每份输出都会经过拼合处理，以移除 App Store Connect 拒绝的 alpha 通道，并在写入前按其预设进行验证。

MCP 工具

工具	功能
build_project	构建 storeshots.json，仅重新渲染发生变化的内容。这与 storeshots build 是同一引擎。
generate_set	针对一种平台和语言批量渲染一组有序套图。支持全景图。
compose_screenshot	渲染单张截图（背景、边框、标题、源图像）
create_showcase	将生成的截图拼接成一条预览横条
validate_screenshot	按商店尺寸和格式规则检查图像
list_presets	列出每个预设及其商店和确切尺寸

每个工具都会返回文件路径以及结构化摘要，因此 Agent 可以审查并迭代。

多语言套图

翻译发生在 Agent 中，而不是 storeshots 中。为每个屏幕的 copy 添加一个语言键，storeshots 就会以区域设置正确的大小写规则渲染它：土耳其语 i → İ，德语 ß 保持不变。storeshots build --lang de 会重新构建单一语言。

全景套图

添加 "panorama": { "to": "#1E3A8A" }，每个面板的纯色背景就会变成横跨整个套图切割成多块的一个水平渐变。并排放在商店中时，这些截图就会呈现为一张连续完整的图像。

自定义边框

偏好某种特定的设备外观？提供你自己的边框 PNG（在屏幕透出的位置为透明），以及截图填充的像素矩形：

{
  "frame": {
    "image": "./frames/iphone-16-pro.png",
    "screenX": 40, "screenY": 40,
    "screenWidth": 1080, "screenHeight": 2280
  }
}

在 storeshots.json 中将其用作 "frame"，可以是为每个预设使用同一个边框，也可以是 { "ios-phone": {…}, "android-phone": {…} }。你也可以将它传给 storeshots compose --frame frame.png --frame-screen 40,40,1080,2280，或传给 compose_screenshot 和 generate_set 工具。路径相对于配置，且边框图像发生变化会触发重新渲染。留空则使用内置边框。

Agent 设置

项目指令。 storeshots init 会向项目的 Agent 指令文件添加一段简短的、以标记分隔的 storeshots 段落。编码 Agent（Claude Code、Codex、Cursor 等）随后便知道该项目的截图是如何生成的：编辑 storeshots.json、运行 storeshots build，并且永远不要手动编辑 PNG。

• 它会使用 AGENTS.md 和/或 CLAUDE.md，以已存在的为准。当 CLAUDE.md 只是导入 @AGENTS.md 时，只有 AGENTS.md 会添加该段落。
• 如果两个文件都不存在，它会创建 AGENTS.md 以及一个导入它的 CLAUDE.md。
• 重新运行会就地更新该段落。--no-agents 会跳过它，而 storeshots init --agents-only 会将其添加到现有项目。

Claude Code 插件。 内置的 skill 会添加一个引导式工作流。它会从你的代码库中为每个屏幕发现一项卖点，并在渲染前就标题取得你的确认。随后它会保持 storeshots.json 最新、添加语言，并引导你完成上传。

/plugin marketplace add mtbun/storeshots-mcp
/plugin install storeshots@storeshots

然后向 Claude Code 请求 "store screenshots for this app"。

llms.txt 在一个文件中为 Agent 概述了命令和配置格式。

设计原则

1. 确定性 —— 渲染路径中不使用 AI 图像生成；相同输入，相同像素。
2. 零配置 —— 无需 API 密钥，无需账户，完全离线。
3. 构造即符合商店要求 —— 尺寸是被强制执行和校验的，而非建议值。
4. Agent 原生 —— 工具暴露结构化数据；文案留在它该待的模型里。

路线图

• 带引导式卖点发现工作流的 Claude Code skill
• Play Store 特色图片预设（1024 × 500）
• 布局变体 —— 文字在上、文字在下、倾斜
• 自定义设备边框
• 全景套图
• 支持增量 build 和 --watch 的项目配置
• Claude Code 插件及 AGENTS.md / CLAUDE.md 集成
• 应用预览视频帧
• 更多商店（Mac App Store、Chrome Web Store）

贡献

欢迎提交 Issue 和 PR。AGENTS.md 记录了架构和约定，供人类贡献者和编码 Agent 参考。

许可证

MIT