@appscreenshotstudio/mcp 0.1.5 → 0.2.0

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:
@@ -120,14 +152,41 @@ Costs 5 credits 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)}` }],
@@ -208,10 +267,42 @@ Example edit messages:
         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) {
@@ -376,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.5",
+  "version": "0.2.0",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",