@appscreenshotstudio/mcp 0.1.2 → 0.1.3

package/README.md

@@ -63,12 +63,13 @@ Create a complete set of App Store screenshots. One tool call = one full project
 
 ### `edit-screenshots`
 
-Make changes to an existing project with natural language.
+Make changes to an existing project with natural language. Optionally target specific cards.
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
 | `project_id` | string | Yes | From a previous `generate-screenshots` call |
 | `message` | string | Yes | What to change |
+| `card_indices` | number[] | No | Target specific cards by index (0-based). Omit to edit all. |
 
 **Costs 1 credit.**
 
@@ -82,6 +83,28 @@ Export to high-resolution PNGs. Returns download URLs.
 
 **Free.**
 
+### `get-project`
+
+Retrieve a project's current state — cards, elements, backgrounds, and metadata.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project ID to retrieve |
+
+**Free.**
+
+### `generate-background`
+
+Generate an AI background for a specific card. Uses project metadata (brand colors, mood, theme) for contextual results.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project containing the card |
+| `card_index` | number | Yes | Which card (0-based) |
+| `prompt` | string | Yes | Description of the background |
+
+**Costs 1 credit.**
+
 ### `list-devices`
 
 Show all supported device specs. No API call needed.
@@ -96,9 +119,6 @@ Show all supported device specs. No API call needed.
 | `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
 | `android-phone` | Android Phone | 1080x2340 | Play Store |
 | `android-tablet-10` | Android Tablet 10" | 2560x1600 | Play Store |
-| `iphone-5.5` | iPhone 8 Plus | 1242x2208 | Optional |
-| `ipad-12.9` | iPad Pro 12.9" | 2048x2732 | Optional |
-| `ipad-11` | iPad Pro 11" | 1668x2388 | Optional |
 
 ## Workflow
 

package/dist/index.js

@@ -7,10 +7,7 @@ const API_KEY = process.env.APPSCREENSHOTSTUDIO_API_KEY;
 // ─── Devices (mirrors lib/device-specs.ts) ─────────────────────────────────────
 const DEVICES = [
     { id: 'iphone-6.9', name: 'iPhone 16 Pro Max', width: 1260, height: 2736, category: 'iphone', required: true },
-    { id: 'iphone-5.5', name: 'iPhone 8 Plus', width: 1242, height: 2208, category: 'iphone', required: false },
     { id: 'ipad-13', name: 'iPad Pro 13"', width: 2064, height: 2752, category: 'ipad', required: true },
-    { id: 'ipad-12.9', name: 'iPad Pro 12.9"', width: 2048, height: 2732, category: 'ipad', required: false },
-    { id: 'ipad-11', name: 'iPad Pro 11"', width: 1668, height: 2388, category: 'ipad', required: false },
     { id: 'android-phone', name: 'Android Phone', width: 1080, height: 2340, category: 'android-phone', required: true },
     { id: 'android-tablet-10', name: 'Android Tablet 10"', width: 2560, height: 1600, category: 'android-tablet', required: true },
 ];
@@ -79,7 +76,26 @@ const server = new McpServer({
 // 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. Generates multiple cards with headlines, backgrounds, device mockups, and a cohesive story flow. Returns a project URL where the developer can upload their actual app screenshots into the device frames and export final PNGs.',
+    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.
+
+Each card is a layered composition with: gradient background, decorative glow orbs, bold headline with colored accent words, device mockup (iPhone/iPad/Android with perspective tilts), and optional floating elements (badges, star ratings, UI snippets).
+
+Available layouts per card:
+- Layout A: "Text Top, Device Bottom Center" — default, device fills lower portion
+- Layout B: "Text Top, Device Offset Right" — tilted phone with perspective
+- Layout C: "Social Proof" — star rating + quote + badge + device
+- Layout M1-M4: Marketing cards WITHOUT device (title cards, feature callouts, CTAs, testimonials)
+
+Card types the system can generate:
+- Hero card (value proposition + device)
+- Feature spotlight (tilted phone + floating UI snippets)
+- Social proof (stars, quotes, badges)
+- Marketing/title card (no device, bold text + rich background)
+- CTA/download card (no device, call to action)
+
+App Store 60/40 rule: minimum 60% of cards must show a device mockup, maximum 40% can be marketing-only.
+
+Costs 1 credit per generation.`,
     inputSchema: z.object({
         app_name: z.string().describe('Name of the app'),
         app_description: z.string().describe('What the app does — 1-3 sentences'),
@@ -154,15 +170,37 @@ server.registerTool('generate-screenshots', {
 // 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 — e.g. "make the headlines bigger", "change the color scheme to blue", "add a social proof card".',
+    description: `Make changes to an existing screenshot project. Use natural language to describe what you want to change. Costs 1 credit per edit.
+
+What you can change:
+- Text: headlines, subtitles, badge text, font size, font family (Inter, Poppins, Montserrat, DM Sans, Space Grotesk, etc.)
+- Colors: brand palette, gradient backgrounds, accent colors, text colors
+- Layout: reposition elements, switch between layouts (A/B/C/M1-M4), change device tilt
+- Device mockups: perspective tilts (flat, left-15, right-15), resize, reposition
+- Add/remove cards: add a social proof card, remove card 3, add a marketing title card
+- Floating elements: add/edit badges, star ratings, floating UI snippets (rounded-rect + text overlays)
+- Shapes: glow orbs, waves, blobs, rounded rectangles, circles, custom SVG paths
+- Backgrounds: change gradient colors/angle, set a backgroundPrompt for AI-generated backgrounds
+- Style: shadows, opacity, border radius, rotation, blur
+
+Example edit messages:
+- "Make the headlines larger and use Bebas Neue font"
+- "Change the color scheme to blue (#2563EB) across all cards"
+- "Add a social proof card with 5 stars and a testimonial quote"
+- "Tilt the phone on card 2 to the left"
+- "Add floating UI snippets around the device on card 1"
+- "Replace card 3 with a marketing CTA card saying Download Free"
+- "Add a wave shape flowing across all cards"`,
     inputSchema: z.object({
         project_id: z.string().describe('Project ID from a previous generate-screenshots call'),
         message: z.string().describe('What to change — use natural language'),
+        card_indices: z.array(z.number()).optional()
+            .describe('Target specific cards by index (0-based). e.g. [0] for card 1, [2,3] for cards 3-4. Omit to apply changes to all cards.'),
     }),
-}, async ({ project_id, message }) => {
+}, async ({ project_id, message, card_indices }) => {
     const res = await apiCall('POST', `/api/v1/projects/${project_id}/chat`, {
         message,
-        selected_card_indices: [],
+        selected_card_indices: card_indices || [],
     });
     if (!res.ok) {
         return {
@@ -191,7 +229,7 @@ server.registerTool('edit-screenshots', {
 // Tool 3: render-screenshots
 server.registerTool('render-screenshots', {
     title: 'Render Screenshots to PNG',
-    description: 'Export a screenshot project to high-resolution PNG files. Returns download URLs for each card. Note: device mockups will be empty unless screenshots have been uploaded via the web app 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. Note: device mockups will show empty frames unless app screenshots have been uploaded via the web app first.',
     inputSchema: z.object({
         project_id: z.string().describe('Project ID to render'),
     }),
@@ -235,6 +273,97 @@ server.registerTool('list-devices', {
             }],
     };
 });
+// Tool 5: get-project
+server.registerTool('get-project', {
+    title: 'Get Project Details',
+    description: `Retrieve the full state of a screenshot project, including all cards and their elements. Use this to inspect what was generated before making edits. Free — no credit cost.
+
+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 highlights)
+- Device mockups: perspectiveVariant (flat, left-15, right-15), screenshotImage (null if no upload)
+- Shapes: shapeType (circle, rectangle, rounded-rect, blob, wave, etc.), fill, opacity
+- projectMeta: globalVisualTheme, brandColors, mood, appCategory`,
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID to inspect'),
+    }),
+}, async ({ project_id }) => {
+    const res = await apiCall('GET', `/api/v1/projects/${project_id}`);
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Failed to get project: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const project = res.data.data;
+    // Build a concise summary instead of dumping raw JSON
+    const cardSummaries = project.canvas_state?.cards?.map((card, i) => {
+        const elementTypes = card.elements.map(el => el.type);
+        const typeCounts = {};
+        for (const t of elementTypes) {
+            typeCounts[t] = (typeCounts[t] || 0) + 1;
+        }
+        const typeStr = Object.entries(typeCounts).map(([t, c]) => `${c} ${t}`).join(', ');
+        return `  Card ${i} (${card.id}): ${card.elements.length} elements — ${typeStr}`;
+    }) || [];
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `Project: ${project.name}`,
+                    `ID: ${project.id}`,
+                    `Device: ${project.device_id}`,
+                    `Cards: ${project.canvas_state?.cards?.length || 0}`,
+                    '',
+                    ...cardSummaries,
+                    '',
+                    `Project URL: ${API_BASE}/builder/${project.id}`,
+                    '',
+                    `Full canvas state:`,
+                    JSON.stringify(project.canvas_state, null, 2),
+                ].join('\n'),
+            }],
+    };
+});
+// Tool 6: generate-background
+server.registerTool('generate-background', {
+    title: 'Generate AI Background',
+    description: `Generate an AI background image for a specific card using Gemini. The background is generated based on a text prompt and applied directly to the card. Costs 1 credit.
+
+Good prompts describe mood, lighting, and color — not objects or text:
+- "Deep purple nebula with soft pink and blue light rays"
+- "Warm sunset gradient with golden bokeh particles"
+- "Dark moody atmosphere with teal and emerald glow"
+- "Clean minimal white-to-light-gray gradient with subtle noise texture"
+
+The generated image is cropped to exact device dimensions and set as the card's background.`,
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID'),
+        card_index: z.number().describe('Card index (0-based) to apply the background to'),
+        prompt: z.string().describe('Background description — describe mood, lighting, colors, textures. Do NOT include text, devices, or UI elements.'),
+    }),
+}, async ({ project_id, card_index, prompt }) => {
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/generate-background`, {
+        card_index,
+        prompt,
+    });
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Background generation failed: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const creditsRemaining = res.data.credits_remaining;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `AI background generated and applied to card ${card_index + 1}.`,
+                    `Credits remaining: ${creditsRemaining}`,
+                    `Project URL: ${API_BASE}/builder/${project_id}`,
+                ].join('\n'),
+            }],
+    };
+});
 // ─── Start server ───────────────────────────────────────────────────────────────
 async function main() {
     if (!API_KEY) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",