truepane

truepane-mcp

一个用于 Truepane 的本地 MCP 服务。它允许 AI Agent （Claude Code、Codex 等）获取原始应用截图（例如从模拟器中捕获的截图），并将其制作成可直接上架 App Store / Google Play 的幻灯片： 使用精确的商店分辨率生成程序化设备边框、背景、排版和多语言本地化内容。

所有操作均在本地运行。它使用原生画布 （@napi-rs/canvas）进行渲染：从本地文件路径读取截图，并将 PNG 写入本地文件路径——不会上传到任何地方。无需配置或 API 密钥。 Agent 本身就是大模型，因此样式设计和翻译由它自行判断。

Agent 可以做什么

• 为 iPhone、iPad、Android 手机和 Android 平板构建一个项目，并添加特定目标平台和语言区域的截图。
• 使用 import_screenshots 以确定性方式预览并应用截图目录；冲突绝不会在未提示的情况下覆盖文件。
• 使用归一化坐标放置文字和设备、调整样机大小、对齐文案、将设备旋转 −20° 至 +20°，并将文本块倾斜 −12° 至 +12°。
• 使用 set_background_image 为单张幻灯片、所有幻灯片设置自定义背景图片，或设置一张横跨整个条带并切分到各张幻灯片的长背景图。之后还可调整不透明度、遮罩和适配方式；遮罩可确保标题在照片上清晰可读。背景也可以从幻灯片自身的截图生成，无需占用任何存储空间。
• 使用 custom 形状系列以参数化方式组合背景：六种基本图形（圆环、圆盘、弧形、三角形、长条、blob）和五种排列方式（散布、网格、行、径向、波浪），并可调整大小、抖动、旋转、间距、相位、描边和不透明度渐变。它是数据而非代码——根据种子确定性生成，可安全地共享在项目文件中，并采用条带空间布局，使多张幻灯片的背景连续衔接。
• 在相邻的两张幻灯片之间放置一个同步设备。两侧裁切出的部分均保留各自的截图，并保持位置、缩放和旋转联动。
• 保存并应用便携式品牌套件，无需携带截图或项目数据。
• 渲染商店原生尺寸、1024×500 的 Google Play 宣传图片，或有边界限制的自定义尺寸。自定义宽度和高度会作为一组进行验证；若不符合要求，则会被拒绝，而不会静默替换或钳制。
• 执行与浏览器编辑器相同的发布前检查。
• 保存发布基线，比较新增、已更改、未更改和已移除的资源，并仅渲染已更改的资源。
• 与 Truepane Web 编辑器双向转换可编辑的项目 JSON。

安装

这是一个标准的 stdio MCP 服务——任何支持 MCP 的客户端都可以通过 npx -y truepane-mcp 启动（无需检出代码仓库）。需要 Node ≥ 18。

Claude Code

claude mcp add --scope user truepane -- npx -y truepane-mcp

Codex CLI

codex mcp add truepane -- npx -y truepane-mcp

或者在 ~/.codex/config.toml 中手动配置 Codex：

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

Cursor、Windsurf、Claude Desktop 和其他 JSON 配置客户端——将以下内容添加到 客户端的 mcpServers 配置块中：

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

重启客户端，然后确认 Truepane 工具已可用。

推荐的 Agent 工作流

1. 首先调用 list_options。它会返回完整的能力映射，以及有效的平台、输出画布、字体、背景和构图预设。
2. 使用 create_project 创建幻灯片文案和可选截图。对于多平台项目，传入 targets。
3. 使用 set_screenshots 附加目标平台/区域设置对应的媒体，或使用 import_screenshots 预览准备好的目录，并明确应用审核后的映射。
4. 使用 set_style 设置排版、颜色、背景和构图。对于背景照片或贯穿整条画布的背景， 先调用 set_background_image 并传入本地文件，再通过 set_style background.image 进行调整。 指定 slide_index 时，构图仅应用于对应幻灯片；设备位置采用归一化画布坐标，缩放范围为 0.4..1.6，旋转范围为 −20..20。 suggest_palette_from_screenshot 可提供基于本地计算的初始配色方案。
5. 当一个关联设备需要跨越相邻幻灯片边界时，使用 span_device_across_slides。
6. 使用 set_translations 添加本地化文案和可选的本地化截图。使用 language: "all" 进行渲染，可生成区域设置子文件夹。
7. 调用 validate_project，然后调用 render 并检查其内嵌预览。 调整后重新渲染，直到整组内容准备就绪。
8. 使用 export_project / load_project 与浏览器编辑器交接。

工具映射

目标	工具
创建和编辑内容	create_project, set_slides, set_screenshots, set_translations
批量及多目标媒体	import_screenshots, set_screenshots
样式和构图	set_style, suggest_palette_from_screenshot, span_device_across_slides
背景图像	set_background_image, set_style with background.image
可复用的视觉系统	export_brand_kit, apply_brand_kit
原生、功能和自定义画布	set_output, render
发布安全	validate_project, compare_release, set_release_baseline, render with changed_only
网页编辑器交接	export_project, load_project

render 会写入全分辨率 PNG，并返回精简的内嵌预览。 使用 target: "all" 和/或 language: "all" 生成完整矩阵。使用 what: "strip" 生成连续的水平长图。

字体

Google Fonts 会按需获取并缓存在 ~/.cache/truepane/fonts 中（已内置 Inter，因此开箱即可离线渲染）。在 macOS 上，-apple-system 字体会使用真实的 San Francisco 渲染——来自你自己安装的系统字体，不会打包或再分发——在 Linux/CI 上则回退到 Inter。SF 是可变字体，因此可以使用完整字重范围（包括通过 titleWeight/subtitleWeight 指定的 Heavy/Black），而不仅限于 Regular/Bold。精选的 Google 字体——Inter、Manrope 和 Fraunces——也会作为单文件可变字体加载，因此同样支持完整字重范围；其他 Google 字体则使用静态字重（最高约为 700）。想要使用其他字体的完整字重范围？请提交 issue，或通过 PR 将其添加到 server/mcp/fonts.ts 的 VARIABLE_FONT_URLS 中。对于非拉丁语目标语言，请选择支持相应文字系统的字体（Inter 支持西里尔字母/希腊字母；CJK 使用 Noto Sans JP/KR/SC；阿拉伯语使用 Noto Sans Arabic，其文字会自动进行塑形并从右向左排版）——与浏览器不同，服务端渲染不会对每个字形使用系统字体回退，因此字体不包含的字形会显示为方框。

许可证

AGPL-3.0。本项目是 Truepane 项目的一部分；有关 Web 应用和完整文档，请参阅 主代码仓库。