@appscreenshotstudio/mcp 0.8.6 → 0.8.7

package/README.md

@@ -95,6 +95,9 @@ Attach local image files as `{ file_path, kind }`. Max 5 per call. The `kind` de
 | `screenshot` (default) | Your real app UI, straight from a simulator or device | Inside the generated device frames, in attachment order |
 | `mascot` | Your app's character or logo creature | Decoratively around the phones (peeking from behind the hook card, beside the closing card). Use a transparent PNG |
 | `reference` | A look to **match**: a competitor's App Store listing, a design the user pointed you at, any image that already shows a phone with a headline above it | Nowhere. It is read for palette, type weight, headline length and composition, and never placed in a frame |
+| `background` | The user's own photo: an arena, a product shot, a brand photo, a still from their video | **Behind** the cards. One photo becomes one panorama across the first three cards (or the cards your message names, e.g. "across all of them"); several become one per card, in attachment order. Free: the photo is cut to fit, nothing is generated |
+
+The images in one call must stay under about 4MB encoded. The tool does not resize, and a photo straight off a camera is often bigger, so shrink it first (a 3840px long edge at JPEG quality 85 is plenty). An oversized call is refused before anything is sent, with no credits spent.
 
 **Do not send a competitor's store screenshots as `screenshot`.** They are finished marketing cards, so putting one inside a device frame nests a phone inside a phone and ships someone else's artwork into your listing. If the user says "make it look like this app" and hands you that app's listing, it is `reference`. Their own raw captures are `screenshot`. One call can carry both, and the reference ones are simply skipped when the frames get filled.
 
