@appscreenshotstudio/mcp 0.4.3 → 0.5.1

package/README.md

@@ -148,6 +148,21 @@ Generate an AI background for a specific card. Uses project metadata (brand colo
 
 **Costs 6 credits.**
 
+### `generate-panoramic-background`
+
+Generate one wide image and slice it across multiple cards so they read as a continuous scene in the App Store gallery. Use after a panoramic chat edit ("pano the background across cards 1-3") to fulfill the pending panoramic, or pass an explicit `prompt` / `pexels_query`.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project containing the cards |
+| `prompt` | string | No | AI scene description (Gemini). Costs 6 credits. |
+| `pexels_query` | string | No | Stock photo search query (Pexels). Free. |
+| `card_indices` | number[] | No | Cards sharing the panoramic (0-based, min 2). Default: first 3. |
+
+Omit both `prompt` and `pexels_query` to fulfill a panoramic already set up by `generate-screenshots` / `edit-screenshots`.
+
+**Costs 6 credits (AI prompt) or free (Pexels query).**
+
 ### `list-devices`
 
 Show all supported device specs. No API call needed.
@@ -169,6 +184,7 @@ Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate
 | ID | Name | Size | Required |
 |---|---|---|---|
 | `iphone-6.9` | iPhone 16 Pro Max | 1260x2736 | App Store |
+| `iphone-6.3` | iPhone 17 Pro | 1206x2622 | Optional |
 | `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
 | `android-phone` | Android Phone | 1080x2340 | Play Store |
 | `android-tablet-10` | Android Tablet 7" | 1200x1920 | Play Store |
@@ -178,12 +194,13 @@ Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate
 
 The AI generates professional screenshots using:
 
-- **78+ decorative shapes** across 13 categories: nature (leaf, flower, tree), weather (cloud, sun, snowflake), celebration (sparkle, trophy, crown, confetti), social (chat-bubble, music-note), tech (rocket, code-bracket), health (dumbbell, flame), food (coffee-cup, pizza), travel (airplane, compass), finance (dollar-sign, piggy-bank), education (graduation-cap, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji), abstract (swirl, infinity, gem)
+- **94 shape types** (17 core + 77 decorative across 13 categories): nature (leaf, flower, tree), weather (cloud, sun, snowflake), celebration (sparkle, trophy, crown, confetti), social (chat-bubble, music-note), tech (rocket, code-bracket), health (dumbbell, flame), food (coffee-cup, pizza), travel (airplane, compass), finance (dollar-sign, piggy-bank), education (graduation-cap, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji), abstract (swirl, infinity, gem)
 - **Rich text**: per-word color, bold, italic, underline, highlight pills (colored backgrounds behind words), gradient fills, text stroke outlines, emoji
-- **Laurel stats**: wing-left + wing-right shapes flanking stats like "4.9 Rating" or "1M+ Users"
-- **Floating UI snippets**: rounded-rect panels with text overlapping device edges
+- **Compound trust signals**: statRow, laurelStat, starRating, quote, pressBanner, featureGrid, beforeAfterSplit, stepList — auto-positioned per layout
+- **Frame color**: recolor the device frame — `natural` (default), `black`, `white`, `gold`. Requires Growth plan or higher.
+- **Panoramics**: slice one wide image across cards (chat tags the cards, then `generate-panoramic-background` creates and slices the image) or stretch a foreground element across adjacent cards (`apply_element_span`). Gallery gutters are accounted for.
 - **9 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, landscape-left, landscape-right
-- **7 layouts**: Text Top + Device Center (A), Text Top + Device Offset (B), Social Proof (C), Marketing Title (M1), Feature Callout (M2), CTA (M3), Testimonial (M4)
+- **13 layouts**: `text-top-device-bottom`, `text-top-device-tilted`, `device-hero`, `social-proof`, `review-clip`, `screen-hero`, `lifestyle-hero`, `feature-grid`, `before-after`, `stats-hero`, `metric-badge`, `annotated-feature`, `step-flow`. The AI varies `deviceScale`, `deviceSide`, `textPosition`, and `textAlign` per card so a set never looks like duplicates.
 
 ## Workflow
 

package/dist/index.js

@@ -31,12 +31,40 @@ const API_KEY = process.env.APPSCREENSHOTSTUDIO_API_KEY;
 // ⚠️ Keep in sync: lib/device-specs.ts, mcp-server/README.md, docs/api page, docs/mcp page
 const DEVICES = [
     { id: 'iphone-6.9', name: 'iPhone 16 Pro Max', width: 1260, height: 2736, category: 'iphone', required: true },
+    { id: 'iphone-6.3', name: 'iPhone 17 Pro', width: 1206, height: 2622, category: 'iphone', required: false },
     { id: 'ipad-13', name: 'iPad Pro 13"', width: 2064, height: 2752, category: 'ipad', required: true },
     { id: 'android-phone', name: 'Android Phone', width: 1080, height: 2340, category: 'android-phone', required: true },
     { id: 'android-tablet-10', name: 'Android Tablet 7"', width: 1200, height: 1920, category: 'android-tablet', required: true },
     { id: 'apple-watch-ultra', name: 'Apple Watch Ultra 2', width: 410, height: 502, category: 'apple-watch', required: true },
 ];
 const VALID_DEVICE_IDS = DEVICES.map(d => d.id);
+// Aliases callers commonly pass instead of the canonical id: display-name
+// derivations ("iPhone 16 Pro Max" -> iphone-16-pro-max) and legacy slugs.
+// Mirrors MARKETING_TO_SPEC in lib/device-specs.ts — keep the two in sync.
+const DEVICE_ALIASES = {
+    'iphone-16-pro': 'iphone-6.9',
+    'iphone-16-pro-max': 'iphone-6.9',
+    'iphone-17-pro': 'iphone-6.3',
+    'samsung-galaxy-s25-ultra': 'android-phone',
+    'ipad-pro-13': 'ipad-13',
+    'ipad-12.9': 'ipad-13',
+    'ipad-pro-12.9': 'ipad-13',
+    'android-tablet': 'android-tablet-10',
+    'apple-watch': 'apple-watch-ultra',
+};
+/**
+ * Resolve a caller-supplied device id to a canonical one, or return the list of
+ * valid devices for a helpful error. Runs at the tool boundary so an unknown
+ * device fails fast (before a project is created and generation credits are
+ * spent) instead of surfacing late as a render-time "Unknown device".
+ */
+function resolveDeviceId(input) {
+    const normalized = DEVICE_ALIASES[input] ?? input;
+    if (VALID_DEVICE_IDS.includes(normalized))
+        return { id: normalized };
+    const options = DEVICES.map(d => `${d.id} (${d.name})`).join(', ');
+    return { error: `Unknown device "${input}". Valid devices: ${options}.` };
+}
 // ─── API helper ─────────────────────────────────────────────────────────────────
 async function apiCall(method, path, body) {
     if (!API_KEY) {
@@ -126,7 +154,7 @@ function buildDesignMessage(input) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.4.3',
+    version: '0.4.4',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
@@ -137,20 +165,24 @@ IMPORTANT: Before calling this tool, research the user's codebase to populate th
 
 The AI picks a narrative arc that fits the app's sell angle (trust-first for finance/health, visual-first for creative/lifestyle, problem-first for pain-relief apps, numbers-led for SaaS/analytics, community-first for social, feature-forward for multi-mode apps) and assigns a job to each card: HOOK → EDUCATE → PROVE → CONVERT.
 
-9 layout types available per card:
+13 layout types available per card:
 - text-top-device-bottom: headline top, flat device bottom (feature/educate)
 - text-top-device-tilted: headline left, tilted device right (or mirrored)
 - device-hero: headline + large centered device, product-forward
-- social-proof: stars + quote + laurel stat, device optional
-- feature-callout: headline + features list, no device
-- lifestyle-hero: full-bleed photo background + text overlay
+- social-proof: stars + quote + laurel stat, no device (testimonial-led)
+- review-clip: rating-statement headline + stars + quote + bottom-clipped device
+- screen-hero: top-clipped device + centered headline + optional trust stat
+- lifestyle-hero: full-bleed photo background + text overlay (no device)
+- feature-grid: headline + 2×2 or 2×3 icon+label grid, no device
 - before-after: dark before-half + bright after-half (transformation apps)
-- text-bottom: headline anchored to lower third, cinematic
 - stats-hero: giant centered stat(s), no device, numbers-led
+- metric-badge: centered device + chunky "achievement card" floating over its screen
+- annotated-feature: tilted device + side callout chip linked by a connector line
+- step-flow: headline + 2-4 numbered step rows ("how it works"), no device
 
-Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit.
+Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit, stepList.
 
-Panoramic backgrounds slice one wide AI-generated or Pexels image across multiple cards for cohesion. Panoramic element spans stretch a foreground image or device across adjacent cards.
+Panoramic backgrounds slice one wide AI-generated or Pexels image across multiple cards for cohesion. Panoramic element spans stretch a foreground image or device across adjacent cards. Note: if the design comes back with a panoramic background, the chat only tags the cards; call generate-panoramic-background afterwards to actually create and slice the wide image.
 
 Design features:
 - Rich text with per-word color, weight, italic, underline, highlight pills, gradient fills, stroke outlines, and emoji
@@ -204,10 +236,16 @@ Costs 5 credits per generation.`,
             .describe('Context gathered from researching the app codebase. Dramatically improves screenshot quality — the more detail here, the better the output.'),
     }),
 }, async (input) => {
+    // Resolve/validate the device up front so an unknown id fails fast here
+    // instead of after a project (and its 5 generation credits) is spent.
+    const resolved = resolveDeviceId(input.device_id);
+    if ('error' in resolved) {
+        return { content: [{ type: 'text', text: resolved.error }] };
+    }
     // Step 1: Create project (with codebase context if provided)
     const projectName = `${input.app_name} Screenshots`;
     const createBody = {
-        device_id: input.device_id,
+        device_id: resolved.id,
         name: projectName,
     };
     if (input.codebase_context) {
@@ -268,14 +306,14 @@ What you can change:
 - Text: headlines, subtitles, badge text, font size, font family (Inter, Poppins, Montserrat, DM Sans, Space Grotesk, etc.)
 - Text styling: per-word color, bold, italic, underline, highlight pills (colored background behind words), gradient text, text stroke outlines
 - Colors: brand palette, gradient backgrounds, accent colors, text colors
-- Layouts (9 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, feature-callout, lifestyle-hero, before-after, text-bottom, stats-hero. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
-- Layout params: deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), compoundPlacement (below-text/below-device)
+- Layouts (13 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, review-clip, screen-hero, lifestyle-hero, feature-grid, before-after, stats-hero, metric-badge, annotated-feature, step-flow. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
+- Layout params: deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), textAlign (left/center)
 - Device mockups: perspective variants (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), 2D rotation, resize, reposition
 - Frame color: recolor the device frame — "natural" (default), "black", "white", "gold". Examples: "make the iPhone gold", "black titanium finish", "white iPhone". Requires Growth plan or higher.
 - Switch devices: "make this for Apple Watch" / "duplicate for Android tablet" clones the project at the target device's canvas size
 - Add/remove cards: add a social proof card, remove card 3, add a marketing title card
 - Compound fields (auto-positioned): statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit
-- Panoramic backgrounds: one wide AI or Pexels image sliced across multiple cards ("pano the background across cards 1-3")
+- Panoramic backgrounds: one wide AI or Pexels image sliced across multiple cards ("pano the background across cards 1-3"). The edit only tags the cards; call generate-panoramic-background afterwards to create and slice the wide image.
 - Panoramic element spans: stretch a foreground image, device-mockup, or shape across adjacent cards ("pano the device across cards 1-2")
 - Floating elements: add/edit badges, star ratings
 - Shapes: glow orbs, waves, blobs, rounded rectangles, circles, custom SVG paths
@@ -371,7 +409,7 @@ Example edit messages:
 // Tool 3: render-screenshots
 server.registerTool('render-screenshots', {
     title: 'Render Screenshots to PNG',
-    description: 'Export a screenshot project to high-resolution PNG files at exact App Store dimensions. Returns download URLs for each card. Free — no credit cost. Note: device mockups will show empty frames unless app screenshots have been uploaded via upload-screenshots first.',
+    description: 'Export a screenshot project to high-resolution PNG files at exact App Store dimensions. Returns download URLs for each card. Free (no credit cost). Rendering blocks until the PNGs are ready: expect roughly 20-40s for iPhone sets and 60-120s for iPad (the larger canvas renders slower), so allow up to ~2 minutes before treating it as failed. Note: device mockups will show empty frames unless app screenshots have been uploaded via upload-screenshots first.',
     inputSchema: z.object({
         project_id: z.string().describe('Project ID to render'),
     }),
@@ -383,16 +421,34 @@ server.registerTool('render-screenshots', {
         };
     }
     const data = res.data.data;
-    return {
-        content: [{
-                type: 'text',
-                text: [
-                    `Rendered ${data.images?.length || 0} screenshots:`,
-                    '',
-                    ...(data.images || []).map((img, i) => `Card ${i + 1}: ${img.url} (${img.width}×${img.height})`),
-                ].join('\n'),
-            }],
-    };
+    const images = data.images || [];
+    // Text block: full-resolution download URLs (for export / saving to disk).
+    const content = [
+        {
+            type: 'text',
+            text: [
+                `Rendered ${images.length} screenshot${images.length === 1 ? '' : 's'}:`,
+                '',
+                ...images.map((img, i) => `Card ${i + 1}: ${img.url} (${img.width}×${img.height})`),
+                '',
+                'Previews are shown below. To compare all cards side by side at full size,',
+                'refine by hand, or export, open the project URL in the builder.',
+            ].join('\n'),
+        },
+    ];
+    // Image blocks: downscaled inline previews so image-capable agents
+    // (Claude Code, Cursor) display the screenshots in-chat. The API returns
+    // each preview as a `data:<mime>;base64,<data>` URL; MCP image content
+    // needs the raw base64 + mimeType, so split it out.
+    for (const img of images) {
+        if (!img.preview)
+            continue;
+        const match = /^data:(image\/[a-zA-Z+]+);base64,(.+)$/.exec(img.preview);
+        if (!match)
+            continue;
+        content.push({ type: 'image', mimeType: match[1], data: match[2] });
+    }
+    return { content };
 });
 // Tool 4: list-devices
 server.registerTool('list-devices', {
@@ -506,7 +562,55 @@ The generated image is cropped to exact device dimensions and set as the card's
             }],
     };
 });
