appmockupgenerator-mcp 1.0.1 → 1.1.1

package/README.md

@@ -72,6 +72,12 @@ On Windows, if `npx` isn't found, use `"command": "cmd", "args": ["/c", "npx", "
 - "Make App Store screenshots from the PNGs in ./fastlane/screenshots"
 - "Create Play Store screenshots for these 4 images, Vibrant Gradient style, in German"
 - "Capture my iOS Simulator screens and turn them into store screenshots"
+- "Make a panorama set from these 5 screens and A/B test minimal vs editorial"
+- "Localize my last 4 screenshots into German, Japanese and Portuguese (Brazil) with cultural adaptation"
+- "Convert these iPhone mockups to iPad and iPhone Duo"
+- "Score my current App Store screenshots" · "Make a Play Store feature graphic"
+- "Write and host a privacy policy, terms and support page for my app"
+- "Track my app and tell me when it hits a milestone"
 - Claude Code: type `/` and pick the `create_store_screenshots` prompt from the appmockup server for a guided flow.
 
 ### Where screenshots come from
@@ -90,20 +96,47 @@ Before generating, the assistant asks you which source to use:
 
 ## Tools
 
+Ask *"What can AppMockup do?"* and the assistant calls `capabilities` for the full list. Plan limits match the web app and are enforced by the server.
+
+**Store screenshots**
+
+| Tool | What it does | Credits | Plan |
+|---|---|---|---|
+| `generate_screenshots` | Raw screens → store screenshots. `mode` clean/dynamic, 7 styles, 19 copy languages, pop-out effect, title/subtitle colours, reference mockup, iPad native/compatibility, Magic Convert (iPad/Duo) | 1 each (+1 Magic Convert) | All (Duo: Pro+) |
+| `preview_titles` | AI headline + subtitle per screen, editable before paying | 0 | All |
+| `generate_panorama` | One continuous design across the set, sliced into panels. Art directions `dynamic`, `clean`, `frameless`, `editorial`; optional hero panel; 2–4 directions = A/B test | 1 per panel per direction | All (A/B: Starter+) |
+| `generate_hero_image` | Lifestyle hero / feature poster | 1 | All |
+
+**Edit, convert, localize**
+
+| Tool | What it does | Credits | Plan |
+|---|---|---|---|
+| `edit_screenshot` | Replace headline/subtitle, background, style, or any instruction | 1 each | Starter+ |
+| `match_style` | Copy the look of a reference image, URL or competitor listing | 1 each | Pro+ |
+| `convert_to_ipad` | iPhone mockup → iPad Pro 13", optional UI reflow | 1 each | Pro+ |
+| `convert_to_duo` | iPhone mockup → iPhone Duo inner/outer display | 1 per output | Pro+ |
+| `localize_screenshots` | 74 languages, native-sounding copy, optional cultural adaptation (colours, density, RTL) | 1 per screenshot per language | Pro+ |
+
+**Listing, legal, growth**
+
 | Tool | What it does | Credits |
 |---|---|---|