@@ -265,7 +268,7 @@ Full policy: [appscreenshotstudio.com/privacy](https://appscreenshotstudio.com/p
 
 **Retention.** Projects persist in your account until you delete them. Rendered PNG download URLs expire after 7 days.
 
-**Contact.** [support@kindlebookillustrations.com](mailto:support@kindlebookillustrations.com)
+**Contact.** [contact@bookillustrationai.com](mailto:contact@bookillustrationai.com)
 
 ## Links
 

package/dist/index.js

@@ -168,6 +168,21 @@ function buildDesignMessage(input, hasScreenshotImages = false) {
     parts.push(`Please include projectMeta with brand colors, mood, appCategory, and a rich globalVisualTheme description.`);
     return parts.join('\n');
 }
+/**
+ * Characters of image data one chat call may carry. The server sits behind a
+ * 4.5MB request-body limit that rejects the call before it runs, so an agent
+ * sees a bare failure. This package does not resize (no image library), and a
+ * background photo straight off a camera is several MB, so say so up front.
+ */
+const CHAT_IMAGE_BUDGET_CHARS = 4_000_000;
+/** A message telling the agent how to fit, or null when the images fit. */
+function imagesOverBudget(payload) {
+    const total = payload.reduce((n, img) => n + img.dataUrl.length, 0);
+    if (total <= CHAT_IMAGE_BUDGET_CHARS)
+        return null;
+    return `The attached images are ${(total / 1e6).toFixed(1)}MB encoded, over the ${(CHAT_IMAGE_BUDGET_CHARS / 1e6).toFixed(1)}MB one call can carry, so nothing was sent and no credits were spent. `
+        + 'Shrink them first, e.g. to a 3840px long edge as JPEG quality 85 (macOS: sips -Z 3840 -s format jpeg in.png --out out.jpg; ImageMagick: magick in.png -resize "3840x3840>" -quality 85 out.jpg), or send background photos in a call of their own.';
+}
 function readImagesForChat(images) {
     const payload = [];
     const errors = [];
@@ -193,10 +208,10 @@ function readImagesForChat(images) {
 /** 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', 'reference']).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. 'reference' = a look to match rather than content: a competitor's App Store listing, a design you want the style of, any image that already shows a phone with a headline above it. A reference is read for taste and is NEVER placed inside a frame, which is the point: wrapping a finished marketing card in a device frame puts a phone inside a phone."),
+    kind: z.enum(['screenshot', 'mascot', 'reference', 'background']).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. 'reference' = a look to match rather than content: a competitor's App Store listing, a design you want the style of, any image that already shows a phone with a headline above it. A reference is read for taste and is NEVER placed inside a frame, which is the point: wrapping a finished marketing card in a device frame puts a phone inside a phone. 'background' = the user's own photo, placed BEHIND the cards: one background photo becomes one panorama across a group of cards (the first three, or the cards the message names, e.g. \"across all of them\"), several become one per card in attachment order. Free, nothing is generated; cards the photo lands on get a dark band and light text so the words stay readable."),
 })).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; a reference only informs the design. All survive later edits and regenerations.');
+    .describe('Images to attach to this generation. App screenshots land inside the device frames automatically; a mascot gets placed around the phones; a reference only informs the design; a background photo goes behind the cards. All survive later edits and regenerations. Together they must stay under about 4MB encoded: this tool does not resize, so shrink camera photos first.');
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 // Read from package.json rather than a literal. This is the version a client
 // sees in the MCP handshake, and a hand-synced literal silently sat at 0.6.1
@@ -216,7 +231,7 @@ server.registerTool('generate-screenshots', {
         destructiveHint: false,
         openWorldHint: false,
     },
-    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.
+    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; attach the user's own photo (kind: "background") and it goes behind the cards, one photo as a panorama or several as one per card. 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.
 
@@ -297,6 +312,13 @@ Costs 5 credits per generation.`,
     if ('error' in resolved) {
         return { content: [{ type: 'text', text: resolved.error }] };
     }
+    // Read the images before anything is created, so an oversized attachment
+    // fails here instead of leaving an empty project behind.
+    const { payload: chatImages, errors: imageErrors } = readImagesForChat(input.images);
+    const tooBig = imagesOverBudget(chatImages);
+    if (tooBig) {
+        return { content: [{ type: 'text', text: tooBig }] };
+    }
     // Step 1: Create project (with codebase context if provided)
     const projectName = `${input.app_name} Screenshots`;
     const createBody = {
@@ -316,7 +338,6 @@ Costs 5 credits per generation.`,
     const projectId = project.id;
     // 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`, {
@@ -375,7 +396,7 @@ server.registerTool('edit-screenshots', {
         destructiveHint: true,
         openWorldHint: false,
     },
-    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.
+    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, and a background photo (kind: "background") goes behind the cards, one photo as a panorama or several as one per card.
 
 What you can change:
 - Text: headlines, subtitles, badge text, font size, font family (Inter, Poppins, Montserrat, DM Sans, Space Grotesk, etc.)
@@ -455,6 +476,10 @@ Example edit messages:
         }
     }
     const { payload: chatImages, errors: imageErrors } = readImagesForChat(images);
+    const tooBig = imagesOverBudget(chatImages);
+    if (tooBig) {
+        return { content: [{ type: 'text', text: tooBig }] };
+    }
     const res = await apiCall('POST', `/api/v1/projects/${project_id}/chat`, {
         message: enrichedMessage,
         selected_card_indices: card_indices || [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "mcpName": "com.appscreenshotstudio/mcp",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",

package/skills/appscreenshotstudio/SKILL.md

@@ -68,10 +68,11 @@ 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, each tagged with a `kind`. Three kinds, three destinations:
+- `images`: local file paths, each tagged with a `kind`. Four kinds, four destinations:
   - `kind: "screenshot"` (default): real app UI, placed inside the device frames automatically, in order. 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.
   - `kind: "mascot"`: the app's character, placed peeking from behind the hook card's phone and on the closing card. Transparent PNG.
   - `kind: "reference"`: a look to **match**, never placed in a frame. Use this for a competitor's App Store listing, a design the user pointed you at, or any image that already shows a phone with a headline above it. It is read for palette, type weight, headline length and composition.
+  - `kind: "background"`: the user's own photo, placed BEHIND the cards. One photo becomes a panorama across the first three cards (or the cards your message names); several become one per card, in order. Use it when the user wants their own arena, product or brand photo as the backdrop. Keep all images in a call under about 4MB encoded: shrink camera photos first (3840px long edge, JPEG).
 
 **Do not tag a competitor's store screenshots as `screenshot`.** They are finished marketing cards, so placing one inside a device frame nests a phone inside a phone and ships someone else's artwork. If the user says "make it look like X" and hands you X's listing, that is `kind: "reference"`. Their own raw captures are `kind: "screenshot"`, and a message can carry both.