@appscreenshotstudio/mcp 0.5.2 → 0.5.4

package/dist/index.js

@@ -92,7 +92,7 @@ const STORY_FLOW_DESCRIPTIONS = {
     'hero-intro': 'Hero branding screen first (no device), then features with devices',
     'social-proof-bookend': 'Hero intro, then features, then social proof ending',
 };
-function buildDesignMessage(input) {
+function buildDesignMessage(input, hasScreenshotImages = false) {
     const parts = [];
     parts.push(`Create ${input.count} App Store screenshots for my app.`);
     parts.push(`\nApp name: ${input.app_name}`);
@@ -147,19 +147,57 @@ function buildDesignMessage(input) {
         parts.push('--- End App Research Context ---');
         parts.push('\nUse the research context above to create screenshots that accurately represent this specific app. Headlines, features, and visual style should reflect what the app actually does and looks like.');
     }
-    parts.push(`\nAll device mockups should have screenshotImage: null — the developer will upload actual app screenshots later.`);
+    if (hasScreenshotImages) {
+        parts.push(`\nMy app screenshots are attached — they are placed into the device frames automatically.`);
+    }
+    else {
+        parts.push(`\nAll device mockups should have screenshotImage: null — the developer will upload actual app screenshots later.`);
+    }
     parts.push(`Please include projectMeta with brand colors, mood, appCategory, and a rich globalVisualTheme description.`);
     return parts.join('\n');
 }
+/** Read local image files into the chat API's images payload. Same file
+ *  handling as upload-screenshots; kind rides through to server-side
+ *  placement (screenshots fill the generated device frames, mascots get
+ *  placed decoratively around the phones). */
+function readImagesForChat(images) {
+    const payload = [];
+    const errors = [];
+    for (const { file_path, kind } of images ?? []) {
+        try {
+            if (!existsSync(file_path)) {
+                errors.push(`File not found: ${file_path}`);
+                continue;
+            }
+            const buffer = readFileSync(file_path);
+            const ext = file_path.toLowerCase().split('.').pop();
+            const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg'
+                : ext === 'webp' ? 'image/webp'
+                    : 'image/png';
+            payload.push({ dataUrl: `data:${mimeType};base64,${buffer.toString('base64')}`, mediaType: mimeType, kind });
+        }
+        catch (err) {
+            errors.push(`Failed to read ${file_path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { payload, errors };
+}
+/** Shared images param for generate-screenshots and edit-screenshots. */
+const chatImagesSchema = z.array(z.object({
+    file_path: z.string().describe('Absolute path to an image file on the local filesystem (PNG, JPG, or WEBP)'),
+    kind: z.enum(['screenshot', 'mascot']).default('screenshot')
+        .describe("'screenshot' = real app UI, automatically placed inside the generated device frames (in attachment order). 'mascot' = the app's character/mascot, placed decoratively around the phones (peeking from behind the hook card's phone, beside or in a corner on the closing card). Use a transparent PNG for mascots."),
+})).max(5).optional()
+    .describe('Images to attach to this generation. App screenshots land inside the device frames automatically; a mascot gets placed around the phones. Both survive later edits and regenerations.');
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.5.2',
+    version: '0.5.4',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
     title: 'Generate App Store Screenshots',
-    description: `Create a complete set of App Store screenshot designs for an app. Returns a project URL where the developer can upload actual app screenshots into the device frames and export final PNGs.
+    description: `Create a complete set of App Store screenshot designs for an app. Attach real app screenshots via the images param and they are placed inside the device frames automatically; attach a mascot/character image (kind: "mascot", transparent PNG) and it gets placed around the phones. Returns a project URL where the developer can preview, refine, and export final PNGs.
 
 IMPORTANT: Before calling this tool, research the user's codebase to populate the codebase_context parameter. Search for: package.json/README (app name & description), theme/color config files (brand colors), route definitions (key screens), marketing copy (value proposition), and App Store metadata. The more context you provide, the better the screenshots will be. Call prepare-screenshot-brief first if you need a research checklist.
 
@@ -234,6 +272,7 @@ Costs 5 credits per generation.`,
                 .describe('The main user journey — e.g. "Sign up → Create project → Invite team → Track progress"'),
         }).optional()
             .describe('Context gathered from researching the app codebase. Dramatically improves screenshot quality — the more detail here, the better the output.'),
+        images: chatImagesSchema,
     }),
 }, async (input) => {
     // Resolve/validate the device up front so an unknown id fails fast here
@@ -259,11 +298,15 @@ Costs 5 credits per generation.`,
     }
     const project = createRes.data.data;
     const projectId = project.id;
-    // Step 2: Chat to generate all cards
-    const message = buildDesignMessage(input);
+    // Step 2: Chat to generate all cards (with attached images when provided:
+    // screenshots auto-fill the device frames, mascots decorate around them)
+    const { payload: chatImages, errors: imageErrors } = readImagesForChat(input.images);
+    const hasScreens = chatImages.some((img) => img.kind === 'screenshot');
+    const message = buildDesignMessage(input, hasScreens);
     const chatRes = await apiCall('POST', `/api/v1/projects/${projectId}/chat`, {
         message,
         selected_card_indices: [],
+        ...(chatImages.length > 0 ? { images: chatImages } : {}),
     });
     if (!chatRes.ok) {
         return {
@@ -286,10 +329,13 @@ Costs 5 credits per generation.`,
                     `Credits remaining: ${creditsRemaining}`,
                     '',
                     'Next steps:',
-                    '1. Use upload-screenshots to add your app screenshots into the device frames',
+                    hasScreens
+                        ? '1. Your attached screenshots were placed into the device frames (upload-screenshots can swap any card later)'
+                        : '1. Use upload-screenshots to add your app screenshots into the device frames',
                     '2. Use render-screenshots to export final PNGs',
                     '3. Or open the project URL in a browser to preview and adjust',
                     '',
+                    imageErrors.length ? `Image read warnings:\n${imageErrors.join('\n')}` : '',
                     chatData.suggestions?.length
                         ? `Suggestions: ${chatData.suggestions.join(', ')}`
                         : '',
@@ -300,7 +346,7 @@ Costs 5 credits per generation.`,
 // Tool 2: edit-screenshots
 server.registerTool('edit-screenshots', {
     title: 'Edit Screenshot Designs',
-    description: `Make changes to an existing screenshot project. Use natural language to describe what you want to change. Costs 5 credits per edit.
+    description: `Make changes to an existing screenshot project. Use natural language to describe what you want to change. Costs 5 credits per edit. You can also attach images: app screenshots fill the device frames of regenerated cards, a mascot (kind: "mascot") gets placed around the phones.
 
 What you can change:
 - Text: headlines, subtitles, badge text, font size, font family (Inter, Poppins, Montserrat, DM Sans, Space Grotesk, etc.)
@@ -357,8 +403,9 @@ Example edit messages:
             primary_user_flow: z.string().optional(),
         }).optional()
             .describe('App context from codebase research. Helps the AI make edits that match the actual app.'),
+        images: chatImagesSchema,
     }),
-}, async ({ project_id, message, card_indices, codebase_context }) => {
+}, async ({ project_id, message, card_indices, codebase_context, images }) => {
     let enrichedMessage = message;
     if (codebase_context) {
         const ctxParts = [];
@@ -378,13 +425,15 @@ Example edit messages:
             enrichedMessage = `[App context: ${ctxParts.join('. ')}]\n\n${message}`;
         }
     }
+    const { payload: chatImages, errors: imageErrors } = readImagesForChat(images);
     const res = await apiCall('POST', `/api/v1/projects/${project_id}/chat`, {
         message: enrichedMessage,
         selected_card_indices: card_indices || [],
+        ...(chatImages.length > 0 ? { images: chatImages } : {}),
     });
     if (!res.ok) {
         return {
-            content: [{ type: 'text', text: `Edit failed: ${JSON.stringify(res.data)}` }],
+            content: [{ type: 'text', text: `Edit failed: ${JSON.stringify(res.data)}${imageErrors.length ? `\n\nImage read warnings:\n${imageErrors.join('\n')}` : ''}` }],
         };
     }
     const data = res.data.data;
@@ -409,7 +458,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). 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.',
+    description: 'Export a screenshot project to high-resolution PNG files at exact App Store dimensions. Returns download URLs for each card; URLs stay valid for 7 days, so save the PNGs to disk promptly (re-rendering is free if a URL has expired). 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'),
     }),
@@ -431,6 +480,9 @@ server.registerTool('render-screenshots', {
                 '',
                 ...images.map((img, i) => `Card ${i + 1}: ${img.url} (${img.width}×${img.height})`),
                 '',
+                'Download URLs are valid for 7 days. Save the PNGs to disk now if you',
+                'need them long-term (re-rendering later is free).',
+                '',
                 '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'),
@@ -480,7 +532,7 @@ Returns the canvas state with:
 - cards[]: each card has an id, elements array, and optional background settings
 - Each element has: type (text, device-mockup, shape, badge, image, star-rating), position (x, y), size (width, height), zIndex, and type-specific properties
 - Text elements: fontFamily, fontSize, fontWeight, color, segments (for multi-color text with per-word color, bold, italic, underline, highlightColor)
-- Device mockups: perspectiveVariant (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), screenshotImage (null if no upload)
+- Device mockups: perspectiveVariant (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), screenshotImage (null if no upload), frameStyle (realistic | none), showIsland (false hides the Dynamic Island pill; Apple accepts screenshots either way)
 - Shapes: 94 shape types (17 core + 77 decorative across 13 categories) — core shapes (circle, rectangle, rounded-rect, blob, wave, triangle, diamond, hexagon, ring, star, wing-left, wing-right, etc.) plus decorative library shapes (leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, and many more)
 - projectMeta: globalVisualTheme, brandColors, mood, appCategory`,
     inputSchema: z.object({

package/package.json

@@ -1,45 +1,48 @@
-{
-  "name": "@appscreenshotstudio/mcp",
-  "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/TWWorks-org/mcp-server"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "app-store-screenshots",
-    "screenshot-generator",
-    "appscreenshotstudio",
-    "ai-tools"
-  ],
-  "bin": {
-    "appscreenshotstudio-mcp": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^3.25.67"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "dist",
-    "skills",
-    "README.md"
-  ]
-}
+{
+  "name": "@appscreenshotstudio/mcp",
+  "version": "0.5.4",
+  "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/TWWorks-org/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/TWWorks-org/mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "app-store-screenshots",
+    "screenshot-generator",
+    "appscreenshotstudio",
+    "ai-tools"
+  ],
+  "bin": {
+    "appscreenshotstudio-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ]
+}

package/skills/appscreenshotstudio/SKILL.md

@@ -68,12 +68,13 @@ Call the `generate-screenshots` MCP tool with:
 - `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
+- `images`: local file paths of real app screenshots (placed inside the device frames automatically, in order) and/or the app's mascot with `kind: "mascot"` (placed peeking from behind the hook card's phone and on the closing card; transparent PNG). If screenshots exist in the repo (fastlane/screenshots, store assets, README images), attach them here so the set comes back with real UI in the phones instead of empty frames.
 
 ### Step 4: Upload App Screenshots
 
-If the user has actual app screenshots (from Simulator, emulator, or screen captures), upload them into the device frames using `upload-screenshots`:
+If screenshots were attached in Step 3 they are already in the frames — this step covers swaps and late additions. `upload-screenshots`:
 - Takes local file paths and maps them to card indices
-- Fills the empty device mockups with real app UI
+- Fills or replaces the device mockups' app UI per card
 - Free — no credit cost
 
 ### Step 5: Show and Iterate (the core loop)
@@ -91,7 +92,7 @@ Hand off to the builder only when it genuinely helps: share the project URL and
 
 ### Step 6: Export
 
-`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.
+`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 and note they stay valid for 7 days, so download promptly (re-rendering later is free if a URL has expired). The builder project URL is the alternative when they want to compare the full set visually or hand-tweak before downloading.
 
 ## Headline Rules