appmockupgenerator-mcp 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# AppMockup MCP server
+
+Turn raw app screenshots into App Store and Google Play marketing screenshots, with device frame, background and headline, without leaving Claude Code, Cursor, VS Code or Claude Desktop.
+
+```
+You:   Make App Store screenshots from the PNGs in ./screenshots
+Agent: Found 5 screenshots. Proposed titles: 1. "Plan your week in seconds" …
+       This will use 5 credits (you have 70). Go ahead?
+You:   Yes
+Agent: Done. Saved to ./appmockup-output/20261101-104512/01-plan-your-week-in-seconds.png …
+```
+
+The server runs locally on your machine. It reads only the image files you point it at, uploads them to AppMockup, and saves the finished PNGs back into your project. It uses the credits on your AppMockup account: 1 credit per generated screenshot, the same as the web app. Results also appear in your web History.
+
+## 1. Get your API key
+
+1. Sign in at [appmockupgenerator.com](https://appmockupgenerator.com). New accounts get free credits.
+2. Verify your email address if you haven't (check your inbox for the link).
+3. Open **Studio → API & MCP** in the sidebar, or go to [appmockupgenerator.com/studio/api-keys](https://appmockupgenerator.com/studio/api-keys).
+4. Enter a name (e.g. "MacBook – Claude Code") and click **Create key**.
+5. Copy the key (`amk_live_…`). **It is shown only once.** If you lose it, revoke it and create a new one.
+
+Treat the key like a password: anyone who has it can spend your credits. Don't commit it to git. You can have up to 5 active keys and revoke any of them instantly from the same page.
+
+## 2. Add the server to your AI client
+
+Requires **Node.js 18.17+** (`node -v`).
+
+**Claude Code**
+
+```bash
+claude mcp add appmockup --scope user --env APPMOCKUP_API_KEY=amk_live_YOUR_KEY -- npx -y appmockupgenerator-mcp
+```
+
+**Claude Desktop**: Settings → Developer → Edit Config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "appmockup": {
+      "command": "npx",
+      "args": ["-y", "appmockupgenerator-mcp"],
+      "env": { "APPMOCKUP_API_KEY": "amk_live_YOUR_KEY" }
+    }
+  }
+}
+```
+
+**Cursor**: `~/.cursor/mcp.json` (same JSON as Claude Desktop).
+
+**VS Code**: `.vscode/mcp.json`, or run "MCP: Open User Configuration":
+
+```json
+{
+  "servers": {
+    "appmockup": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "appmockupgenerator-mcp"],
+      "env": { "APPMOCKUP_API_KEY": "amk_live_YOUR_KEY" }
+    }
+  }
+}
+```
+
+Restart the client, then ask: *"Check my AppMockup account."* You should see your credit balance.
+
+On Windows, if `npx` isn't found, use `"command": "cmd", "args": ["/c", "npx", "-y", "appmockupgenerator-mcp"]`.
+
+## 3. Use it
+
+- "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"
+- Claude Code: type `/` and pick the `create_store_screenshots` prompt from the appmockup server for a guided flow.
+
+### Where screenshots come from
+
+Before generating, the assistant asks you which source to use:
+
+1. **Your screenshot files (recommended).** You choose exactly which 4–8 screens appear, in which order. Point at files or a folder; `find_screenshots` lists candidate images so you can pick.
+2. **A running simulator/emulator.** The assistant asks you to open each screen you want, then captures **one screen per step** (`xcrun simctl` for the iOS Simulator on macOS, `adb` for Android). The AI never decides on its own which screens to capture.
+
+### Flow
+
+1. `choose_screenshot_source`: asks you files vs. simulator.
+2. `preview_titles` (free, optional): proposes a headline and subtitle per screenshot. Edit any of them.
+3. `generate_screenshots`: shows the credit cost and asks you to confirm, then runs in the background.
+4. `get_job`: reports progress, then the saved file paths. A `manifest.json` with titles and order is written next to the PNGs.
+
+## Tools
+
+| 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.
+
+## Configuration
+
+| Variable | Required | Description |
+|---|---|---|
+| `APPMOCKUP_API_KEY` | yes | Your key from the API & MCP page |
+| `APPMOCKUP_OUTPUT_DIR` | no | Where to save results. Default: `<workspace>/appmockup-output/<timestamp>`, or `~/AppMockup` when the client has no workspace |
+
+## Security
+
+- **The key stays local.** It is read from the environment, sent only in the `X-API-Key` header over HTTPS to `api.appmockupgenerator.com`, and never logged or shown to the model. AppMockup stores only a keyed hash (HMAC) of it, never the key itself.
+- **Only images leave your machine.** Files are checked by their magic bytes (PNG/JPEG/WebP) and size before anything is read or uploaded. A path to any other kind of file is refused, even if a prompt asks for it.
+- **Fixed destinations.** Uploads go only to AppMockup's Cloudflare R2 storage, and downloads come only from `cdn.appmockupgenerator.com`. Redirects are refused.
+- **No shell.** Simulator capture runs `xcrun`/`adb` with fixed arguments and validated device ids.
+- **Spending needs your consent.** Generation states the credit cost and needs your confirmation. Clients that support MCP elicitation show a dialog; others require the assistant to ask you first.
+- **Server-side limits.** Requests are rate-limited per key, credits are deducted atomically, and failed generations are refunded automatically. Revoking a key takes effect within a minute.
+
+## Troubleshooting
+
+Every error has a code and a "How to fix" line. Common ones:
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `CONFIG_MISSING_API_KEY` | No key in the MCP config | Add `APPMOCKUP_API_KEY` to `env` and restart the client |
+| `CONFIG_INVALID_API_KEY` / `API_KEY_INVALID` | Key mistyped or deleted | Copy the full key again, or create a new one |
+| `API_KEY_REVOKED` | Key was revoked | Create a new key and update the config |
+| `INSUFFICIENT_CREDITS` | Not enough credits for this run | Buy credits at appmockupgenerator.com/pricing, or select fewer screenshots |
+| `EMAIL_NOT_VERIFIED` | Account email not verified | Click the link in your verification email |
+| `PLAN_REQUIRED` | Option needs a higher plan (e.g. iPhone Duo) | Upgrade or choose another platform |
+| `RATE_LIMITED` | Too many requests | Wait for the time shown, then retry |
+| `FILE_NOT_IMAGE` / `IMAGE_TOO_SMALL` / `FILE_TOO_LARGE` | Input file problem | Use full-resolution PNG/JPEG/WebP screenshots, 20 MB max |
+| `SIMULATOR_NOT_RUNNING` / `SIMULATOR_TOOL_MISSING` | No booted device, or no Xcode/adb | Start the simulator/emulator, or use files instead |
+| `TIMEOUT` during generation | The server didn't answer in time | Check History before retrying, so you don't pay twice |
+| `SESSION_EXPIRED` | Title preview is older than ~55 minutes | Run `preview_titles` again |
+
+Debug with the MCP Inspector: `npm run build && npm run inspect`.
+
+## Development
+
+```bash
+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
+```

package/dist/api.js

@@ -0,0 +1,275 @@
+import { VERSION, requireApiKey } from './config.js';
+import { AppMockupError, API_KEYS_URL, HISTORY_URL, PRICING_URL, toAppMockupError } from './errors.js';
+import { imageInfo } from './images.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Errors that happened before the server could have processed anything. */
+function isPreRequestNetworkError(err) {
+    const cause = err?.cause;
+    const code = cause?.code ?? err?.code;
+    return code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EAI_AGAIN' || code === 'UND_ERR_CONNECT_TIMEOUT';
+}
+function semverLt(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y;
+    }
+    return false;
+}
+/** Map an HTTP error from the AppMockup API to a helpful, user-facing error. */
+function mapApiError(status, body, context) {
+    const code = typeof body.code === 'string' ? body.code : '';
+    const serverMsg = [body.message, body.error, body.details].find((v) => typeof v === 'string' && v.trim());
+    const retryAfter = Number(body.retryAfterSeconds ?? body.resetsIn ?? 0) || undefined;
+    if (code === 'API_KEY_REVOKED') {
+        return new AppMockupError('API_KEY_REVOKED', 'This API key was revoked.', `Create a new key at ${API_KEYS_URL} and update APPMOCKUP_API_KEY in your MCP config.`);
+    }
+    if (status === 401 || code === 'API_KEY_INVALID' || code === 'API_KEY_MISSING') {
+        if (code === 'ACCOUNT_NOT_FOUND') {
+            return new AppMockupError('ACCOUNT_NOT_FOUND', 'The account linked to this API key no longer exists.', `Sign in at ${API_KEYS_URL} and create a new key.`);
+        }
+        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) {
+        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 });
+    }
+    if (status === 403 && code === 'EMAIL_NOT_VERIFIED') {
+        return new AppMockupError('EMAIL_NOT_VERIFIED', 'Your AppMockup email address is not verified.', 'Click the verification link in your inbox, then retry.');
+    }
+    if (status === 403) {
+        return new AppMockupError('PLAN_REQUIRED', serverMsg || 'This option is not included in your plan.', `See plans at ${PRICING_URL}, or choose another platform.`);
+    }
+    if (status === 429) {
+        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 && /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) {
+        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.');
+    }
+    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.`);
+    }
+    return new AppMockupError('SERVER_ERROR', `${context} failed (HTTP ${status})${serverMsg ? `: ${serverMsg}` : ''}.`, 'Retry. Credits for failed generations are refunded automatically.');
+}
+export class ApiClient {
+    config;
+    accountChecked = false;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(endpoint, context, opts) {
+        const apiKey = requireApiKey(this.config);
+        const url = `${this.config.apiBaseUrl}/${endpoint}`;
+        const maxAttempts = opts.idempotent ? 3 : 2;
+        for (let attempt = 1;; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': apiKey,
+                        'User-Agent': `appmockupgenerator-mcp/${VERSION} (node ${process.version}; ${process.platform})`,
+                        'X-AppMockup-Client': `mcp/${VERSION}`,
+                    },
+                    body: JSON.stringify(opts.body ?? {}),
+                    signal: AbortSignal.timeout(opts.timeoutMs),
+                    redirect: 'error',
+                });
+            }
+            catch (err) {
+                // Only repeat a non-idempotent call when the request provably never left.
+                const retryable = attempt < maxAttempts && (opts.idempotent || isPreRequestNetworkError(err));
+                if (retryable) {
+                    await sleep(1000 * attempt * attempt);
+                    continue;
+                }
+                const mapped = toAppMockupError(err);
+                if (mapped.code === 'TIMEOUT' && !opts.idempotent) {
+                    throw new AppMockupError('TIMEOUT', `${context} took too long to respond.`, `It may still finish: check ${HISTORY_URL} before retrying so you don't spend another credit.`);
+                }
+                throw mapped;
+            }
+            const text = await res.text();
+            let body = {};
+            try {
+                body = text ? JSON.parse(text) : {};
+            }
+            catch { /* non-JSON (proxy error page) */ }
+            // 200 + { success:false, reason } is a soft "not available" answer (e.g. storage disabled).
+            if (res.ok && (body.success !== false || typeof body.reason === 'string'))
+                return body;
+            const err = mapApiError(res.status, body, context);
+            const retryAfter = Number(err.details?.retryAfterSeconds ?? 0);
+            const canRetry = attempt < maxAttempts && ((err.code === 'RATE_LIMITED' && body.code === 'RATE_LIMITED' && retryAfter > 0 && retryAfter <= 30) ||
+                // Auth-layer 503s happen before any credit is deducted.
+                (err.code === 'SERVICE_UNAVAILABLE' && (opts.idempotent || body.code === 'SERVICE_UNAVAILABLE')));
+            if (canRetry) {
+                await sleep(retryAfter > 0 ? retryAfter * 1000 : 2000 * attempt);
+                continue;
+            }
+            throw err;
+        }
+    }
+    async account() {
+        const acc = await this.request('mcp-account.php', 'Account check', { timeoutMs: 20_000, idempotent: true });
+        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.');
+        }
+        this.accountChecked = true;
+        return acc;
+    }
+    /**
+     * Upload one screenshot straight to storage via a presigned URL and return its
+     * CDN URL. Large images never pass through the PHP API this way.
+     * Returns null when server-side storage is disabled (caller falls back to base64).
+     */
+    async uploadScreenshot(data, mime) {
+        const presign = await this.request('asset-presign.php', 'Upload preparation', { body: { renditions: [{ rendition: 'source', contentType: mime, contentLength: data.length }] }, timeoutMs: 20_000, idempotent: true });
+        if (presign.success === false && presign.reason === 'storage_disabled')
+            return null;
+        const up = presign.uploads?.[0];
+        if (!up?.url || !up.publicUrl) {
+            throw new AppMockupError('UPLOAD_FAILED', 'The server did not return an upload URL.', 'Retry in a minute.');
+        }
+        // Only ever send user files to Cloudflare R2 and only expect our CDN back.
+        const target = new URL(up.url);
+        if (target.protocol !== 'https:' || !target.hostname.endsWith('.r2.cloudflarestorage.com')) {
+            throw new AppMockupError('UPLOAD_FAILED', 'Refused to upload to an unexpected storage host.', 'Contact support@appmockupgenerator.com.');
+        }
+        this.assertCdnUrl(up.publicUrl);
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                const res = await fetch(up.url, {
+                    method: 'PUT',
+                    headers: { ...(up.headers ?? {}), 'Content-Type': mime, 'Content-Length': String(data.length) },
+                    body: new Uint8Array(data),
+                    signal: AbortSignal.timeout(120_000),
+                    redirect: 'error',
+                });
+                if (res.ok)
+                    return up.publicUrl;
+                if (res.status === 403) {
+                    throw new AppMockupError('UPLOAD_FAILED', 'The upload URL expired or was rejected.', 'Retry; a new upload URL is created each time.');
+                }
+            }
+            catch (err) {
+                if (err instanceof AppMockupError || attempt === 3) {
+                    throw err instanceof AppMockupError ? err : new AppMockupError('UPLOAD_FAILED', 'Uploading the screenshot failed.', 'Check your connection and retry.');
+                }
+            }
+            await sleep(1000 * attempt);
+        }
+        throw new AppMockupError('UPLOAD_FAILED', 'Uploading the screenshot failed.', 'Check your connection and retry.');
+    }
+    async analyze(images, language) {
+        const res = await this.request('generate-mockup.php', 'Screenshot analysis', {
+            body: { mode: 'analyze', base64Images: images, language },
+            timeoutMs: 240_000,
+            idempotent: true,
+        });
+        if (!res.sessionId)
+            throw new AppMockupError('SERVER_ERROR', 'Analysis returned no session.', 'Retry.');
+        return { sessionId: res.sessionId, count: res.screenshotCount ?? images.length };
+    }
+    async getTitles(sessionId) {
+        const res = await this.request('generate-mockup.php', 'Loading titles', {
+            body: { mode: 'get-titles', sessionId }, timeoutMs: 20_000, idempotent: true,
+        });
+        return (res.items ?? []).map((it, i) => ({
+            index: Number(it.index ?? i), position: Number(it.position ?? i),
+            title: String(it.title ?? ''), subtitle: String(it.subtitle ?? ''),
+        }));
+    }
+    async updateTitles(sessionId, items) {
+        const res = await this.request('generate-mockup.php', 'Saving titles', {
+            body: { mode: 'update-titles', sessionId, items }, timeoutMs: 20_000, idempotent: true,
+        });
+        return Number(res.updated ?? 0);
+    }
+    /** Spends 1 credit (refunded server-side if generation fails). Never auto-retried after sending. */
+    async generate(args) {
+        const res = await this.request('generate-mockup.php', 'Screenshot generation', {
+            body: {
+                mode: 'generate',
+                supportsAssetUrls: true,
+                screenshotBase64: args.image,
+                sessionId: args.sessionId,
+                screenshotIndex: args.index,
+                platform: args.platform,
+                style: args.style,
+                customInstructions: args.customInstructions ?? '',
+                twistEnabled: args.twist,
+                twistType: args.twist ? 'ai-decides' : 'none',
+                originalFileName: args.fileName,
+            },
+            timeoutMs: 330_000,
+            idempotent: false,
+        });
+        const url = res.mockup?.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.`);
+        }
+        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),
+            creditsRemaining: typeof res.creditsRemaining === 'number' ? res.creditsRemaining : null,
+        };
+    }
+    /** Download a finished asset. Only our own CDN, bounded size, verified bytes. */
+    async download(url) {
+        this.assertCdnUrl(url);
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                const res = await fetch(url, { signal: AbortSignal.timeout(120_000), redirect: 'error' });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const len = Number(res.headers.get('content-length') ?? 0);
+                if (len > 60 * 1024 * 1024)
+                    throw new AppMockupError('DOWNLOAD_FAILED', 'Generated file is unexpectedly large.', 'Download it from History instead.');
+                const buf = Buffer.from(await res.arrayBuffer());
+                if (!imageInfo(buf))
+                    throw new AppMockupError('DOWNLOAD_FAILED', 'Downloaded file is not a valid image.', `Download it from ${HISTORY_URL}.`);
+                return buf;
+            }
+            catch (err) {
+                if (err instanceof AppMockupError)
+                    throw err;
+                if (attempt === 3) {
+                    throw new AppMockupError('DOWNLOAD_FAILED', 'Could not download the generated screenshot.', `It was created successfully; download it from ${HISTORY_URL}.`, { url });
+                }
+                await sleep(1500 * attempt);
+            }
+        }
+        throw new AppMockupError('DOWNLOAD_FAILED', 'Could not download the generated screenshot.', `Download it from ${HISTORY_URL}.`);
+    }
+    assertCdnUrl(raw) {
+        let u;
+        try {
+            u = new URL(raw);
+        }
+        catch {
+            throw new AppMockupError('SERVER_ERROR', 'Server returned an invalid asset URL.', 'Retry.');
+        }
+        if (u.protocol !== 'https:' || !this.config.allowedCdnHosts.includes(u.hostname)) {
+            throw new AppMockupError('SERVER_ERROR', 'Server returned an asset on an unexpected host; refusing to use it.', 'Contact support@appmockupgenerator.com.');
+        }
+    }
+}

package/dist/config.js

@@ -0,0 +1,49 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AppMockupError, API_KEYS_URL } from './errors.js';
+export const VERSION = '1.0.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';
+/** amk_test_ keys belong to the staging project, so they default to the staging API. */
+function defaultBaseUrl(apiKey) {
+    return apiKey?.startsWith('amk_test_') ? STAGING_API : PRODUCTION_API;
+}
+function parseBaseUrl(raw, apiKey) {
+    const value = (raw ?? '').trim() || defaultBaseUrl(apiKey);
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AppMockupError('CONFIG_INVALID', `APPMOCKUP_API_URL is not a valid URL.`, 'Remove APPMOCKUP_API_URL from your MCP config.');
+    }
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(local && url.protocol === 'http:')) {
+        throw new AppMockupError('CONFIG_INVALID', 'APPMOCKUP_API_URL must use https.', 'Remove APPMOCKUP_API_URL from your MCP config.');
+    }
+    return url.toString().replace(/\/+$/, '');
+}
+export function loadConfig(env = process.env) {
+    const apiKey = (env.APPMOCKUP_API_KEY ?? '').trim() || null;
+    const outputDir = (env.APPMOCKUP_OUTPUT_DIR ?? '').trim();
+    return {
+        apiKey,
+        apiBaseUrl: parseBaseUrl(env.APPMOCKUP_API_URL, apiKey),
+        outputDir: outputDir ? path.resolve(outputDir.replace(/^~(?=$|[\\/])/, os.homedir())) : null,
+        allowedCdnHosts: ['cdn.appmockupgenerator.com', 'cdn-staging.appmockupgenerator.com'],
+    };
+}
+/**
+ * The server still starts without a key so the client can list tools and
+ * explain setup; every tool that needs the API calls this first.
+ */
+export function requireApiKey(config) {
+    if (!config.apiKey) {
+        throw new AppMockupError('CONFIG_MISSING_API_KEY', 'No AppMockup API key is configured.', `Create a key at ${API_KEYS_URL}, add it as APPMOCKUP_API_KEY in this MCP server's "env" config, then restart your AI client.`);
+    }
+    if (!KEY_RE.test(config.apiKey)) {
+        throw new AppMockupError('CONFIG_INVALID_API_KEY', 'APPMOCKUP_API_KEY does not look like an AppMockup key (expected amk_live_ followed by 40 characters).', `Copy the full key again from ${API_KEYS_URL}. Check for missing characters or extra quotes/spaces.`);
+    }
+    return config.apiKey;
+}