-| `check_account` | Key status, credits, plan | 0 |
-| `list_options` | Platforms, styles, languages, limits | 0 |
-| `choose_screenshot_source` | Asks you: files or simulator | 0 |
-| `find_screenshots` | Lists screenshot-sized images in a folder | 0 |
-| `list_devices` | Booted iOS Simulators / Android emulators | 0 |
-| `capture_simulator` | Saves the current screen of one device | 0 |
-| `preview_titles` | Proposed marketing copy per screenshot | 0 |
-| `generate_screenshots` | Creates the store screenshots (background job) | 1 per screenshot |
-| `get_job` | Progress and results (long-polls up to 55 s) | 0 |
-| `cancel_job` | Stops a job; unstarted screenshots aren't charged | 0 |
-
-Platforms: `ios`, `android`, `ipad`, `duo` (iPhone Duo is on the Pro and Studio plans). Up to 10 screenshots per run, 20 MB each, PNG/JPEG/WebP.
+| `generate_feature_graphic` | Google Play 1024×500 feature graphic (Starter+) | 1 |
+| `analyze_screenshots` | Score 0–100, grade, strengths, fixes | 0 |
+| `legal_pages_questions`, `generate_legal_pages`, `publish_legal_pages`, `list_legal_sites` | Privacy policy, terms, support and delete-account pages; saved locally, or hosted at `<name>.appfront.page` (hosting: monthly plans) | 0 |
+| `track_app`, `list_tracked_apps`, `refresh_tracked_app`, `app_milestones`, `set_tracking_alerts`, `untrack_app`, `tracking_limits` | Daily ratings/reviews/installs and milestone alerts (Free 1 app, Starter 2, Pro 5, Studio 30) | 0 |
+| `submit_to_showcase`, `my_showcase_submissions`, `withdraw_showcase_submission` | Feature your live app on the AppMockup Showcase | 0 |
+
+**Workflow & account**
+
+| Tool | What it does |
+|---|---|
+| `capabilities`, `list_options`, `check_account` | What's possible, exact option values, credits and plan |
+| `choose_screenshot_source`, `find_screenshots`, `list_devices`, `capture_simulator` | Pick files or capture from a simulator |
+| `get_job`, `cancel_job` | Follow any background job (long-polls up to 55 s); cancelled items aren't charged |
+| `list_history`, `download_assets` | Everything you generated (web or MCP). The URLs can be passed straight into edit/convert/localize/match |
+
+Platforms: `ios`, `android`, `ipad`, `duo`. Up to 10 images per run, 20 MB each, PNG/JPEG/WebP. Web-only: landing page builder, icon resizer, store listing preview.
 
 ## Configuration
 
@@ -147,5 +180,8 @@ Debug with the MCP Inspector: `npm run build && npm run inspect`.
 npm install
 npm run build
 node scripts/smoke-test.mjs ../public               # offline tool checks
