@appscreenshotstudio/mcp 0.4.4 → 0.5.2

package/README.md

@@ -200,7 +200,7 @@ The AI generates professional screenshots using:
 - **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
-- **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.
+- **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
 
@@ -219,6 +219,7 @@ The AI generates professional screenshots using:
 
 ## Links
 
+- [Screenshot API + MCP overview](https://appscreenshotstudio.com/api)
 - [Full docs](https://appscreenshotstudio.com/docs/mcp)
 - [REST API reference](https://appscreenshotstudio.com/docs/api)
 - [Pricing](https://appscreenshotstudio.com/pricing)

package/dist/index.js

@@ -38,6 +38,33 @@ const DEVICES = [
     { 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) {
@@ -127,7 +154,7 @@ function buildDesignMessage(input) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.4.4',
+    version: '0.5.2',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
@@ -138,7 +165,7 @@ 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.
 
-14 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
@@ -146,7 +173,6 @@ The AI picks a narrative arc that fits the app's sell angle (trust-first for fin
 - 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)
 - stats-hero: giant centered stat(s), no device, numbers-led
@@ -210,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) {
@@ -274,13 +306,13 @@ 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 (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.
+- 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
+- Compound fields (auto-positioned): statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit, stepList
 - 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
@@ -377,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'),
     }),
@@ -389,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', {
@@ -760,7 +810,7 @@ This tool helps you gather the right information so generate-screenshots produce
     if (platform === 'android' || platform === 'both') {
         deviceTips.push('**Android (required for Play Store):**');
         deviceTips.push('- Android Phone (android-phone): 1080×2340 — REQUIRED');
-        deviceTips.push('- Android Tablet 7" (android-tablet-10): 1200×1920 — optional');
+        deviceTips.push('- Android Tablet 7" (android-tablet-10): 1200×1920 — REQUIRED');
         deviceTips.push('');
     }
     // Schema reminder

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.4.4",
+  "version": "0.5.2",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",
   "homepage": "https://appscreenshotstudio.com/docs/mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/appscreenshotstudio/mcp-server"
+    "url": "https://github.com/TWWorks-org/mcp-server"
   },
   "keywords": [
     "mcp",

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