@appscreenshotstudio/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppScreenshotStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @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
+
+### `generate-screenshots`
+
+Create a complete set of App Store screenshots. One tool call = one full project.
+
+| 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`) |
+
+**Costs 1 credit.**
+
+### `edit-screenshots`
+
+Make changes to an existing project with natural language.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | From a previous `generate-screenshots` call |
+| `message` | string | Yes | What to change |
+
+**Costs 1 credit.**
+
+### `render-screenshots`
+
+Export to high-resolution PNGs. Returns download URLs.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project to render |
+
+**Free.**
+
+### `list-devices`
+
+Show all supported device specs. No API call needed.
+
+**Free.**
+
+## Supported Devices
+
+| ID | Name | Size | Required |
+|---|---|---|---|
+| `iphone-6.9` | iPhone 16 Pro Max | 1260x2736 | App Store |
+| `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
+| `android-phone` | Android Phone | 1080x2340 | Play Store |
+| `android-tablet-10` | Android Tablet 10" | 2560x1600 | Play Store |
+| `iphone-6.5` | iPhone 14 Plus | 1284x2778 | Optional |
+| `iphone-6.3` | iPhone 16 Pro | 1179x2556 | Optional |
+| `iphone-6.1` | iPhone 14 | 1170x2532 | Optional |
+
+## 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
+
+## 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
+
+- [Full docs](https://appscreenshotstudio.com/docs/mcp)
+- [REST API reference](https://appscreenshotstudio.com/docs/api)
+- [Pricing](https://appscreenshotstudio.com/pricing)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_BASE = process.env.APPSCREENSHOTSTUDIO_URL || 'https://appscreenshotstudio.com';
+const API_KEY = process.env.APPSCREENSHOTSTUDIO_API_KEY;
+// ─── Devices (mirrors lib/device-specs.ts) ─────────────────────────────────────
+const DEVICES = [
+    { id: 'iphone-6.9', name: 'iPhone 16 Pro Max', width: 1260, height: 2736, category: 'iphone', required: true },
+    { id: 'iphone-6.5', name: 'iPhone 14 Plus', width: 1284, height: 2778, category: 'iphone', required: false },
+    { id: 'iphone-6.3', name: 'iPhone 16 Pro', width: 1179, height: 2556, category: 'iphone', required: false },
+    { id: 'iphone-6.1', name: 'iPhone 14', width: 1170, height: 2532, category: 'iphone', required: false },
+    { id: 'iphone-5.5', name: 'iPhone 8 Plus', width: 1242, height: 2208, category: 'iphone', required: false },
+    { id: 'ipad-13', name: 'iPad Pro 13"', width: 2064, height: 2752, category: 'ipad', required: true },
+    { id: 'ipad-12.9', name: 'iPad Pro 12.9"', width: 2048, height: 2732, category: 'ipad', required: false },
+    { id: 'ipad-11', name: 'iPad Pro 11"', width: 1668, height: 2388, category: 'ipad', required: false },
+    { id: 'android-phone', name: 'Android Phone', width: 1080, height: 2340, category: 'android-phone', required: true },
+    { id: 'android-tablet-10', name: 'Android Tablet 10"', width: 2560, height: 1600, category: 'android-tablet', required: true },
+];
+const VALID_DEVICE_IDS = DEVICES.map(d => d.id);
+// ─── API helper ─────────────────────────────────────────────────────────────────
+async function apiCall(method, path, body) {
+    if (!API_KEY) {
+        return { ok: false, status: 401, data: { error: 'APPSCREENSHOTSTUDIO_API_KEY not set' } };
+    }
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            'Authorization': `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const data = await res.json();
+    return { ok: res.ok, status: res.status, data };
+}
+// ─── Message builder ────────────────────────────────────────────────────────────
+const STORY_FLOW_DESCRIPTIONS = {
+    'auto': 'Choose the best narrative structure automatically',
+    'standard': 'Standard feature highlights',
+    'problem-solution': 'Problem, then solution, then benefit',
+    'social-proof': 'Lead with testimonials and reviews',
+    'benefit-first': 'Lead with benefits, features later',
+    'journey': 'User journey and before/after transformation',
+    'hero-intro': 'Hero branding screen first (no device), then features with devices',
+    'social-proof-bookend': 'Hero intro, then features, then social proof ending',
+};
+function buildDesignMessage(input) {
+    const parts = [];
+    parts.push(`Create ${input.count} App Store screenshots for my app.`);
+    parts.push(`\nApp name: ${input.app_name}`);
+    parts.push(`Description: ${input.app_description}`);
+    if (input.features?.length) {
+        parts.push(`\nKey features (in order of importance):`);
+        for (const f of input.features) {
+            parts.push(`- ${f}`);
+        }
+    }
+    if (input.brand_colors) {
+        const colors = [`primary: ${input.brand_colors.primary}`];
+        if (input.brand_colors.secondary)
+            colors.push(`secondary: ${input.brand_colors.secondary}`);
+        if (input.brand_colors.accent)
+            colors.push(`accent: ${input.brand_colors.accent}`);
+        parts.push(`\nBrand colors: ${colors.join(', ')}`);
+    }
+    if (input.mood) {
+        parts.push(`Mood: ${input.mood}`);
+    }
+    if (input.story_flow && input.story_flow !== 'auto') {
+        parts.push(`\nStory flow: ${input.story_flow} (${STORY_FLOW_DESCRIPTIONS[input.story_flow] || input.story_flow})`);
+    }
+    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');
+}
+// ─── MCP Server ─────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'appscreenshotstudio',
+    version: '0.1.0',
+});
+// Tool 1: generate-screenshots
+server.registerTool('generate-screenshots', {
+    title: 'Generate App Store Screenshots',
+    description: 'Create a complete set of App Store screenshot designs for an app. Generates multiple cards with headlines, backgrounds, device mockups, and a cohesive story flow. Returns a project URL where the developer can upload their actual app screenshots into the device frames and export final PNGs.',
+    inputSchema: z.object({
+        app_name: z.string().describe('Name of the app'),
+        app_description: z.string().describe('What the app does — 1-3 sentences'),
+        features: z.array(z.string()).max(10).optional()
+            .describe('Key features in order of importance. The first 2-3 will be highlighted most prominently.'),
+        brand_colors: z.object({
+            primary: z.string().describe('Primary brand color as hex (e.g. #7C3AED)'),
+            secondary: z.string().optional().describe('Secondary color as hex'),
+            accent: z.string().optional().describe('Accent color as hex'),
+        }).optional().describe('Brand colors to use in the design'),
+        mood: z.string().optional()
+            .describe('Design mood — e.g. "energetic", "calm", "minimal", "bold", "professional", "playful"'),
+        device_id: z.string().default('iphone-6.9')
+            .describe(`Target device. Options: ${VALID_DEVICE_IDS.join(', ')}. Default: iphone-6.9 (iPhone 16 Pro Max)`),
+        count: z.number().min(3).max(10).default(5)
+            .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.'),
+    }),
+}, async (input) => {
+    // Step 1: Create project
+    const projectName = `${input.app_name} Screenshots`;
+    const createRes = await apiCall('POST', '/api/v1/projects', {
+        device_id: input.device_id,
+        name: projectName,
+    });
+    if (!createRes.ok) {
+        return {
+            content: [{ type: 'text', text: `Failed to create project: ${JSON.stringify(createRes.data)}` }],
+        };
+    }
+    const project = createRes.data.data;
+    const projectId = project.id;
+    // Step 2: Chat to generate all cards
+    const message = buildDesignMessage(input);
+    const chatRes = await apiCall('POST', `/api/v1/projects/${projectId}/chat`, {
+        message,
+        selected_card_indices: [],
+    });
+    if (!chatRes.ok) {
+        return {
+            content: [{ type: 'text', text: `Project created (${projectId}) but design generation failed: ${JSON.stringify(chatRes.data)}` }],
+        };
+    }
+    const chatData = chatRes.data.data;
+    const creditsRemaining = chatRes.data.credits_remaining;
+    const projectUrl = `${API_BASE}/builder/${projectId}`;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `Generated ${chatData.canvas_state?.cards?.length || 0} screenshot cards for "${input.app_name}".`,
+                    '',
+                    chatData.message,
+                    '',
+                    `Project URL: ${projectUrl}`,
+                    `Project ID: ${projectId}`,
+                    `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',
+                    '',
+                    chatData.suggestions?.length
+                        ? `Suggestions: ${chatData.suggestions.join(', ')}`
+                        : '',
+                ].filter(Boolean).join('\n'),
+            }],
+    };
+});
+// Tool 2: edit-screenshots
+server.registerTool('edit-screenshots', {
+    title: 'Edit Screenshot Designs',
+    description: 'Make changes to an existing screenshot project. Use natural language to describe what you want to change — e.g. "make the headlines bigger", "change the color scheme to blue", "add a social proof card".',
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID from a previous generate-screenshots call'),
+        message: z.string().describe('What to change — use natural language'),
+    }),
+}, async ({ project_id, message }) => {
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/chat`, {
+        message,
+        selected_card_indices: [],
+    });
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Edit failed: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const data = res.data.data;
+    const creditsRemaining = res.data.credits_remaining;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    data.message,
+                    '',
+                    `Cards: ${data.canvas_state?.cards?.length || 0}`,
+                    `Credits remaining: ${creditsRemaining}`,
+                    `Project URL: ${API_BASE}/builder/${project_id}`,
+                    '',
+                    data.suggestions?.length
+                        ? `Suggestions: ${data.suggestions.join(', ')}`
+                        : '',
+                ].filter(Boolean).join('\n'),
+            }],
+    };
+});
+// Tool 3: render-screenshots
+server.registerTool('render-screenshots', {
+    title: 'Render Screenshots to PNG',
+    description: 'Export a screenshot project to high-resolution PNG files. Returns download URLs for each card. Note: device mockups will be empty unless screenshots have been uploaded via the web app first.',
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID to render'),
+    }),
+}, async ({ project_id }) => {
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/render`);
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Render failed: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const data = res.data.data;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `Rendered ${data.images?.length || 0} screenshots:`,
+                    '',
+                    ...(data.images || []).map((url, i) => `Card ${i + 1}: ${url}`),
+                ].join('\n'),
+            }],
+    };
+});
+// Tool 4: list-devices
+server.registerTool('list-devices', {
+    title: 'List Supported Devices',
+    description: 'Show all supported device specs for App Store and Play Store screenshots. Use the device ID when generating screenshots.',
+    inputSchema: z.object({}),
+}, async () => {
+    const lines = DEVICES.map(d => `${d.id} — ${d.name} (${d.width}×${d.height}, ${d.category}${d.required ? ', required for store submission' : ''})`);
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    'Supported devices:',
+                    '',
+                    ...lines,
+                    '',
+                    'Default: iphone-6.9 (iPhone 16 Pro Max, 1260×2736)',
+                    'For App Store, you need at least: iphone-6.9 + ipad-13',
+                ].join('\n'),
+            }],
+    };
+});
+// ─── Start server ───────────────────────────────────────────────────────────────
+async function main() {
+    if (!API_KEY) {
+        console.error('Warning: APPSCREENSHOTSTUDIO_API_KEY not set. Tools will fail until it is configured.');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('MCP server failed to start:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@appscreenshotstudio/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://appscreenshotstudio.com/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appscreenshotstudio/mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "app-store-screenshots",
+    "screenshot-generator",
+    "appscreenshotstudio",
+    "ai-tools"
+  ],
+  "bin": {
+    "appscreenshotstudio-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}