@appscreenshotstudio/mcp 0.6.0 → 0.6.1

package/dist/index.js

@@ -192,7 +192,7 @@ const chatImagesSchema = z.array(z.object({
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.5.5',
+    version: '0.6.1',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
@@ -668,18 +668,20 @@ Good prompts describe a continuous scene, not objects or text:
 // Tool 8: 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.
+    description: `Get a category playbook and repo-research checklist to prepare for screenshot generation. Call this BEFORE generate-screenshots. Free (no credits).
+
+Pass app_category to get category-specific guidance pulled live from AppScreenshotStudio: the frame-1 hook playbook (default layout, what to avoid, caption patterns), the recommended story_flow and mood, and the exact facts to dig out of THIS app's repo for its category (e.g. security and compliance signals for finance, real gameplay art for games, the outcome for fitness).
 
 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
+- A category playbook (frame-1 hooks + layout + arc + mood) for the app_category
+- A category-specific repo research focus (what to grep this app for)
+- A generic codebase research checklist (file patterns per tech stack)
+- Headline tips + 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.`,
+The more you gather here, the better generate-screenshots does 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'),
+            .describe('App category, e.g. fitness, finance, gaming, social, productivity, health, travel, wellness. Drives the category playbook this tool returns; synonyms are normalized server-side.'),
         platform: z.enum(['ios', 'android', 'both']).default('ios')
             .describe('Target platform'),
     }),
@@ -755,84 +757,31 @@ This tool helps you gather the right information so generate-screenshots produce
         '- 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]);
+    let playbook = null;
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/playbook?category=${encodeURIComponent(app_category ?? '')}`);
+        if (res.ok) {
+            const json = (await res.json());
+            if (json?.data)
+                playbook = json.data;
+        }
     }
-    else {
-        storyFlows.push('**General recommendations by app type:**', '');
-        for (const [, lines] of Object.entries(categoryRecommendations)) {
-            storyFlows.push(...lines, '');
+    catch {
+        // offline or endpoint unavailable: the generic checklist still stands
+    }
+    const categoryBlock = [];
+    if (playbook && playbook.depth !== 'general') {
+        categoryBlock.push(`# Category Playbook: ${playbook.label}`, '', `Recommended \`story_flow\`: \`${playbook.arc}\`  |  \`mood\`: \`${playbook.mood}\``, '', '## Research this app for its category', `These are what a ${playbook.label.toLowerCase()} frame 1 lives or dies on. Dig them out of the repo before generating:`, ...playbook.researchFocus.map((r) => `- ${r}`), '');
+        if (playbook.frame1) {
+            categoryBlock.push('## Frame 1 (the hook) for this category', `Default layout: \`${playbook.frame1.defaultLayout}\`. Avoid: ${playbook.frame1.avoidLayouts.map((l) => `\`${l}\``).join(', ')}.`, `Why: ${playbook.frame1.rationale}`, '', 'Pick the hook that fits the app, then write the headline from its caption pattern:', ...playbook.frame1.hooks.map((h) => `- **${h.name}** (${h.layout}): ${h.shows}. Caption: ${h.captionPattern}`), '');
+        }
+        if (playbook.patternsToAvoid && playbook.patternsToAvoid.length) {
+            categoryBlock.push('## Avoid for this category', ...playbook.patternsToAvoid.map((p) => `- ${p}`), '');
+        }
+        if (playbook.highlights && playbook.highlights.length) {
+            categoryBlock.push(`Highlights worth surfacing: ${playbook.highlights.join(', ')}.`, '');
         }
+        categoryBlock.push('---', '');
     }
     // Headline tips
     const headlineTips = [
@@ -901,7 +850,7 @@ This tool helps you gather the right information so generate-screenshots produce
     return {
         content: [{
                 type: 'text',
-                text: [...checklist, ...storyFlows, ...headlineTips, ...deviceTips, ...schemaReminder].join('\n'),
+                text: [...categoryBlock, ...checklist, ...headlineTips, ...deviceTips, ...schemaReminder].join('\n'),
             }],
     };
 });

package/package.json

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