@appscreenshotstudio/mcp 0.1.4 → 0.2.0

package/README.md

@@ -59,7 +59,7 @@ Create a complete set of App Store screenshots. One tool call = one full project
 | `count` | number | No | Number of cards, 3-10 (default: 5) |
 | `story_flow` | string | No | Narrative structure (default: `auto`) |
 
-**Costs 1 credit.**
+**Costs 5 credits.**
 
 ### `edit-screenshots`
 
@@ -71,7 +71,7 @@ Make changes to an existing project with natural language. Optionally target spe
 | `message` | string | Yes | What to change |
 | `card_indices` | number[] | No | Target specific cards by index (0-based). Omit to edit all. |
 
-**Costs 1 credit.**
+**Costs 5 credits.**
 
 ### `render-screenshots`
 
@@ -103,7 +103,7 @@ Generate an AI background for a specific card. Uses project metadata (brand colo
 | `card_index` | number | Yes | Which card (0-based) |
 | `prompt` | string | Yes | Description of the background |
 
-**Costs 1 credit.**
+**Costs 6 credits.**
 
 ### `list-devices`
 
@@ -120,6 +120,17 @@ Show all supported device specs. No API call needed.
 | `android-phone` | Android Phone | 1080x2340 | Play Store |
 | `android-tablet-10` | Android Tablet 10" | 2560x1600 | Play Store |
 
+## Design Features
+
+The AI generates professional screenshots using:
+
+- **78+ decorative shapes** across 13 categories: nature (leaf, flower, tree), weather (cloud, sun, snowflake), celebration (sparkle, trophy, crown, confetti), social (chat-bubble, music-note), tech (rocket, code-bracket), health (dumbbell, flame), food (coffee-cup, pizza), travel (airplane, compass), finance (dollar-sign, piggy-bank), education (graduation-cap, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji), abstract (swirl, infinity, gem)
+- **Rich text**: per-word color, bold, italic, underline, highlight pills (colored backgrounds behind words), gradient fills, text stroke outlines, emoji
+- **Laurel stats**: wing-left + wing-right shapes flanking stats like "4.9 Rating" or "1M+ Users"
+- **Floating UI snippets**: rounded-rect panels with text overlapping device edges
+- **11 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, flat-lay, side-profile, landscape-left, landscape-right
+- **7 layouts**: Text Top + Device Center (A), Text Top + Device Offset (B), Social Proof (C), Marketing Title (M1), Feature Callout (M2), CTA (M3), Testimonial (M4)
+
 ## Workflow
 
 1. **Generate** — Agent calls `generate-screenshots` with your app details

package/dist/index.js

@@ -64,6 +64,36 @@ function buildDesignMessage(input) {
     if (input.story_flow && input.story_flow !== 'auto') {
         parts.push(`\nStory flow: ${input.story_flow} (${STORY_FLOW_DESCRIPTIONS[input.story_flow] || input.story_flow})`);
     }
+    if (input.codebase_context) {
+        const ctx = input.codebase_context;
+        parts.push('\n--- App Research Context (from codebase analysis) ---');
+        if (ctx.readme_summary)
+            parts.push(`App overview: ${ctx.readme_summary}`);
+        if (ctx.key_screens?.length) {
+            parts.push('Key screens in the app:');
+            for (const screen of ctx.key_screens)
+                parts.push(`  - ${screen}`);
+        }
+        if (ctx.color_tokens && Object.keys(ctx.color_tokens).length) {
+            parts.push(`Theme colors from code: ${JSON.stringify(ctx.color_tokens)}`);
+        }
+        if (ctx.target_audience)
+            parts.push(`Target audience: ${ctx.target_audience}`);
+        if (ctx.app_category)
+            parts.push(`App category: ${ctx.app_category}`);
+        if (ctx.competitive_edge)
+            parts.push(`What makes it unique: ${ctx.competitive_edge}`);
+        if (ctx.app_store_description)
+            parts.push(`Existing store description: ${ctx.app_store_description}`);
+        if (ctx.tech_stack)
+            parts.push(`Tech stack: ${ctx.tech_stack}`);
+        if (ctx.ui_style)
+            parts.push(`UI style: ${ctx.ui_style}`);
+        if (ctx.primary_user_flow)
+            parts.push(`Primary user flow: ${ctx.primary_user_flow}`);
+        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.`);
     parts.push(`Please include projectMeta with brand colors, mood, appCategory, and a rich globalVisualTheme description.`);
     return parts.join('\n');
@@ -78,6 +108,8 @@ 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.
 
+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.
+
 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:
@@ -89,13 +121,19 @@ Available layouts per card:
 Card types the system can generate:
 - Hero card (value proposition + device)
 - Feature spotlight (tilted phone + floating UI snippets)
-- Social proof (stars, quotes, badges)
+- Social proof (stars, quotes, badges, laurel wings with stats)
 - Marketing/title card (no device, bold text + rich background)
 - CTA/download card (no device, call to action)
 
+Design features:
+- 78+ decorative shapes across 13 categories (nature, weather, celebration, social, tech, health, food, travel, abstract, finance, education, pets, emoji)
+- Rich text with per-word color, weight, italic, underline, highlight pills, gradient fills, stroke outlines, and emoji
+- Laurel stats pattern: wing-left + wing-right shapes flanking stats like "4.9 Rating" or "1M+ Users"
+- Floating UI snippets: rounded-rect panels with text overlapping the device edges
+
 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.`,
+Costs 5 credits 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'),
@@ -114,14 +152,41 @@ Costs 1 credit per generation.`,
             .describe('Number of screenshot cards to generate (3-10). Default: 5'),
         story_flow: z.enum(['auto', 'standard', 'problem-solution', 'social-proof', 'benefit-first', 'journey', 'hero-intro', 'social-proof-bookend']).default('auto')
             .describe('Narrative structure for the screenshots. "auto" lets the AI choose the best flow.'),
+        codebase_context: z.object({
+            readme_summary: z.string().optional()
+                .describe('Summary of the app from README or docs — what does it do and why?'),
+            key_screens: z.array(z.string()).max(15).optional()
+                .describe('Main screens/views in the app — e.g. "Dashboard with activity feed", "Settings with theme toggle"'),
+            color_tokens: z.record(z.string()).optional()
+                .describe('Brand/theme colors found in code — e.g. {"primary": "#7C3AED", "background": "#0F172A"}'),
+            target_audience: z.string().optional()
+                .describe('Who the app is for — e.g. "busy professionals who want to track habits"'),
+            app_category: z.string().optional()
+                .describe('App category — e.g. fitness, finance, social, productivity, food, travel, health, education'),
+            competitive_edge: z.string().optional()
+                .describe('What makes this app unique vs competitors'),
+            app_store_description: z.string().optional()
+                .describe('Existing App Store/Play Store description if found in the codebase'),
+            tech_stack: z.string().optional()
+                .describe('Tech stack — e.g. "React Native", "SwiftUI", "Flutter". Useful for developer-tool apps.'),
+            ui_style: z.string().optional()
+                .describe('UI style observations — e.g. "dark mode with neon accents", "clean minimal with lots of whitespace"'),
+            primary_user_flow: z.string().optional()
+                .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.'),
     }),
 }, async (input) => {
-    // Step 1: Create project
+    // Step 1: Create project (with codebase context if provided)
     const projectName = `${input.app_name} Screenshots`;
-    const createRes = await apiCall('POST', '/api/v1/projects', {
+    const createBody = {
         device_id: input.device_id,
         name: projectName,
-    });
+    };
+    if (input.codebase_context) {
+        createBody.codebase_context = input.codebase_context;
+    }
+    const createRes = await apiCall('POST', '/api/v1/projects', createBody);
     if (!createRes.ok) {
         return {
             content: [{ type: 'text', text: `Failed to create project: ${JSON.stringify(createRes.data)}` }],
@@ -170,16 +235,19 @@ Costs 1 credit 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 1 credit 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.
 
 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
 - 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
+- Decorative shapes: 78+ library shapes — leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, and many more across 13 categories
+- Laurel stats: wing-left + wing-right shapes flanking a stat (e.g. "4.9 Rating", "1M+ Users", "#1 App")
 - Backgrounds: change gradient colors/angle, set a backgroundPrompt for AI-generated backgrounds
 - Style: shadows, opacity, border radius, rotation, blur
 
@@ -190,16 +258,51 @@ Example edit messages:
 - "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"`,
+- "Add a wave shape flowing across all cards"
+- "Add laurel wings around a 4.9 rating on card 1"
+- "Add decorative leaf and sparkle shapes scattered in the background"
+- "Make 'Every' underlined and italic in the headline"`,
     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.'),
+        codebase_context: z.object({
+            readme_summary: z.string().optional(),
+            key_screens: z.array(z.string()).max(15).optional(),
+            color_tokens: z.record(z.string()).optional(),
+            target_audience: z.string().optional(),
+            app_category: z.string().optional(),
+            competitive_edge: z.string().optional(),
+            app_store_description: z.string().optional(),
+            tech_stack: z.string().optional(),
+            ui_style: z.string().optional(),
+            primary_user_flow: z.string().optional(),
+        }).optional()
+            .describe('App context from codebase research. Helps the AI make edits that match the actual app.'),
     }),
-}, async ({ project_id, message, card_indices }) => {
+}, async ({ project_id, message, card_indices, codebase_context }) => {
+    let enrichedMessage = message;
+    if (codebase_context) {
+        const ctxParts = [];
+        if (codebase_context.readme_summary)
+            ctxParts.push(`App: ${codebase_context.readme_summary}`);
+        if (codebase_context.key_screens?.length)
+            ctxParts.push(`Screens: ${codebase_context.key_screens.join(', ')}`);
+        if (codebase_context.color_tokens)
+            ctxParts.push(`Colors: ${JSON.stringify(codebase_context.color_tokens)}`);
+        if (codebase_context.target_audience)
+            ctxParts.push(`Audience: ${codebase_context.target_audience}`);
+        if (codebase_context.ui_style)
+            ctxParts.push(`UI style: ${codebase_context.ui_style}`);
+        if (codebase_context.competitive_edge)
+            ctxParts.push(`Unique: ${codebase_context.competitive_edge}`);
+        if (ctxParts.length) {
+            enrichedMessage = `[App context: ${ctxParts.join('. ')}]\n\n${message}`;
+        }
+    }
     const res = await apiCall('POST', `/api/v1/projects/${project_id}/chat`, {
-        message,
+        message: enrichedMessage,
         selected_card_indices: card_indices || [],
     });
     if (!res.ok) {
@@ -281,9 +384,9 @@ server.registerTool('get-project', {
 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
+- 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, flat-lay, side-profile, landscape-left, landscape-right), screenshotImage (null if no upload)
+- Shapes: 78+ shape types 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({
         project_id: z.string().describe('Project ID to inspect'),
@@ -328,7 +431,7 @@ Returns the canvas state with:
 // 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.
+    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 6 credits.
 
 Good prompts describe mood, lighting, and color — not objects or text:
 - "Deep purple nebula with soft pink and blue light rays"
@@ -364,6 +467,370 @@ The generated image is cropped to exact device dimensions and set as the card's
             }],
     };
 });
+// Tool 7: prepare-screenshot-brief
+server.registerTool('prepare-screenshot-brief', {
+    title: 'Prepare Screenshot Brief',
+    description: `Get a research checklist and strategy guide to prepare for screenshot generation. Call this BEFORE generate-screenshots to know what to look for in the codebase. Free — no API call or credits needed.
+
+Returns:
+- A codebase research checklist (file patterns to search for each tech stack)
+- Story flow recommendations by app category
+- Tips for writing compelling screenshot headlines
+- The codebase_context schema to fill in
+
+This tool helps you gather the right information so generate-screenshots produces the best possible output on the first try.`,
+    inputSchema: z.object({
+        app_category: z.string().optional()
+            .describe('App category if known — e.g. fitness, finance, social, productivity, developer-tools'),
+        platform: z.enum(['ios', 'android', 'both']).default('ios')
+            .describe('Target platform'),
+    }),
+}, async ({ app_category, platform }) => {
+    const checklist = [
+        '# Screenshot Brief — Research Checklist',
+        '',
+        'Search the codebase for each of these before calling generate-screenshots.',
+        'The more you find, the better the screenshots will be.',
+        '',
+        '## 1. App Identity (REQUIRED)',
+        '',
+        '**Find the app name and description:**',
+        '- package.json → "name", "description"',
+        '- README.md → first paragraph, badges, tagline',
+        '- pubspec.yaml → "name", "description" (Flutter)',
+        '- build.gradle / app/build.gradle → applicationId, versionName (Android)',
+        '- Info.plist / *.xcodeproj → CFBundleDisplayName (iOS native)',
+        '- Cargo.toml → "name", "description" (Rust)',
+        '- pyproject.toml / setup.py → name, description (Python)',
+        '',
+        '**Find the value proposition:**',
+        '- Landing page / marketing page components → hero headline, subheadline',
+        '- README.md → "Features" or "Why" section',
+        '- App Store metadata files (fastlane/metadata/) → description, keywords',
+        '',
+        '## 2. Features & Screens (REQUIRED)',
+        '',
+        '**Find the main screens:**',
+        '- Route definitions: look for Router, Navigator, routes.ts, app.tsx routing',
+        '- Page/screen directories: pages/, screens/, views/, app/ (Next.js)',
+        '- Navigation config: tabs, drawer items, bottom nav',
+        '',
+        '**Find key features:**',
+        '- README.md → feature list, bullet points',
+        '- Settings/preferences screen → feature toggles reveal capabilities',
+        '- Changelog/release notes → recent features',
+        '',
+        '## 3. Visual Identity (HIGHLY RECOMMENDED)',
+        '',
+        '**Find brand colors:**',
+        '- tailwind.config.* → theme.extend.colors',
+        '- theme.ts, colors.ts, tokens.ts → color definitions',
+        '- CSS variables: :root { --primary: ... }',
+        '- styles/globals.css, variables.css → custom properties',
+        '- SwiftUI: Color.accentColor, Asset catalog colors',
+        '- Flutter: ThemeData, ColorScheme',
+        '- Android: colors.xml, themes.xml',
+        '',
+        '**Find fonts:**',
+        '- Font imports in layout/root files',
+        '- Google Fonts imports, @font-face declarations',
+        '- Typography config in theme files',
+        '',
+        '**Observe UI style:**',
+        '- Dark mode / light mode support?',
+        '- Design system: shadcn/ui, Material, Cupertino, custom?',
+        '- Dense or spacious layout?',
+        '- Rounded or sharp corners?',
+        '',
+        '## 4. Market Context (NICE TO HAVE)',
+        '',
+        '- Target audience mentions in docs, README, marketing copy',
+        '- Competitor references in code comments or docs',
+        '- Analytics/tracking events → reveal most-used features',
+        '- Testimonials or reviews referenced in code',
+        '- Social proof data (user counts, ratings)',
+        '',
+        '## 5. User Flow (NICE TO HAVE)',
+        '',
+        '- Onboarding screens → what the app teaches users first',
+        '- Auth flow → sign up with email, social, magic link?',
+        '- Main navigation → what users do most',
+        '- Key interactions → what makes the app satisfying to use',
+    ];
+    // Story flow recommendations
+    const storyFlows = [
+        '',
+        '---',
+        '',
+        '# Story Flow Recommendations',
+        '',
+    ];
+    const categoryRecommendations = {
+        'fitness': [
+            '**Fitness apps → `journey` or `benefit-first`**',
+            '- Lead with transformation: "Before → After" or "Track → Improve → Achieve"',
+            '- Highlight: workout tracking, progress charts, streaks, community challenges',
+            '- Mood: energetic or bold',
+        ],
+        'finance': [
+            '**Finance apps → `benefit-first` or `problem-solution`**',
+            '- Lead with outcomes: "Save $X/month" or "See all accounts in one place"',
+            '- Highlight: dashboards, charts, budgets, alerts, security',
+            '- Mood: professional or calm',
+        ],
+        'social': [
+            '**Social apps → `social-proof-bookend` or `hero-intro`**',
+            '- Lead with community: "Join 1M+ users" or show vibrant UI',
+            '- Highlight: feed, messaging, profiles, discovery, sharing',
+            '- Mood: playful or energetic',
+        ],
+        'productivity': [
+            '**Productivity apps → `problem-solution` or `standard`**',
+            '- Lead with pain point: "Stop juggling 5 apps" → "One place for everything"',
+            '- Highlight: task management, collaboration, integrations, speed',
+            '- Mood: minimal or professional',
+        ],
+        'food': [
+            '**Food/recipe apps → `hero-intro` or `journey`**',
+            '- Lead with beautiful imagery or the discovery experience',
+            '- Highlight: recipe browsing, meal planning, grocery lists, cooking mode',
+            '- Mood: warm or playful',
+        ],
+        'travel': [
+            '**Travel apps → `journey` or `hero-intro`**',
+            '- Lead with destination discovery or trip planning flow',
+            '- Highlight: search, booking, itinerary, maps, offline access',
+            '- Mood: energetic or calm',
+        ],
+        'health': [
+            '**Health/wellness apps → `benefit-first` or `journey`**',
+            '- Lead with outcomes: "Sleep better", "Feel calmer", "Know your body"',
+            '- Highlight: tracking, insights, reminders, progress, professional guidance',
+            '- Mood: calm or professional',
+        ],
+        'education': [
+            '**Education apps → `journey` or `hero-intro`**',
+            '- Lead with learning progression or "learn anything" hero',
+            '- Highlight: courses, progress tracking, quizzes, certificates, offline',
+            '- Mood: playful or professional',
+        ],
+        'developer-tools': [
+            '**Developer tools → `problem-solution` or `benefit-first`**',
+            '- Lead with workflow pain: "Stop copy-pasting" → "One command and done"',
+            '- Highlight: CLI, integrations, speed, DX, code examples',
+            '- Mood: minimal or bold',
+        ],
+        'shopping': [
+            '**Shopping/e-commerce → `social-proof-bookend` or `benefit-first`**',
+            '- Lead with deals or trust: "Trusted by 500K+ shoppers"',
+            '- Highlight: discovery, search, wishlists, checkout, tracking',
+            '- Mood: bold or energetic',
+        ],
+    };
+    if (app_category && categoryRecommendations[app_category]) {
+        storyFlows.push(...categoryRecommendations[app_category]);
+    }
+    else {
+        storyFlows.push('**General recommendations by app type:**', '');
+        for (const [, lines] of Object.entries(categoryRecommendations)) {
+            storyFlows.push(...lines, '');
+        }
+    }
+    // Headline tips
+    const headlineTips = [
+        '',
+        '---',
+        '',
+        '# Screenshot Headline Tips',
+        '',
+        '- Lead with USER BENEFIT, not feature name: "Never forget a task" > "Task Management"',
+        '- Use power words: Track, Save, Build, Discover, Master, Simplify, Automate',
+        '- Include numbers when possible: "3x faster", "10K+ recipes", "Save 2hrs/week"',
+        '- First 3 screenshots matter most — App Store shows them in search results',
+        '- Hero card headline = your one-sentence pitch. Make it count.',
+        '- Keep headlines under 6 words. Subtitle can add detail.',
+    ];
+    // Device recommendations
+    const deviceTips = [
+        '',
+        '---',
+        '',
+        '# Device Recommendations',
+        '',
+    ];
+    if (platform === 'ios' || platform === 'both') {
+        deviceTips.push('**iOS (required for App Store):**');
+        deviceTips.push('- iPhone 16 Pro Max (iphone-6.9): 1260×2736 — REQUIRED');
+        deviceTips.push('- iPad Pro 13" (ipad-13): 2064×2752 — REQUIRED');
+        deviceTips.push('');
+    }
+    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 10" (android-tablet-10): 2560×1600 — optional');
+        deviceTips.push('');
+    }
+    // Schema reminder
+    const schemaReminder = [
+        '',
+        '---',
+        '',
+        '# Next Step',
+        '',
+        'After researching, call `generate-screenshots` with your findings in the `codebase_context` parameter:',
+        '```json',
+        '{',
+        '  "app_name": "...",',
+        '  "app_description": "...",',
+        '  "features": ["...", "..."],',
+        '  "brand_colors": { "primary": "#...", "secondary": "#..." },',
+        '  "mood": "...",',
+        '  "story_flow": "...",',
+        '  "count": 5,',
+        '  "codebase_context": {',
+        '    "readme_summary": "...",',
+        '    "key_screens": ["Dashboard", "Settings", "Profile", "..."],',
+        '    "color_tokens": { "primary": "#...", "background": "#..." },',
+        '    "target_audience": "...",',
+        '    "app_category": "...",',
+        '    "competitive_edge": "...",',
+        '    "ui_style": "...",',
+        '    "primary_user_flow": "Sign up → ... → ..."',
+        '  }',
+        '}',
+        '```',
+    ];
+    return {
+        content: [{
+                type: 'text',
+                text: [...checklist, ...storyFlows, ...headlineTips, ...deviceTips, ...schemaReminder].join('\n'),
+            }],
+    };
+});
+// ─── MCP Prompts ────────────────────────────────────────────────────────────────
+// Prompt 1: Full workflow — research codebase → generate → iterate → export
+server.registerPrompt('create-app-screenshots', {
+    title: 'Create App Store Screenshots',
+    description: 'Full guided workflow: research the codebase, generate screenshots, iterate, and export. Best results when used from within the app\'s project directory.',
+    argsSchema: {
+        platform: z.enum(['ios', 'android', 'both']).default('ios')
+            .describe('Target platform'),
+        extra_instructions: z.string().optional()
+            .describe('Any additional instructions — e.g. "use dark theme", "focus on the AI features", "make it seasonal for Christmas"'),
+    },
+}, ({ platform, extra_instructions }) => ({
+    messages: [{
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    'Create professional App Store screenshots for my app using AppScreenshotStudio.',
+                    '',
+                    'Follow this workflow for the best results:',
+                    '',
+                    '## Step 1: Research My Codebase',
+                    '',
+                    'Before generating anything, thoroughly research this codebase to understand what my app does.',
+                    'Call `prepare-screenshot-brief` to get a detailed research checklist, then search for:',
+                    '',
+                    '**App Identity:**',
+                    '- package.json, pubspec.yaml, build.gradle, Info.plist → app name, version',
+                    '- README.md → what the app does, value proposition, key features',
+                    '- Marketing/landing pages → hero headline, positioning, taglines',
+                    '',
+                    '**Features & Screens:**',
+                    '- Route/navigation definitions → list of screens the user sees',
+                    '- Main views/pages/components → what to showcase in screenshots',
+                    '- Settings/preferences → feature inventory',
+                    '',
+                    '**Visual Identity:**',
+                    '- Theme/color config files → brand colors (tailwind.config, theme.ts, colors.xml, etc.)',
+                    '- Font imports → typography choices',
+                    '- Dark/light mode → UI aesthetic',
+                    '',
+                    '**Market Context:**',
+                    '- App Store metadata (fastlane/metadata/, store listing files) → existing description',
+                    '- README → target audience, competitor mentions',
+                    '',
+                    '## Step 2: Generate Screenshots',
+                    '',
+                    'Use ALL your research to call `generate-screenshots` with rich parameters:',
+                    '- Fill in `codebase_context` with everything you found',
+                    '- Choose the best `story_flow` for this type of app',
+                    '- Extract `brand_colors` from the theme files',
+                    '- Write a compelling `app_description` based on the value proposition',
+                    '- Order `features` by user impact',
+                    `- Target platform: ${platform}${platform === 'both' ? ' (generate for iPhone first, then Android)' : ''}`,
+                    `${platform === 'ios' || platform === 'both' ? '- Device: iphone-6.9 for iPhone, ipad-13 for iPad' : ''}`,
+                    `${platform === 'android' || platform === 'both' ? '- Device: android-phone for Android' : ''}`,
+                    '- Count: 5-6 cards recommended (App Store shows first 3 prominently in search)',
+                    '',
+                    '## Step 3: Review & Iterate',
+                    '',
+                    'After generation, consider:',
+                    '- Do the headlines accurately represent the app\'s value?',
+                    '- Are the right features highlighted?',
+                    '- Do the brand colors match the app?',
+                    '- Would YOU download this app based on these screenshots?',
+                    'Use `edit-screenshots` to refine anything that doesn\'t feel right.',
+                    '',
+                    '## Step 4: Export',
+                    '',
+                    'Use `render-screenshots` to get final high-resolution PNGs.',
+                    'Remind me to upload actual app screenshots into the device frames via the web app.',
+                    '',
+                    extra_instructions ? `## Additional Instructions\n\n${extra_instructions}\n` : '',
+                    '---',
+                    'IMPORTANT: Take your time in Step 1. The quality of your research directly determines the quality of the screenshots. Thorough research saves multiple rounds of iteration.',
+                ].filter(Boolean).join('\n'),
+            },
+        }],
+}));
+// Prompt 2: Improve existing screenshots with codebase context
+server.registerPrompt('improve-screenshots', {
+    title: 'Improve Existing Screenshots',
+    description: 'Research the codebase and improve an existing screenshot project. Use when screenshots have already been generated but need refinement.',
+    argsSchema: {
+        project_id: z.string().describe('Project ID to improve'),
+        focus: z.string().optional()
+            .describe('What to focus on — e.g. "headlines", "colors", "story flow", "add social proof"'),
+    },
+}, ({ project_id, focus }) => ({
+    messages: [{
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    `I have an existing screenshot project (ID: ${project_id}) that I want to improve.`,
+                    '',
+                    '## Step 1: Inspect Current State',
+                    '',
+                    `Call \`get-project\` with project_id "${project_id}" to see the current screenshots.`,
+                    'Note the headlines, features shown, colors used, and story flow.',
+                    '',
+                    '## Step 2: Research My Codebase',
+                    '',
+                    'Search the codebase to understand what my app actually does:',
+                    '- Find the app name, description, and value proposition',
+                    '- List the main features and screens',
+                    '- Extract brand colors from theme/config files',
+                    '- Understand the target audience',
+                    '',
+                    '## Step 3: Compare & Improve',
+                    '',
+                    'Compare the current screenshots to what the app really is. Then use `edit-screenshots` to fix:',
+                    '1. **Headline accuracy** — do they describe what the app actually does?',
+                    '2. **Feature selection** — are the most valuable features highlighted?',
+                    '3. **Brand consistency** — do colors match the app\'s theme?',
+                    '4. **Story flow** — does the narrative make sense for this type of app?',
+                    '5. **Visual polish** — enough decorative elements, good contrast, professional layout?',
+                    '',
+                    focus ? `## Focus Area\n\nPrioritize improving: ${focus}\n` : '',
+                    'Pass `codebase_context` with your research when calling `edit-screenshots` for context-aware changes.',
+                ].filter(Boolean).join('\n'),
+            },
+        }],
+}));
 // ─── Start server ───────────────────────────────────────────────────────────────
 async function main() {
     if (!API_KEY) {

package/package.json

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