-// Tool 7: prepare-screenshot-brief
+// Tool 7: generate-panoramic-background
+server.registerTool('generate-panoramic-background', {
+    title: 'Generate Panoramic Background',
+    description: `Generate one wide background image and slice it across multiple cards so they read as a continuous scene when the App Store gallery scrolls. The store gallery gap is accounted for, so slices line up after Apple's gutter.
+
+Two image sources:
+- prompt: AI-generated via Gemini. Costs 6 credits.
+- pexels_query: stock landscape photo from Pexels. Free.
+
+If you omit both, the tool fulfills a panoramic the chat already set up: when generate-screenshots or edit-screenshots returns a design with a panoramic background (e.g. after "pano the background across cards 1-3"), the cards are tagged but the wide image isn't created yet. Calling this tool with just the project_id picks up that pending panoramic and generates it.
+
+Good prompts describe a continuous scene, not objects or text:
+- "Misty mountain range at dawn, soft pink-to-blue gradient sky"
+- "Calm ocean horizon at golden hour with gentle waves"
+- "Abstract flowing emerald and teal silk waves"`,
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID'),
+        prompt: z.string().optional()
+            .describe('AI scene description (Gemini, 6 credits). Describe one continuous landscape scene: no text, devices, or UI.'),
+        pexels_query: z.string().optional()
+            .describe('Stock photo search query (Pexels, free). e.g. "mountain sunrise", "ocean horizon". Provide either this or prompt, not both.'),
+        card_indices: z.array(z.number().int().min(0)).max(10).optional()
+            .describe('Which cards share the panoramic (0-based, min 2). Default: first 3 cards (the ones visible in the App Store gallery without scrolling).'),
+    }),
+}, async ({ project_id, prompt, pexels_query, card_indices }) => {
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/generate-panoramic-background`, {
+        ...(prompt ? { prompt } : {}),
+        ...(pexels_query ? { pexels_query } : {}),
+        ...(card_indices ? { card_indices } : {}),
+    });
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Panoramic background generation failed: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const data = res.data.data;
+    const creditsRemaining = res.data.credits_remaining;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `Panoramic background generated and sliced across cards ${data.card_indices.map(i => i + 1).join(', ')}.`,
+                    `Credits remaining: ${creditsRemaining}`,
+                    `Project URL: ${API_BASE}/builder/${project_id}`,
+                ].join('\n'),
+            }],
+    };
+});
+// Tool 8: prepare-screenshot-brief
 server.registerTool('prepare-screenshot-brief', {
     title: 'Prepare Screenshot Brief',
     description: `Get a research checklist and strategy guide to prepare for screenshot generation. Call this BEFORE generate-screenshots to know what to look for in the codebase. Free — no API call or credits needed.
@@ -746,7 +850,7 @@ This tool helps you gather the right information so generate-screenshots produce
             }],
     };
 });
