@appscreenshotstudio/mcp 0.5.3 → 0.5.5

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.5',
 });
 // 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,26 +425,34 @@ 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;
     const creditsRemaining = res.data.credits_remaining;
+    // A device switch ("make this for iPad") clones the project. All further
+    // edits, uploads, and renders must target the NEW project id, not the old one.
+    const activeProjectId = data.duplicated_project_id || project_id;
     return {
         content: [{
                 type: 'text',
                 text: [
                     data.message,
                     '',
+                    data.duplicated_project_id
+                        ? `NEW PROJECT CREATED at the target device size: ${data.duplicated_project_id}\nUse this project_id for all further edits, screenshot uploads, and rendering. The original project (${project_id}) is unchanged.`
+                        : '',
                     `Cards: ${data.canvas_state?.cards?.length || 0}`,
                     `Credits remaining: ${creditsRemaining}`,
-                    `Project URL: ${API_BASE}/builder/${project_id}`,
+                    `Project URL: ${API_BASE}/builder/${activeProjectId}`,
                     '',
                     data.suggestions?.length
                         ? `Suggestions: ${data.suggestions.join(', ')}`

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@appscreenshotstudio/mcp",
-  "version": "0.5.3",
-  "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"
-  ]
-}
+{
+  "name": "@appscreenshotstudio/mcp",
+  "version": "0.5.5",
+  "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)