@appscreenshotstudio/mcp 0.3.0 → 0.4.0

package/README.md

@@ -98,6 +98,24 @@ Make changes to an existing project with natural language. Optionally target spe
 
 **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.
@@ -136,27 +154,15 @@ Show all supported device specs. No API call needed.
 
 **Free.**
 
-## Prompts
-
-MCP prompts are pre-defined workflows your agent can follow.
-
-### `create-app-screenshots`
+## Claude Code Skill
 
-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" |
+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:
 
-### `improve-screenshots`
-
-Research the codebase and improve an existing screenshot project. Compares current designs to the actual app and makes targeted fixes.
+```bash
+npx @appscreenshotstudio/mcp install-skill
+```
 
-| Argument | Required | Description |
-|---|---|---|
-| `project_id` | Yes | Project ID to improve |
-| `focus` | No | What to focus on: "headlines", "colors", "story flow", etc. |
+Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate App Store screenshots for my app".
 
 ## Supported Devices
 
@@ -183,7 +189,7 @@ The AI generates professional screenshots using:
 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
+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

package/dist/index.js

@@ -2,7 +2,7 @@
 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 { existsSync, mkdirSync, copyFileSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -124,7 +124,7 @@ function buildDesignMessage(input) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.1.0',
+    version: '0.4.0',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
@@ -244,9 +244,9 @@ Costs 5 credits per generation.`,
                     `Credits remaining: ${creditsRemaining}`,
                     '',
                     'Next steps:',
-                    '1. Open the project URL in a browser',
-                    '2. Upload app screenshots into the device mockups',
-                    '3. Click "Download All" to export final PNGs',
+                    '1. Use upload-screenshots to add your app screenshots into the device frames',
+                    '2. Use render-screenshots to export final PNGs',
+                    '3. Or open the project URL in a browser to preview and adjust',
                     '',
                     chatData.suggestions?.length
                         ? `Suggestions: ${chatData.suggestions.join(', ')}`
@@ -355,7 +355,7 @@ Example edit messages:
 // Tool 3: render-screenshots
 server.registerTool('render-screenshots', {
     title: 'Render Screenshots to PNG',
-    description: 'Export a screenshot project to high-resolution PNG files at exact App Store dimensions. Returns download URLs for each card. Free — no credit cost. Note: device mockups will show empty frames unless app screenshots have been uploaded via the web app first.',
+    description: 'Export a screenshot project to high-resolution PNG files at exact App Store dimensions. Returns download URLs for each card. Free — no credit cost. Note: device mockups will show empty frames unless app screenshots have been uploaded via upload-screenshots first.',
     inputSchema: z.object({
         project_id: z.string().describe('Project ID to render'),
     }),
@@ -730,6 +730,94 @@ This tool helps you gather the right information so generate-screenshots produce
             }],
     };
 });
+// Tool 8: upload-screenshots
+server.registerTool('upload-screenshots', {
+    title: 'Upload App Screenshots',
+    description: `Upload local app screenshots (from Simulator, emulator, or screen captures) into the device mockups of an existing project. This lets you add real app UI into the device frames without leaving the terminal.
+
+Reads files from your local filesystem, converts them to base64, and sets them on the device mockup elements in the specified cards.
+
+Free — no credit cost. The screenshots are placed into the device frames that were created by generate-screenshots.
+
+Workflow:
+1. generate-screenshots → creates project with empty device frames
+2. upload-screenshots → fills the device frames with your actual app UI
+3. render-screenshots → exports final PNGs at App Store dimensions
+
+Tips:
+- Take screenshots from the iOS Simulator (Cmd+S) or Android emulator
+- Use PNG format for best quality
+- Screenshots are automatically fitted into the device frame
+- You can upload different screenshots to different cards`,
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID from a previous generate-screenshots call'),
+        screenshots: z.array(z.object({
+            file_path: z.string().describe('Absolute path to a screenshot file on the local filesystem (PNG, JPG, or WEBP)'),
+            card_index: z.number().int().min(0).describe('Which card to place this screenshot on (0-based)'),
+        })).min(1).max(10)
+            .describe('Array of screenshots to upload, each mapped to a specific card index'),
+    }),
+}, async ({ project_id, screenshots }) => {
+    // Read local files and convert to base64
+    const screenshotData = [];
+    const errors = [];
+    for (const { file_path, card_index } of screenshots) {
+        try {
+            if (!existsSync(file_path)) {
+                errors.push(`File not found: ${file_path}`);
+                continue;
+            }
+            const buffer = readFileSync(file_path);
+            const ext = file_path.toLowerCase().split('.').pop();
+            const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg'
+                : ext === 'webp' ? 'image/webp'
+                    : 'image/png';
+            const base64 = `data:${mimeType};base64,${buffer.toString('base64')}`;
+            screenshotData.push({ card_index, image_base64: base64 });
+        }
+        catch (err) {
+            errors.push(`Failed to read ${file_path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (screenshotData.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No screenshots could be read.\n\nErrors:\n${errors.join('\n')}`,
+                }],
+        };
+    }
+    // Upload to API
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/upload-screenshots`, {
+        screenshots: screenshotData,
+    });
+    if (!res.ok) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Upload failed: ${JSON.stringify(res.data)}${errors.length ? `\n\nFile read errors:\n${errors.join('\n')}` : ''}`,
+                }],
+        };
+    }
+    const data = res.data.data;
+    const lines = [
+        `Uploaded ${data.uploaded} screenshot${data.uploaded !== 1 ? 's' : ''} into device mockups.`,
+        '',
+    ];
+    for (const r of data.results) {
+        lines.push(`  Card ${r.card_index + 1}: ${r.success ? 'OK' : r.error}`);
+    }
+    if (errors.length) {
+        lines.push('', 'File read warnings:', ...errors.map(e => `  ${e}`));
+    }
+    lines.push('', `Project URL: ${API_BASE}/builder/${project_id}`, '', 'Next steps:', '- Use render-screenshots to export final PNGs', '- Use edit-screenshots to adjust the design', '- Open the project URL to preview in the browser');
+    return {
+        content: [{
+                type: 'text',
+                text: lines.join('\n'),
+            }],
+    };
+});
 // ─── Start server ───────────────────────────────────────────────────────────────
 function autoInstallSkill() {
     try {
@@ -737,11 +825,10 @@ function autoInstallSkill() {
         const src = join(__dir, '..', 'skills', 'appscreenshotstudio', 'SKILL.md');
         const destDir = join(homedir(), '.claude', 'skills', 'appscreenshotstudio');
         const dest = join(destDir, 'SKILL.md');
-        if (!existsSync(src) || existsSync(dest))
+        if (!existsSync(src))
             return;
         mkdirSync(destDir, { recursive: true });
         copyFileSync(src, dest);
-        console.error('Installed Claude Code skill to ~/.claude/skills/appscreenshotstudio/');
     }
     catch {
         // Silent fail — skill install is optional

package/package.json

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

package/skills/appscreenshotstudio/SKILL.md

@@ -69,14 +69,21 @@ Call the `generate-screenshots` MCP tool with:
 - `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
+### Step 4: Upload App Screenshots
+
+If the user has actual app screenshots (from Simulator, emulator, or screen captures), upload them into the device frames using `upload-screenshots`:
+- Takes local file paths and maps them to card indices
+- Fills the empty device mockups with real app UI
+- Free — no credit cost
+
+### Step 5: 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
+### Step 6: Export
 
 Call `render-screenshots` to export PNGs at exact App Store dimensions. This is free.
 
@@ -98,6 +105,7 @@ Headlines must pass the "one second test" — readable at thumbnail size.
 | generate-screenshots | 5 credits |
 | edit-screenshots | 5 credits |
 | generate-background | 6 credits |
+| upload-screenshots | free |
 | render-screenshots | free |
 | prepare-screenshot-brief | free |
 | list-devices | free |