-node scripts/pipeline-test.mjs a.png b.png c.png    # full pipeline against a mocked API
+node scripts/pipeline-test.mjs a.png b.png c.png    # screenshot pipeline against a mocked API
+node scripts/features-test.mjs a.png                # every feature tool against a mocked API
 ```
+
+`npm run build` first copies the legal-document generator from `../services/legalDocs` (`scripts/sync-shared.mjs`), so legal pages match the web wizard exactly.

package/dist/api.js

@@ -33,6 +33,9 @@ function mapApiError(status, body, context) {
         }
         return new AppMockupError('API_KEY_INVALID', 'AppMockup rejected the API key.', `Copy a valid key from ${API_KEYS_URL} into APPMOCKUP_API_KEY and restart your AI client.`);
     }
+    if (status === 402 && (code === 'APP_LIMIT' || code === 'PAID_REQUIRED')) {
+        return new AppMockupError('PLAN_REQUIRED', serverMsg || 'This needs a higher plan.', `See plans at ${PRICING_URL}.`, typeof body.limit === 'number' ? { limit: body.limit } : undefined);
+    }
     if (status === 402) {
         const credits = Number(body.currentCredits ?? 0);
         return new AppMockupError('INSUFFICIENT_CREDITS', `Not enough credits (you have ${credits}).`, `Each screenshot costs 1 credit. Buy credits or upgrade at ${PRICING_URL}, then retry.`, { credits });
@@ -47,17 +50,30 @@ function mapApiError(status, body, context) {
         const mins = retryAfter ? Math.ceil(retryAfter / 60) : undefined;
         return new AppMockupError('RATE_LIMITED', serverMsg || 'Rate limit reached.', mins ? `Wait about ${mins} minute(s) and retry.` : 'Wait a few minutes and retry.', retryAfter ? { retryAfterSeconds: retryAfter } : undefined);
     }
+    if (status === 404 && body.error && !/session/i.test(serverMsg ?? '') && typeof body.error === 'string' && !/endpoint/i.test(body.error)) {
+        // A JSON 404 from a real endpoint means "that thing does not exist" (app, batch, site).
+        return new AppMockupError('INVALID_INPUT', `${context}: ${serverMsg}`, 'Check the id or URL and try again.');
+    }
     if (status === 404 && /session/i.test(serverMsg ?? '')) {
         return new AppMockupError('SESSION_EXPIRED', 'The title preview expired (previews last 1 hour).', 'Run preview_titles again, or call generate_screenshots with the files directly.');
     }
     if (status === 404) {
         return new AppMockupError('SERVICE_UNAVAILABLE', `${context}: this AppMockup API endpoint was not found.`, 'The server may not support MCP yet, or APPMOCKUP_API_URL points to the wrong environment (amk_test_ keys use /test-api, amk_live_ keys use /api).');
     }
-    if (status === 400 || status === 413) {
+    if (status === 409) {
+        return new AppMockupError('INVALID_INPUT', serverMsg || `${context}: this already exists.`, 'Nothing was changed.');
+    }
+    if (status === 410) {
+        return new AppMockupError('SESSION_EXPIRED', serverMsg || `${context}: this has expired.`, 'Start the operation again.');
+    }
+    if (status === 424) {
+        return new AppMockupError('SERVICE_UNAVAILABLE', serverMsg || 'The app store did not respond.', 'Try again in a few minutes.');
+    }
+    if (status === 400 || status === 413 || status === 422) {
         return new AppMockupError('INVALID_INPUT', serverMsg ? `${context}: ${serverMsg}` : `${context}: the request was rejected.`, 'Check the screenshots and options, then retry.');
     }
     if (status === 503 || status === 502) {
-        return new AppMockupError('SERVICE_UNAVAILABLE', 'AppMockup is temporarily unavailable.', 'Wait a minute and retry.');
+        return new AppMockupError('SERVICE_UNAVAILABLE', serverMsg || 'AppMockup is temporarily unavailable.', 'Wait a minute and retry. Failed generations are refunded automatically.');
     }
     if (status === 504) {
         return new AppMockupError('TIMEOUT', `${context} timed out on the server.`, `If a screenshot was created it appears in ${HISTORY_URL}; check there before retrying so you don't spend another credit.`);
@@ -124,8 +140,11 @@ export class ApiClient {
             throw err;
         }
     }
+    /** Plan from the most recent account check (for plan-aware suggestions). */
+    lastPlan;
     async account() {
         const acc = await this.request('mcp-account.php', 'Account check', { timeoutMs: 20_000, idempotent: true });
+        this.lastPlan = acc.plan;
         if (!this.accountChecked && acc.minClientVersion && semverLt(VERSION, acc.minClientVersion)) {
             throw new AppMockupError('CLIENT_OUTDATED', `This AppMockup MCP server (v${VERSION}) is out of date.`, 'Restart your AI client; npx -y appmockupgenerator-mcp fetches the latest version.');
         }
@@ -200,7 +219,7 @@ export class ApiClient {
         });
         return Number(res.updated ?? 0);
     }
