@appscreenshotstudio/mcp 0.5.5 → 0.6.1

package/README.md

@@ -1,225 +1,226 @@
-# @appscreenshotstudio/mcp
-
-MCP server for generating App Store screenshots via [AppScreenshotStudio](https://appscreenshotstudio.com).
-
-Let your AI agent (Claude Code, Cursor, Windsurf) generate, edit, and export App Store screenshots as a native tool.
-
-## Setup
-
-### 1. Get an API key
-
-Create one at [appscreenshotstudio.com/settings](https://appscreenshotstudio.com/settings) under **API Keys**.
-
-### 2. Install
-
-**Claude Code:**
-
-```bash
-claude mcp add appscreenshotstudio -- npx -y @appscreenshotstudio/mcp
-```
-
-Then add to your shell profile (`.bashrc`, `.zshrc`, etc.):
-
-```bash
-export APPSCREENSHOTSTUDIO_API_KEY="sk_live_your_key_here"
-```
-
-**Cursor / Windsurf / Other MCP clients:**
-
-Add to your MCP config (`.cursor/mcp.json`, `settings.json`, etc.):
-
-```json
-{
-  "mcpServers": {
-    "appscreenshotstudio": {
-      "command": "npx",
-      "args": ["-y", "@appscreenshotstudio/mcp"],
-      "env": {
-        "APPSCREENSHOTSTUDIO_API_KEY": "sk_live_your_key_here"
-      }
-    }
-  }
-}
-```
-
-## Tools
-
-### `prepare-screenshot-brief`
-
-Get a research checklist and strategy guide before generating. Returns file patterns to search for across tech stacks, story flow recommendations per app category, headline tips, and the `codebase_context` schema to fill in.
-
-**Free — no API call or credits.**
-
-### `generate-screenshots`
-
-Create a complete set of App Store screenshots. The agent researches your codebase first, then passes rich context for accurate, app-specific designs.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `app_name` | string | Yes | App name |
-| `app_description` | string | Yes | What the app does (1-3 sentences) |
-| `features` | string[] | No | Key features, ordered by importance (max 10) |
-| `brand_colors` | object | No | `{ primary, secondary?, accent? }` as hex |
-| `mood` | string | No | "energetic", "calm", "minimal", "bold", etc. |
-| `device_id` | string | No | Target device (default: `iphone-6.9`) |
-| `count` | number | No | Number of cards, 3-10 (default: 5) |
-| `story_flow` | string | No | Narrative structure (default: `auto`) |
-| `codebase_context` | object | No | App context from codebase research (see below) |
-
-**Costs 5 credits.**
-
-#### `codebase_context`
-
-Pass this for dramatically better screenshots. The context is persisted on the project and used in all subsequent chats.
-
-| Field | Description |
-|---|---|
-| `readme_summary` | App overview from README or docs |
-| `key_screens` | Main screens/views (e.g. "Dashboard", "Settings") |
-| `color_tokens` | Brand colors from theme files (e.g. `{ "primary": "#7C3AED" }`) |
-| `target_audience` | Who the app is for |
-| `app_category` | fitness, finance, social, productivity, etc. |
-| `competitive_edge` | What makes it unique |
-| `app_store_description` | Existing store listing if found |
-| `tech_stack` | React Native, SwiftUI, Flutter, etc. |
-| `ui_style` | "dark mode with neon accents", "clean minimal", etc. |
-| `primary_user_flow` | Main user journey through the app |
-
-### `edit-screenshots`
-
-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. |
-| `codebase_context` | object | No | App context to enrich the edit (same schema as above) |
-
-**Costs 5 credits.**
-
-### `upload-screenshots`
-
-Upload local app screenshots (from Simulator, emulator, or screen captures) into the device mockups of an existing project. Reads files from your local filesystem and places them into the device frames.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `project_id` | string | Yes | From a previous `generate-screenshots` call |
-| `screenshots` | array | Yes | Array of `{ file_path, card_index }` — maps local files to cards |
-
-Each item in `screenshots`:
-
-| Field | Type | Description |
-|---|---|---|
-| `file_path` | string | Absolute path to a local PNG, JPG, or WEBP file |
-| `card_index` | number | Which card to place this screenshot on (0-based) |
-
-**Free.**
-
-### `render-screenshots`
-
-Export to high-resolution PNGs. Returns download URLs.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `project_id` | string | Yes | Project to render |
-
-**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 6 credits.**
-
-### `generate-panoramic-background`
-
-Generate one wide image and slice it across multiple cards so they read as a continuous scene in the App Store gallery. Use after a panoramic chat edit ("pano the background across cards 1-3") to fulfill the pending panoramic, or pass an explicit `prompt` / `pexels_query`.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `project_id` | string | Yes | Project containing the cards |
-| `prompt` | string | No | AI scene description (Gemini). Costs 6 credits. |
-| `pexels_query` | string | No | Stock photo search query (Pexels). Free. |
-| `card_indices` | number[] | No | Cards sharing the panoramic (0-based, min 2). Default: first 3. |
-
-Omit both `prompt` and `pexels_query` to fulfill a panoramic already set up by `generate-screenshots` / `edit-screenshots`.
-
-**Costs 6 credits (AI prompt) or free (Pexels query).**
-
-### `list-devices`
-
-Show all supported device specs. No API call needed.
-
-**Free.**
-
-## Claude Code Skill
-
-The MCP server auto-installs a Claude Code skill on first startup. The skill teaches Claude a structured research-first workflow for better screenshot results. You can also install it manually:
-
-```bash
-npx @appscreenshotstudio/mcp install-skill
-```
-
-Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate App Store screenshots for my app".
-
-## Supported Devices
-
-| ID | Name | Size | Required |
-|---|---|---|---|
-| `iphone-6.9` | iPhone 16 Pro Max | 1260x2736 | App Store |
-| `iphone-6.3` | iPhone 17 Pro | 1206x2622 | Optional |
-| `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
-| `android-phone` | Android Phone | 1080x2340 | Play Store |
-| `android-tablet-10` | Android Tablet 7" | 1200x1920 | Play Store |
-| `apple-watch-ultra` | Apple Watch Ultra 2 | 410x502 | App Store |
-
-## Design Features
-
-The AI generates professional screenshots using:
-
-- **94 shape types** (17 core + 77 decorative 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
-- **Compound trust signals**: statRow, laurelStat, starRating, quote, pressBanner, featureGrid, beforeAfterSplit, stepList — auto-positioned per layout
-- **Frame color**: recolor the device frame — `natural` (default), `black`, `white`, `gold`. Requires Growth plan or higher.
-- **Panoramics**: slice one wide image across cards (chat tags the cards, then `generate-panoramic-background` creates and slices the image) or stretch a foreground element across adjacent cards (`apply_element_span`). Gallery gutters are accounted for.
-- **9 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, landscape-left, landscape-right
-- **13 layouts**: `text-top-device-bottom`, `text-top-device-tilted`, `device-hero`, `social-proof`, `review-clip`, `screen-hero`, `lifestyle-hero`, `feature-grid`, `before-after`, `stats-hero`, `metric-badge`, `annotated-feature`, `step-flow`. The AI varies `deviceScale`, `deviceSide`, `textPosition`, and `textAlign` per card so a set never looks like duplicates.
-
-## Workflow
-
-1. **Research** — Agent calls `prepare-screenshot-brief`, then searches your codebase for app name, features, colors, screens, and audience
-2. **Generate** — Agent calls `generate-screenshots` with `codebase_context` for app-specific designs
-3. **Iterate** — Agent calls `edit-screenshots` to refine (codebase context carries over automatically)
-4. **Upload** — Agent calls `upload-screenshots` with local file paths to fill device mockups
-5. **Export** — Agent calls `render-screenshots` or click "Download All" in the web app
-
-## Security
-
-- API key stays on your machine (environment variable)
-- All API calls over HTTPS
-- stdio transport — no network ports opened
-- Revoke keys anytime in Settings
-
-## Links
-
-- [Screenshot API + MCP overview](https://appscreenshotstudio.com/api)
-- [Full docs](https://appscreenshotstudio.com/docs/mcp)
-- [REST API reference](https://appscreenshotstudio.com/docs/api)
-- [Pricing](https://appscreenshotstudio.com/pricing)
+# @appscreenshotstudio/mcp
+
+MCP server for generating App Store screenshots via [AppScreenshotStudio](https://appscreenshotstudio.com).
+
+Let your AI agent (Claude Code, Cursor, Windsurf) generate, edit, and export App Store screenshots as a native tool.
+
+## Setup
+
+### 1. Get an API key
+
+Create one at [appscreenshotstudio.com/settings](https://appscreenshotstudio.com/settings) under **API Keys**.
+
+### 2. Install
+
+**Claude Code:**
+
+```bash
+claude mcp add appscreenshotstudio -- npx -y @appscreenshotstudio/mcp
+```
+
+Then add to your shell profile (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+export APPSCREENSHOTSTUDIO_API_KEY="sk_live_your_key_here"
+```
+
+**Cursor / Windsurf / Other MCP clients:**
+
+Add to your MCP config (`.cursor/mcp.json`, `settings.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "appscreenshotstudio": {
+      "command": "npx",
+      "args": ["-y", "@appscreenshotstudio/mcp"],
+      "env": {
+        "APPSCREENSHOTSTUDIO_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `prepare-screenshot-brief`
+
+Get a research checklist and strategy guide before generating. Returns file patterns to search for across tech stacks, story flow recommendations per app category, headline tips, and the `codebase_context` schema to fill in.
+
+**Free — no API call or credits.**
+
+### `generate-screenshots`
+
+Create a complete set of App Store screenshots. The agent researches your codebase first, then passes rich context for accurate, app-specific designs.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `app_name` | string | Yes | App name |
+| `app_description` | string | Yes | What the app does (1-3 sentences) |
+| `features` | string[] | No | Key features, ordered by importance (max 10) |
+| `brand_colors` | object | No | `{ primary, secondary?, accent? }` as hex |
+| `mood` | string | No | "energetic", "calm", "minimal", "bold", etc. |
+| `device_id` | string | No | Target device (default: `iphone-6.9`) |
+| `count` | number | No | Number of cards, 3-10 (default: 5) |
+| `story_flow` | string | No | Narrative structure (default: `auto`) |
+| `codebase_context` | object | No | App context from codebase research (see below) |
+
+**Costs 5 credits.**
+
+#### `codebase_context`
+
+Pass this for dramatically better screenshots. The context is persisted on the project and used in all subsequent chats.
+
+| Field | Description |
+|---|---|
+| `readme_summary` | App overview from README or docs |
+| `key_screens` | Main screens/views (e.g. "Dashboard", "Settings") |
+| `color_tokens` | Brand colors from theme files (e.g. `{ "primary": "#7C3AED" }`) |
+| `target_audience` | Who the app is for |
+| `app_category` | fitness, finance, social, productivity, etc. |
+| `competitive_edge` | What makes it unique |
+| `app_store_description` | Existing store listing if found |
+| `tech_stack` | React Native, SwiftUI, Flutter, etc. |
+| `ui_style` | "dark mode with neon accents", "clean minimal", etc. |
+| `primary_user_flow` | Main user journey through the app |
+
+### `edit-screenshots`
+
+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. |
+| `codebase_context` | object | No | App context to enrich the edit (same schema as above) |
+
+**Costs 5 credits.**
+
+### `upload-screenshots`
+
+Upload local app screenshots (from Simulator, emulator, or screen captures) into the device mockups of an existing project. Reads files from your local filesystem and places them into the device frames.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | From a previous `generate-screenshots` call |
+| `screenshots` | array | Yes | Array of `{ file_path, card_index }` — maps local files to cards |
+
+Each item in `screenshots`:
+
+| Field | Type | Description |
+|---|---|---|
+| `file_path` | string | Absolute path to a local PNG, JPG, or WEBP file |
+| `card_index` | number | Which card to place this screenshot on (0-based) |
+
+**Free.**
+
+### `render-screenshots`
+
+Export to high-resolution PNGs. Returns download URLs.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project to render |
+
+**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 6 credits.**
+
+### `generate-panoramic-background`
+
+Generate one wide image and slice it across multiple cards so they read as a continuous scene in the App Store gallery. Use after a panoramic chat edit ("pano the background across cards 1-3") to fulfill the pending panoramic, or pass an explicit `prompt` / `pexels_query`.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project containing the cards |
+| `prompt` | string | No | AI scene description (Gemini). Costs 6 credits. |
+| `pexels_query` | string | No | Stock photo search query (Pexels). Free. |
+| `card_indices` | number[] | No | Cards sharing the panoramic (0-based, min 2). Default: first 3. |
+
+Omit both `prompt` and `pexels_query` to fulfill a panoramic already set up by `generate-screenshots` / `edit-screenshots`.
+
+**Costs 6 credits (AI prompt) or free (Pexels query).**
+
+### `list-devices`
+
+Show all supported device specs. No API call needed.
+
+**Free.**
+
+## Claude Code Skill
+
+The MCP server auto-installs a Claude Code skill on first startup. The skill teaches Claude a structured research-first workflow for better screenshot results. You can also install it manually:
+
+```bash
+npx @appscreenshotstudio/mcp install-skill
+```
+
+Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate App Store screenshots for my app".
+
+## Supported Devices
+
+| ID | Name | Size | Required |
+|---|---|---|---|
+| `iphone-6.9` | iPhone 16 Pro Max | 1260x2736 | App Store |
+| `iphone-6.3` | iPhone 17 Pro | 1206x2622 | Optional |
+| `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
+| `android-phone` | Android Phone | 1080x2340 | Play Store |
+| `android-tablet-10` | Android Tablet 7" | 1200x1920 | Play Store |
+| `apple-watch-ultra` | Apple Watch Ultra 2 | 410x502 | App Store |
+
+## Design Features
+
+The AI generates professional screenshots using:
+
+- **94 shape types** (17 core + 77 decorative 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
+- **Compound trust signals**: statRow, laurelStat, starRating, quote, pressBanner. Auto-positioned per layout, and opt-in: supply the real figure or the card ships clean
+- **Background textures**: diagonal-stripe, crosshatch, checkerboard, zigzag, hairline-grid, dot-grid, waves, grain, radial-rays, concentric-circles. Ask for one explicitly; they are subtle by design and run continuously across the set.
+- **Frame color**: recolor the device frame — `natural` (default), `black`, `white`, `gold`. Requires Growth plan or higher.
+- **Panoramics**: slice one wide image across cards (chat tags the cards, then `generate-panoramic-background` creates and slices the image) or stretch a foreground element across adjacent cards (`apply_element_span`). Gallery gutters are accounted for.
+- **9 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, landscape-left, landscape-right
+- **10 layouts**: `text-top-device-bottom`, `text-top-device-tilted`, `device-hero`, `social-proof`, `review-clip`, `screen-hero`, `lifestyle-hero`, `stats-hero`, `metric-badge`, `annotated-feature`. The AI varies `deviceScale`, `deviceSide`, `textPosition`, and `textAlign` per card so a set never looks like duplicates.
+
+## Workflow
+
+1. **Research** — Agent calls `prepare-screenshot-brief`, then searches your codebase for app name, features, colors, screens, and audience
+2. **Generate** — Agent calls `generate-screenshots` with `codebase_context` for app-specific designs
+3. **Iterate** — Agent calls `edit-screenshots` to refine (codebase context carries over automatically)
+4. **Upload** — Agent calls `upload-screenshots` with local file paths to fill device mockups
+5. **Export** — Agent calls `render-screenshots` or click "Download All" in the web app
+
+## Security
+
+- API key stays on your machine (environment variable)
+- All API calls over HTTPS
+- stdio transport — no network ports opened
+- Revoke keys anytime in Settings
+
+## Links
+
+- [Screenshot API + MCP overview](https://appscreenshotstudio.com/api)
+- [Full docs](https://appscreenshotstudio.com/docs/mcp)
+- [REST API reference](https://appscreenshotstudio.com/docs/api)
+- [Pricing](https://appscreenshotstudio.com/pricing)

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', {
@@ -211,14 +211,11 @@ The AI picks a narrative arc that fits the app's sell angle (trust-first for fin
 - review-clip: rating-statement headline + stars + quote + bottom-clipped device
 - screen-hero: top-clipped device + centered headline + optional trust stat
 - lifestyle-hero: full-bleed photo background + text overlay (no device)
-- feature-grid: headline + 2×2 or 2×3 icon+label grid, no device
-- before-after: dark before-half + bright after-half (transformation apps)
 - stats-hero: giant centered stat(s), no device, numbers-led
 - metric-badge: centered device + chunky "achievement card" floating over its screen
 - annotated-feature: tilted device + side callout chip linked by a connector line
-- step-flow: headline + 2-4 numbered step rows ("how it works"), no device
 
-Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit, stepList.
+Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote. Trust signals are opt-in: supply the real number, quote or press name, or the card ships clean rather than inventing one.
 
 Panoramic backgrounds slice one wide AI-generated or Pexels image across multiple cards for cohesion. Panoramic element spans stretch a foreground image or device across adjacent cards. Note: if the design comes back with a panoramic background, the chat only tags the cards; call generate-panoramic-background afterwards to actually create and slice the wide image.
 
@@ -351,8 +348,9 @@ server.registerTool('edit-screenshots', {
 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
-- Layouts (13 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, review-clip, screen-hero, lifestyle-hero, feature-grid, before-after, stats-hero, metric-badge, annotated-feature, step-flow. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
+- Colors: brand palette, gradient backgrounds, accent colors, text colors. A set can rotate MULTIPLE accents card by card ("pink, then coral, then brick") and each card keeps its own highlight colour.
+- Background textures (ask for one explicitly, they are never added on their own): diagonal-stripe, crosshatch, checkerboard, zigzag, hairline-grid, dot-grid, waves, grain, radial-rays, concentric-circles. Kept subtle by design so they cannot affect headline contrast. Tiled textures run continuously across the whole set; radial-rays and concentric-circles can be centred on the middle of the set so the pattern fans out across every card.
+- Layouts (10 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, review-clip, screen-hero, lifestyle-hero, stats-hero, metric-badge, annotated-feature. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
 - Layout params: deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), textAlign (left/center)
 - Device mockups: perspective variants (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), 2D rotation, resize, reposition
 - Frame color: recolor the device frame — "natural" (default), "black", "white", "gold". Examples: "make the iPhone gold", "black titanium finish", "white iPhone". Requires Growth plan or higher.
@@ -382,7 +380,6 @@ Example edit messages:
 - "Recolor the iPhone frame to gold across all cards"
 - "Replace card 3 with a CTA card saying Download Free"
 - "Switch card 2 to device-hero layout with statRow showing our three key metrics"
-- "Add a before-after card showing the transformation"
 - "Add decorative leaf and sparkle shapes scattered in the background"
 - "Make 'Every' underlined and italic in the headline"`,
     inputSchema: z.object({
@@ -671,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'),
     }),
@@ -758,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 = [
@@ -904,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.5.5",
+  "version": "0.6.1",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",