package/dist/errors.js

@@ -0,0 +1,46 @@
+/**
+ * Every failure the user can hit is an AppMockupError with:
+ *  - a stable machine code (for the model to branch on),
+ *  - a plain-English message (what happened),
+ *  - a hint (what to do next).
+ * Tool handlers convert it into an MCP `isError` result; nothing else leaks
+ * (no stack traces, no API keys, no raw server bodies).
+ */
+export class AppMockupError extends Error {
+    code;
+    hint;
+    details;
+    constructor(code, message, hint, details) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.details = details;
+        this.name = 'AppMockupError';
+    }
+    toText() {
+        const lines = [`Error [${this.code}]: ${this.message}`];
+        if (this.hint)
+            lines.push(`How to fix: ${this.hint}`);
+        if (this.details && Object.keys(this.details).length) {
+            lines.push(`Details: ${JSON.stringify(this.details)}`);
+        }
+        return lines.join('\n');
+    }
+}
+export const PRICING_URL = 'https://appmockupgenerator.com/pricing';
+export const API_KEYS_URL = 'https://appmockupgenerator.com/studio/api-keys';
+export const HISTORY_URL = 'https://appmockupgenerator.com/studio/history';
+/** Normalise anything thrown into an AppMockupError without leaking internals. */
+export function toAppMockupError(err) {
+    if (err instanceof AppMockupError)
+        return err;
+    const e = err;
+    if (e?.name === 'AbortError' || e?.name === 'TimeoutError') {
+        return new AppMockupError('TIMEOUT', 'The request timed out.', 'Check your connection and try again.');
+    }
+    const net = ['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNRESET', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT'];
+    if (e?.code && net.includes(e.code)) {
+        return new AppMockupError('NETWORK_ERROR', 'Could not reach AppMockup.', 'Check your internet connection, VPN or proxy, then retry.');
+    }
+    return new AppMockupError('SERVER_ERROR', 'Unexpected error.', 'Retry. If it keeps happening, contact support@appmockupgenerator.com.');
+}