@appscreenshotstudio/mcp 0.2.0 → 0.2.2

package/README.md

@@ -44,9 +44,15 @@ Add to your MCP config (`.cursor/mcp.json`, `settings.json`, etc.):
 
 ## 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. One tool call = one full project.
+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 |
 |---|---|---|---|
@@ -58,9 +64,27 @@ Create a complete set of App Store screenshots. One tool call = one full project
 | `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.
@@ -70,6 +94,7 @@ Make changes to an existing project with natural language. Optionally target spe
 | `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.**
 
@@ -111,6 +136,28 @@ Show all supported device specs. No API call needed.
 
 **Free.**
 
+## Prompts
+
+MCP prompts are pre-defined workflows your agent can follow.
+
+### `create-app-screenshots`
+
+Full guided workflow: research the codebase, generate screenshots with rich context, iterate, and export. Best results when used from within the app's project directory.
+
+| Argument | Default | Description |
+|---|---|---|
+| `platform` | ios | "ios", "android", or "both" |
+| `extra_instructions` | none | Additional instructions like "use dark theme" |
+
+### `improve-screenshots`
+
+Research the codebase and improve an existing screenshot project. Compares current designs to the actual app and makes targeted fixes.
+
+| Argument | Required | Description |
+|---|---|---|
+| `project_id` | Yes | Project ID to improve |
+| `focus` | No | What to focus on: "headlines", "colors", "story flow", etc. |
+
 ## Supported Devices
 
 | ID | Name | Size | Required |
@@ -133,10 +180,11 @@ The AI generates professional screenshots using:
 
 ## Workflow
 
-1. **Generate** — Agent calls `generate-screenshots` with your app details
-2. **Iterate** — Agent calls `edit-screenshots` to refine
-3. **Upload** — Open the project URL, upload your actual app screenshots into the device mockups
-4. **Export** — Agent calls `render-screenshots` or click "Download All" in the web app
+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** — Open the project URL, upload your actual app screenshots into the device mockups
+5. **Export** — Agent calls `render-screenshots` or click "Download All" in the web app
 
 ## Security
 

package/dist/index.js

@@ -2,6 +2,29 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+// ─── CLI: install-skill ─────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+if (args[0] === 'install-skill') {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const src = join(__dirname, '..', 'skills', 'appscreenshotstudio', 'SKILL.md');
+    const destDir = join(homedir(), '.claude', 'skills', 'appscreenshotstudio');
+    const dest = join(destDir, 'SKILL.md');
+    if (!existsSync(src)) {
+        console.error('Error: SKILL.md not found in package. Try reinstalling @appscreenshotstudio/mcp.');
+        process.exit(1);
+    }
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    console.log('Skill installed to ~/.claude/skills/appscreenshotstudio/SKILL.md');
+    console.log('');
+    console.log('You can now use /appscreenshotstudio in Claude Code to generate screenshots.');
+    console.log('Make sure the MCP server is also configured in your Claude Code settings.');
+    process.exit(0);
+}
 const API_BASE = process.env.APPSCREENSHOTSTUDIO_URL || 'https://appscreenshotstudio.com';
 const API_KEY = process.env.APPSCREENSHOTSTUDIO_API_KEY;
 // ─── Devices (mirrors lib/device-specs.ts) ─────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ]
 }

package/skills/appscreenshotstudio/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: appscreenshotstudio
+version: 1.0.0
+description: Generate App Store screenshots by researching the codebase and calling AppScreenshotStudio MCP tools. Use when the user mentions "screenshots", "App Store", "Play Store", "store listing", or wants to create marketing screenshots for their app.
+allowed_tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - WebFetch
+  - AskUserQuestion
+argument-hint: [app name or description]
+---
+
+# App Store Screenshot Generator
+
+You generate production-ready App Store / Play Store screenshots by researching the user's codebase and calling the AppScreenshotStudio MCP tools.
+
+## Workflow
+
+### Step 1: Research the Codebase
+
+Before generating, thoroughly research the app. This context dramatically improves output quality.
+
+**Find and read these files:**
+
+- **App identity**: `README.md`, `package.json`, `Cargo.toml`, `pubspec.yaml`, `build.gradle`
+- **Brand colors**: `tailwind.config.*` (colors/theme), `**/theme.*`, `**/colors.*`, `**/palette.*`
+  - SwiftUI: search for `Color(` or `.accentColor`
+  - Flutter: search for `ThemeData`, `primarySwatch`, `colorScheme`
+- **Key screens**: route/page files, navigation definitions, tab bars
+  - React/Next.js: `app/`, `pages/`, route files
+  - SwiftUI: `NavigationView`, `TabView`, `View` structs
+  - Flutter: `MaterialPageRoute`, `GoRouter`
+  - React Native: `createStackNavigator`, `Screen`
+- **Store metadata**: `Info.plist`, fastlane `metadata/`, `AndroidManifest.xml`
+- **Marketing copy**: landing pages, about pages, existing descriptions
+
+**Build this context object:**
+```
+readme_summary: What the app does (2-3 sentences)
+key_screens: ["Dashboard with activity feed", "Settings page", ...]
+color_tokens: {"primary": "#hex", "secondary": "#hex"}
+target_audience: Who it's for
+app_category: fitness|finance|social|productivity|food|travel|health|education
+competitive_edge: What makes it unique
+ui_style: "dark mode with neon accents" or "clean minimal"
+primary_user_flow: "Sign up → Create project → Track progress"
+```
+
+### Step 2: Confirm with the User
+
+Present your findings and ask:
+- "I found these as your main features: [X, Y, Z]. Are these the top 3-5 to highlight?"
+- "Your brand colors appear to be [primary, secondary]. Should I use these?"
+- "What mood fits? Options: energetic, calm, professional, playful, minimal, bold, warm, dark"
+- "How many screenshots? (3-10, default 5)"
+
+### Step 3: Generate Screenshots
+
+Call the `generate-screenshots` MCP tool with:
+- `app_name`: from package.json or user input
+- `app_description`: from README or user description
+- `features`: top 3-5 features as array
+- `brand_colors`: `{ primary, secondary?, accent? }` from theme files
+- `mood`: user's chosen mood
+- `device_id`: `"iphone-6.9"` (default), `"ipad-13"`, `"android-phone"`, `"android-tablet-10"`
+- `count`: number of cards (3-10)
+- `story_flow`: `"auto"` (default), `"hero-intro"`, `"problem-solution"`, `"benefit-first"`, etc.
+- `codebase_context`: the full context object from Step 1
+
+### Step 4: Review and Iterate
+
+Share the project URL and offer refinements using `edit-screenshots`:
+- "Want to change any headlines or colors?"
+- "Should I add a social proof card with ratings?"
+- "Want to try a different layout style?"
+
+### Step 5: Export
+
+Call `render-screenshots` to export PNGs at exact App Store dimensions. This is free.
+
+## Headline Rules
+
+Headlines must pass the "one second test" — readable at thumbnail size.
+
+**Three styles:**
+1. Paint a moment: "Morning runs handled", "Your kitchen simplified"
+2. State an outcome: "Never miss a workout", "Inbox zero daily"
+3. Eliminate a pain: "No more forgotten tasks", "Ditch the spreadsheet"
+
+**Banned:** feature lists, "and"-joined phrases, starting with "The", vague aspirational fluff.
+
+## Credit Costs
+
+| Tool | Cost |
+|------|------|
+| generate-screenshots | 5 credits |
+| edit-screenshots | 5 credits |
+| generate-background | 6 credits |
+| render-screenshots | free |
+| prepare-screenshot-brief | free |
+| list-devices | free |
+| get-project | free |