truepane-mcp

A local MCP server for Truepane. It lets an AI agent (Claude Code, Codex, …) take raw app screenshots — e.g. captured from a simulator — and turn them into store-ready App Store / Google Play slides: procedural device frames at exact store resolutions, generated backgrounds, typography, and per-language localization.

Everything runs locally. It renders with a native canvas (@napi-rs/canvas): screenshots are read from local file paths and PNGs are written to local file paths — nothing is uploaded anywhere. No configuration or API keys are needed. The agent is itself the language model, so styling and translation are its own judgment calls.

What agents can do

• Build one project for iPhone, iPad, Android phone, and Android tablet, with target- and locale-specific screenshots.
• Preview and apply a screenshot directory deterministically with import_screenshots; conflicts never overwrite silently.
• Place text and devices with normalized coordinates, resize mockups, align copy, rotate devices from −20° to +20°, and tilt the text block from −12° to +12°.
• Set a custom background image per slide, across every slide, or as one long backdrop sliced across the whole strip, with set_background_image. Tune opacity, scrim, and fit afterwards; a scrim keeps titles readable over a photo. A backdrop can also be derived from the slide's own screenshot, which costs no storage at all.
• Compose backgrounds parametrically with the custom shape family: six primitives (ring, disc, arc, triangle, bar, blob) across five arrangements (scatter, grid, row, radial, wave), with size, jitter, rotation, spacing, phase, stroke, and an opacity ramp. It is data, not code — deterministic from a seed, safe to share in a project file, and laid out in strip-space so a multi-slide background flows continuously.
• Span one synchronized device across two adjacent slides. Both clipped halves keep their screenshot, position, scale, and rotation linked.
• Save and apply portable brand kits without carrying screenshots or project data.
• Render native store sizes, the 1024×500 Google Play feature graphic, or bounded custom dimensions. Custom width and height are validated together and rejected rather than silently replaced or clamped.
• Run the same advisory release preflight as the browser editor.
• Save a release baseline, compare added/changed/unchanged/removed assets, and render only changed assets.
• Round-trip editable project JSON with the Truepane web editor.

Install

It's a standard stdio MCP server — any MCP-capable client can launch it with npx -y truepane-mcp (no checkout required). Requires Node ≥ 18.

Claude Code

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

Codex CLI

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

Or configure Codex manually in ~/.codex/config.toml:

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

Cursor, Windsurf, Claude Desktop, and other JSON-config clients — add to the client's mcpServers block:

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

Restart the client, then confirm that the Truepane tools are available.

Recommended agent workflow

1. Call list_options first. It returns the full capability map plus valid platforms, output surfaces, fonts, backgrounds, and composition presets.
2. Use create_project for slide copy and optional screenshots. Pass targets for a multi-platform project.
3. Attach target/locale media with set_screenshots, or preview a prepared directory with import_screenshots and explicitly apply the reviewed map.
4. Use set_style for typography, colors, backgrounds, and composition. For a background photo or a strip-wide backdrop, call set_background_image with a local file first, then tune it via set_style background.image. With slide_index, composition is slide-specific; device position is normalized canvas space, scale is 0.4..1.6, and rotation is −20..20. suggest_palette_from_screenshot provides a local-math starting palette.
5. Use span_device_across_slides when one linked device should cross an adjacent slide boundary.
6. Add localized copy and optional localized screenshots with set_translations. Render language: "all" for locale subfolders.
7. Call validate_project, then render and inspect its inline preview. Adjust and re-render until the set is ready.
8. Use export_project / load_project for browser-editor handoff.

Tool map

render writes full-resolution PNGs and returns a compact inline preview. Use target: "all" and/or language: "all" for the full matrix. Use what: "strip" for a continuous horizontal strip.

Fonts

Google Fonts are fetched on demand and cached in ~/.cache/truepane/fonts (Inter is bundled, so offline rendering works out of the box). The -apple-system font renders as real San Francisco on macOS — from your own installed system font, never bundled or redistributed — and falls back to Inter on Linux/CI. SF is a variable font, so its full weight range resolves (including Heavy/Black via titleWeight/subtitleWeight), not just Regular/Bold. A curated set of Google fonts — Inter, Manrope, and Fraunces — is loaded as a single-file variable font too, so their full range resolves as well; other Google fonts use their static faces (up to ~700). Want another font's full range? Open an issue or PR adding it to VARIABLE_FONT_URLS in server/mcp/fonts.ts. For non-Latin target languages, pick a font that covers the script (Inter covers Cyrillic/Greek; Noto Sans JP/KR/SC for CJK; Noto Sans Arabic for Arabic, which is shaped and laid out right-to-left automatically) — unlike browsers, server-side rendering has no per-glyph system-font fallback, so glyphs a font lacks come out as boxes.

License

AGPL-3.0. Part of the Truepane project; see the main repository for the web app and full documentation.