-// Tool 8: upload-screenshots
+// Tool 9: upload-screenshots
 server.registerTool('upload-screenshots', {
     title: 'Upload App Screenshots',
     description: `Upload local app screenshots (from Simulator, emulator, or screen captures) into the device mockups of an existing project. This lets you add real app UI into the device frames without leaving the terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",

package/skills/appscreenshotstudio/SKILL.md

@@ -2,7 +2,7 @@
 name: appscreenshotstudio
 version: 1.0.0
 description: Generate App Store screenshots by researching the codebase and calling AppScreenshotStudio MCP tools. Use when the user mentions "screenshots", "App Store", "Play Store", "store listing", or wants to create marketing screenshots for their app.
-allowed_tools:
+allowed-tools:
   - Read
   - Glob
   - Grep
@@ -64,7 +64,7 @@ Call the `generate-screenshots` MCP tool with:
 - `features`: top 3-5 features as array
 - `brand_colors`: `{ primary, secondary?, accent? }` from theme files
 - `mood`: user's chosen mood
-- `device_id`: `"iphone-6.9"` (default), `"ipad-13"`, `"android-phone"`, `"android-tablet-10"`
+- `device_id`: `"iphone-6.9"` (default), `"ipad-13"`, `"android-phone"`, `"android-tablet-10"`, `"apple-watch-ultra"`
 - `count`: number of cards (3-10)
 - `story_flow`: `"auto"` (default), `"hero-intro"`, `"problem-solution"`, `"benefit-first"`, etc.
 - `codebase_context`: the full context object from Step 1
@@ -76,16 +76,22 @@ If the user has actual app screenshots (from Simulator, emulator, or screen capt
 - Fills the empty device mockups with real app UI
 - Free — no credit cost
 
-### Step 5: Review and Iterate
+### Step 5: Show and Iterate (the core loop)
 
-Share the project URL and offer refinements using `edit-screenshots`:
-- "Want to change any headlines or colors?"
-- "Should I add a social proof card with ratings?"
-- "Want to try a different layout style?"
+This is conversational refinement, so iterate right here in the chat. Don't send the user away to look at links.
+
+1. **Show.** Call `render-screenshots` (free) after generating. It returns inline image previews, so the screenshots display directly in the conversation. Show them.
+2. **Refine.** Let the user react in plain language and apply changes with `edit-screenshots`:
+   - "Want any headlines or colors changed?"
+   - "Should I add a social proof card with ratings?"
+   - "Different layout style?"
+3. **Re-show.** Call `render-screenshots` again to display the updated set inline. Repeat the show → refine → re-show loop until the user is happy.
+
+Hand off to the builder only when it genuinely helps: share the project URL and frame it as the place to **compare all cards side by side at full size, nudge things by hand, or export**. It is the compare-and-export step, not the required destination. Coarse, language-expressible edits ("warmer background", "swap the headline") are faster to do right here in chat.
 
 ### Step 6: Export
 
-Call `render-screenshots` to export PNGs at exact App Store dimensions. This is free.
+`render-screenshots` is also the export: it returns download URLs for the final PNGs at exact App Store dimensions, and it is free. Give the user those URLs. The builder project URL is the alternative when they want to compare the full set visually or hand-tweak before downloading.
 
 ## Headline Rules