@appscreenshotstudio/mcp 0.4.3 → 0.4.4

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)
+- **14 layouts**: `text-top-device-bottom`, `text-top-device-tilted`, `device-hero`, `social-proof`, `review-clip`, `screen-hero`, `lifestyle-hero`, `photo-device-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,6 +31,7 @@ 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 },
@@ -126,7 +127,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 +138,25 @@ 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:
+14 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)
+- photo-device-hero: full-bleed photo background + headline overlay + flat 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
@@ -268,14 +274,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 (14 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, review-clip, screen-hero, lifestyle-hero, photo-device-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
@@ -506,7 +512,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 +800,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.4.4",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",

package/skills/appscreenshotstudio/SKILL.md

@@ -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