-    /** Spends 1 credit (refunded server-side if generation fails). Never auto-retried after sending. */
+    /** Spends 1 credit (+1 for Magic Convert); refunded server-side on failure. Never auto-retried after sending. */
     async generate(args) {
         const res = await this.request('generate-mockup.php', 'Screenshot generation', {
             body: {
@@ -214,25 +233,57 @@ export class ApiClient {
                 customInstructions: args.customInstructions ?? '',
                 twistEnabled: args.twist,
                 twistType: args.twist ? 'ai-decides' : 'none',
+                specialEffect: args.specialEffect ?? 'none',
+                ...(args.colors && (args.colors.title || args.colors.subtitle) ? { colors: args.colors } : {}),
+                ...(args.ipadMode ? { ipadMode: args.ipadMode } : {}),
+                adaptUiToIpad: Boolean(args.magicConvert),
+                ...(args.reference ? { referenceAssetBase64: args.reference } : {}),
                 originalFileName: args.fileName,
             },
             timeoutMs: 330_000,
             idempotent: false,
         });
-        const url = res.mockup?.assets?.origUrl;
+        return this.assetFrom(res, 'Screenshot generation');
+    }
+    /**
+     * Generic call to an AppMockup endpoint that accepts API keys.
+     * `idempotent: false` for anything that can spend credits.
+     */
+    async post(endpoint, context, body, opts = {}) {
+        return this.request(endpoint, context, {
+            body: { supportsAssetUrls: true, ...body },
+            timeoutMs: opts.timeoutMs ?? 120_000,
+            idempotent: opts.idempotent ?? false,
+        });
+    }
+    /** Pull the stored image out of any generation response (flat or nested `mockup`). */
+    assetFrom(res, context) {
+        const mockup = (res.mockup ?? {});
+        const assets = (res.assets ?? mockup.assets ?? {});
+        const url = assets.origUrl;
         if (!url) {
-            throw new AppMockupError('GENERATION_FAILED', 'The server finished without returning an image.', `Check ${HISTORY_URL}; if nothing is there, retry this screenshot.`);
+            throw new AppMockupError('GENERATION_FAILED', `${context} finished without returning a stored image.`, `Check ${HISTORY_URL}; if nothing is there, retry.`);
         }
         this.assertCdnUrl(url);
         return {
             url,
-            title: res.mockup?.title ?? '',
-            subtitle: res.mockup?.subtitle ?? '',
-            width: Number(res.mockup?.assets?.width ?? 0),
-            height: Number(res.mockup?.assets?.height ?? 0),
+            title: String(mockup.title ?? res.title ?? ''),
+            subtitle: String(mockup.subtitle ?? res.subtitle ?? ''),
+            width: Number(assets.width ?? 0),
+            height: Number(assets.height ?? 0),
             creditsRemaining: typeof res.creditsRemaining === 'number' ? res.creditsRemaining : null,
         };
     }
+    /** True for https URLs on AppMockup's own CDN (the only URLs the API accepts as image input). */
+    isOwnCdnUrl(raw) {
+        try {
+            const u = new URL(raw);
+            return u.protocol === 'https:' && this.config.allowedCdnHosts.includes(u.hostname);
+        }
+        catch {
+            return false;
+        }
+    }
     /** Download a finished asset. Only our own CDN, bounded size, verified bytes. */
     async download(url) {
         this.assertCdnUrl(url);

package/dist/catalog.js

@@ -0,0 +1,79 @@
+/**
+ * Product catalog exposed to the model. Mirrors the web app:
+ *  - styles:            components/StyleSelector.tsx
+ *  - panorama variants: services/geminiPhpService.ts PANORAMA_VARIANTS / api-php/panorama-prompt.php
+ *  - feature graphic:   pages/FeatureGraphicPage.tsx
+ *  - localize langs:    pages/LocalizeScreenshotsPage.tsx SUPPORTED_LANGUAGES
+ *  - plan gating:       services/tierService.ts (enforced server-side for API keys)
+ */
+export const STYLES = [
+    'Default',
+    'Futuristic Dark Mode',
+    'Clean & Minimal Light',
+    'Vibrant Gradient',
+    'Professional Corporate Blue',
+    'Claymorphism 3D',
+    'Elegant Pastel',
+];
+/** Languages for AI-written copy during generation. */
+export const LANGUAGES = ['en', 'es', 'fr', 'de', 'it', 'pt', 'nl', 'ja', 'ko', 'zh', 'ar', 'hi', 'ru', 'tr', 'pl', 'sv', 'id', 'th', 'vi'];
+export const PANORAMA_VARIANTS = [
+    { id: 'dynamic', label: 'Dynamic scene', description: 'Layered photoreal scene with 3D objects and features popping out of the phone. The boldest.' },
+    { id: 'clean', label: 'Minimal', description: 'One refined surface, devices and type. No props, no effects. Calm and premium.' },
+    { id: 'frameless', label: 'Frameless UI', description: 'No phone frame: the screen as a large rounded card on a soft backdrop. Most readable UI.' },
+    { id: 'editorial', label: 'Bold editorial', description: 'Flat poster design: colour blocking, oversized type, graphic shapes. Built to stop a scroll.' },
+];
+export const PANORAMA_MAX_PANELS = 10;
+export const FEATURE_GRAPHIC_STYLES = ['auto', 'minimal', 'bold', '3d-premium', 'lifestyle', 'dark'];
+/** Store localization languages (code → name). The name is what the renderer is told. */
+export const LOCALIZE_LANGUAGES = {
+    en: 'English', zh: 'Chinese (Simplified)', 'zh-TW': 'Chinese (Traditional)', ja: 'Japanese', ko: 'Korean', de: 'German',
+    es: 'Spanish', fr: 'French', 'pt-BR': 'Portuguese (Brazil)', ru: 'Russian', it: 'Italian', ar: 'Arabic', hi: 'Hindi',
+    tr: 'Turkish', nl: 'Dutch', id: 'Indonesian', th: 'Thai', vi: 'Vietnamese', pl: 'Polish', sv: 'Swedish',
+    af: 'Afrikaans', am: 'Amharic', hy: 'Armenian', az: 'Azerbaijani', eu: 'Basque', be: 'Belarusian', bn: 'Bangla',
+    bg: 'Bulgarian', my: 'Burmese', ca: 'Catalan', hr: 'Croatian', cs: 'Czech', da: 'Danish', et: 'Estonian',
+    fil: 'Filipino', fi: 'Finnish', 'fr-CA': 'French (Canada)', gl: 'Galician', ka: 'Georgian', el: 'Greek',
+    gu: 'Gujarati', he: 'Hebrew', hu: 'Hungarian', is: 'Icelandic', kn: 'Kannada', kk: 'Kazakh', km: 'Khmer',
+    ky: 'Kyrgyz', lo: 'Lao', lv: 'Latvian', lt: 'Lithuanian', mk: 'Macedonian', ms: 'Malay', ml: 'Malayalam',
+    mr: 'Marathi', mn: 'Mongolian', ne: 'Nepali', no: 'Norwegian', or: 'Odia', fa: 'Persian', pt: 'Portuguese (Portugal)',
+    pa: 'Punjabi', ro: 'Romanian', sr: 'Serbian', si: 'Sinhala', sk: 'Slovak', sl: 'Slovenian', 'es-MX': 'Spanish (Mexico)',
+    sw: 'Swahili', ta: 'Tamil', te: 'Telugu', uk: 'Ukrainian', ur: 'Urdu', zu: 'Zulu',
+};
+/** Human summary returned by the `capabilities` tool. Keep in sync with the tools. */
+export const CAPABILITIES = `AppMockup can do all of this from your AI assistant (1 credit = 1 generated image unless noted):
+
+CREATE STORE SCREENSHOTS
+• generate_screenshots: raw screenshots → App Store / Google Play marketing screenshots with device frame, background and headline.
+  Platforms: iPhone (ios), Android, iPad, iPhone Duo (Pro/Studio). Modes: clean (minimal) or dynamic (themed 3D scenes).
+  Options: 7 visual styles, copy in ${LANGUAGES.length} languages, pop-out effect, custom title/subtitle colours, art-direction instructions,
+  match a reference mockup, iPad native vs compatibility, Magic Convert (rebuild a phone UI as a real iPad/Duo layout, +1 credit).
+• preview_titles (free): AI headline + subtitle per screen to review and edit before paying.
+• generate_panorama: the whole set as ONE continuous wide design, sliced into panels. Art directions: dynamic, clean (minimal),
+  frameless, editorial. Optional hero first panel. A/B test 2-4 art directions in one go (Starter+). Up to ${PANORAMA_MAX_PANELS} panels.
+• generate_hero_image: a lifestyle "feature poster" hero panel for the listing.
+
+EDIT & REUSE
+• edit_screenshot (Starter+): change the headline/subtitle, background, style, or any free-form edit on a finished mockup.
+• match_style (Pro+): copy the look of a reference screenshot (yours or a competitor's, by image or store URL).
+• convert_to_ipad (Pro+): turn an iPhone mockup into an iPad Pro 13" store screenshot, optionally reflowing the UI.
+• convert_to_duo (Pro/Studio): turn an iPhone mockup into iPhone Duo inner or outer display screenshots.
+
+GO GLOBAL
+• localize_screenshots (Pro+): translate finished screenshots into ${Object.keys(LOCALIZE_LANGUAGES).length} store languages with native-sounding copy,
+  optional cultural adaptation (colours, density, typography, RTL). 1 credit per screenshot per language.
+
+STORE ASSETS & LISTING
+• generate_feature_graphic (Starter+): Google Play 1024×500 feature graphic.
+• analyze_screenshots (free): score 0-100, grade, strengths and fixes for your current screenshots.
+• legal_pages_questions / generate_legal_pages / publish_legal_pages: privacy policy, terms, support and delete-account pages
+  (free to generate; hosting on yourapp.appfront.page is a monthly-plan feature).
+
+GROWTH
+• App tracking: track_app, list_tracked_apps, refresh_tracked_app, app_milestones, untrack_app, tracking_limits — daily ratings/
+  reviews/installs and milestone alerts (Free: 1 app, Starter 2, Pro 5, Studio 30).
+• Showcase: submit_to_showcase, my_showcase_submissions, withdraw_showcase_submission — feature your live app on appmockupgenerator.com.
+
+HISTORY
+• list_history / download_assets: everything you generated (web or MCP), reusable as input to edit/convert/localize.
+
+WEB-ONLY (open appmockupgenerator.com): AI landing page builder, icon resizer, store listing preview.`;

package/dist/config.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { AppMockupError, API_KEYS_URL } from './errors.js';
-export const VERSION = '1.0.0';
+export const VERSION = '1.1.0';
 const KEY_RE = /^amk_(live|test)_[A-Za-z0-9]{40}$/;
 const PRODUCTION_API = 'https://api.appmockupgenerator.com/api';
 const STAGING_API = 'https://api.appmockupgenerator.com/test-api';

package/dist/helpers.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AppMockupError, PRICING_URL, toAppMockupError } from './errors.js';
+import { MAX_FILES_PER_JOB, readLocalImage, resolveUserPath } from './images.js';
+export const ok = (text, structured) => ({
+    content: [{ type: 'text', text }],
+    ...(structured ? { structuredContent: structured } : {}),
+});
+export const fail = (err) => ({
+    content: [{ type: 'text', text: toAppMockupError(err).toText() }],
+    isError: true,
+});
+/** Wraps every handler so no exception (or secret) escapes unformatted. */
+export function safe(log, name, fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (err) {
+            const e = toAppMockupError(err);
+            if (e.code === 'SERVER_ERROR' && !(err instanceof AppMockupError)) {
+                log(`tool ${name} unexpected error: ${err?.message ?? String(err)}`);
+            }
+            return fail(e);
+        }
+    };
+}
+/** Workspace root from the client (MCP roots), falling back to the process cwd. */
+export async function baseDir(ctx) {
+    try {
+        if (ctx.server.server.getClientCapabilities()?.roots) {
+            const { roots } = await ctx.server.server.listRoots(undefined, { timeout: 3000 });
+            const first = roots.find((r) => r.uri.startsWith('file://'));
+            if (first)
+                return fileURLToPath(first.uri);
+        }
+    }
+    catch { /* client without roots support */ }
+    return process.cwd();
+}
+export async function writableDir(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.access(dir, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Where results go: explicit arg > APPMOCKUP_OUTPUT_DIR > <workspace>/appmockup-output > ~/AppMockup. */
+export async function outputRoot(ctx, explicit) {
+    const base = await baseDir(ctx);
+    if (explicit)
+        return resolveUserPath(explicit, base);
+    if (ctx.config.outputDir)
+        return ctx.config.outputDir;
+    const isSystemDir = base === path.parse(base).root || base === os.homedir();
+    const candidate = path.join(base, 'appmockup-output');
+    if (!isSystemDir && await writableDir(candidate))
+        return candidate;
+    return path.join(os.homedir(), 'AppMockup');
+}
+export const stamp = () => new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+/** <root>/<timestamp>-<label> unless the user picked a folder. */
+export async function jobOutputDir(ctx, explicit, label) {
+    const root = await outputRoot(ctx, explicit);
+    return explicit ? root : path.join(root, `${stamp()}-${label}`);
+}
+export function canElicit(ctx) {
+    return Boolean(ctx.server.server.getClientCapabilities()?.elicitation);
+}
+/**
+ * Credit gate shared by every paid tool: checks the balance, then asks the user
+ * (elicitation dialog when supported, otherwise via the assistant + confirm flag).
+ * Returns a tool result to send back when the run must NOT start, or null to proceed.
+ */
+export async function confirmSpend(ctx, opts) {
+    const acc = await ctx.api.account();
+    if (acc.credits < opts.cost) {
+        throw new AppMockupError('INSUFFICIENT_CREDITS', `${opts.what} needs ${opts.cost} credit(s) but you have ${acc.credits}.`, `Buy credits or upgrade at ${acc.pricingUrl || PRICING_URL}, or reduce the request.`, { credits: acc.credits, needed: opts.cost });
+    }
+    const summary = `${opts.what} for ${opts.cost} credit(s)? You have ${acc.credits}.`;
+    if (canElicit(ctx)) {
+        const res = await ctx.server.server.elicitInput({
+            mode: 'form',
+            message: summary,
+            requestedSchema: { type: 'object', properties: { confirm: { type: 'boolean', title: 'Spend credits and continue', default: true } }, required: ['confirm'] },
+        });
+        if (res.action !== 'accept' || res.content?.confirm !== true) {
+            return ok('The user declined. Nothing was generated and no credits were spent.', { started: false });
+        }
+        return null;
+    }
+    if (!opts.confirmed) {
+        return ok(`Confirmation needed. Ask the user: "${summary}" If they agree, call ${opts.toolName} again with the same arguments and confirm_credit_spend: true.`, { started: false, needs_confirmation: true, credits: acc.credits, cost: opts.cost });
+    }
+    return null;
+}
+/**
+ * Accepts local file paths and AppMockup CDN URLs (e.g. a URL returned by an
+ * earlier job or list_history). Local files are validated and uploaded once.
+ */
+export async function resolveImages(ctx, inputs, opts = {}) {
+    const max = opts.max ?? MAX_FILES_PER_JOB;
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+        throw new AppMockupError('INVALID_INPUT', `No ${opts.label ?? 'images'} were given.`, 'Pass local file paths, or AppMockup image URLs from a previous result or list_history.');
+    }
+    if (inputs.length > max) {
+        throw new AppMockupError('TOO_MANY_FILES', `${inputs.length} images given; the maximum here is ${max}.`, 'Select fewer images.');
+    }
+    const base = await baseDir(ctx);
+    const out = [];
+    for (const raw of inputs) {
+        const value = String(raw ?? '').trim();
+        if (/^https?:\/\//i.test(value)) {
+            if (!ctx.api.isOwnCdnUrl(value)) {
+                throw new AppMockupError('INVALID_INPUT', `Only AppMockup image URLs can be used directly (got ${new URL(value).hostname}).`, 'Download the image and pass the local file path instead.');
+            }
+            out.push({ ref: value, name: path.basename(new URL(value).pathname) || 'asset.png', source: value });
+            continue;
+        }
+        const img = await readLocalImage(value, base);
+        const url = await ctx.api.uploadScreenshot(img.data, img.mime);
+        out.push({ ref: url ?? `data:${img.mime};base64,${img.data.toString('base64')}`, name: img.name, source: img.path, local: img });
+    }
+    return out;
+}

package/dist/index.js

@@ -8,13 +8,17 @@ import { JobManager } from './jobs.js';
 import { registerTools } from './tools.js';
 // stdout is the MCP protocol channel: all diagnostics go to stderr, and never include secrets.
 const log = (msg) => process.stderr.write(`[appmockupgenerator-mcp] ${msg}\n`);
-const INSTRUCTIONS = `AppMockup turns raw app screenshots into App Store / Google Play marketing screenshots.
-Workflow:
+const INSTRUCTIONS = `AppMockup creates App Store / Google Play marketing assets: store screenshots, panorama sets, hero images, feature graphics, edits, style matches, iPad/iPhone Duo conversions, localization into 70+ languages, plus a free screenshot analyzer, legal pages, app tracking and the Showcase. Call capabilities when the user asks what is possible.
+Workflow for new screenshots:
 1. If the user has not given screenshot files, call choose_screenshot_source and follow the user's choice. Recommend existing files; only capture from a simulator when the user asks, one screen at a time, after the user navigates to it.
-2. Confirm the platform (ios, android, ipad, duo).
-3. Optionally run preview_titles (free) and let the user edit the copy.
-4. generate_screenshots costs 1 credit per screenshot: confirm the cost with the user first. It runs in the background; follow it with get_job (wait_seconds 55) until finished, then report the saved file paths.
-Errors include a code and a "How to fix" line: relay the fix to the user instead of retrying blindly. Never retry a generation that timed out without checking History first.`;
+2. Call choose_design so the user picks the layout, art direction and platform. Do not skip this: many users don't know panorama exists. Panorama (one continuous design across the set, plus a hero panel) is the recommended default, the same as on appmockupgenerator.com; individual screenshots (clean or dynamic) are the alternative. Skip it only if the user already named the layout.
+3. Panorama → generate_panorama. Individual → optionally preview_titles (free) so the user can edit the copy, then generate_screenshots.
+4. Every paid tool states its credit cost and needs the user's confirmation. Paid tools run in the background: follow them with get_job (wait_seconds 55) until finished, then report the saved file paths.
+Results include AppMockup URLs that can be fed straight into edit_screenshot, convert_to_ipad, convert_to_duo, localize_screenshots or match_style.
+NEXT STEPS: finished jobs and most tools end with a "NEXT STEPS" block tailored to what the user just made, their plan and what they already did. Always show it to the user as a short numbered menu at the end of your reply (e.g. "Want me to localize these into Japanese and German, make the iPad versions, or change a headline?"). Never run a suggestion without the user's go-ahead. If the user picks one, the block already lists the tool and the image URLs to pass.
+When a tool answers with needs_input (e.g. which languages, which reference, what to change), ask the user that question; nothing was charged.
+Some tools need a plan (edit/feature graphic: Starter+; match style, iPad/Duo conversion, localization: Pro+). If one returns PLAN_REQUIRED, tell the user which plan unlocks it.
+Errors include a code and a "How to fix" line: relay the fix to the user instead of retrying blindly. Never retry a generation that timed out without checking list_history first.`;
 async function main() {
     let config;
     try {