applaunchflow 0.3.1

package/README.md

@@ -0,0 +1,110 @@
+# AppLaunchFlow MCP
+
+MCP server for AppLaunchFlow — create App Store & Google Play screenshots with AI.
+
+## Connect
+
+AppLaunchFlow is a hosted MCP connector with OAuth 2.1 and PKCE. No API key,
+local token, or scoped npm package name is required.
+
+### Codex
+
+The shortest setup command configures the hosted connector and opens OAuth:
+
+```bash
+npx -y applaunchflow connect codex
+```
+
+Useful follow-up commands:
+
+```bash
+npx -y applaunchflow status
+npx -y applaunchflow disconnect
+```
+
+The equivalent native Codex commands are:
+
+```bash
+codex mcp add applaunchflow --url https://mcp.applaunchflow.com/mcp
+codex mcp login applaunchflow
+codex mcp get applaunchflow
+codex mcp remove applaunchflow
+```
+
+### ChatGPT
+
+```bash
+npx -y applaunchflow connect chatgpt
+```
+
+Paste the displayed URL when creating a custom MCP connector in ChatGPT. The
+same URL is also available at any time with `npx -y applaunchflow url`.
+
+### Other MCP clients
+
+Use this Streamable HTTP endpoint and enable OAuth when prompted:
+
+```text
+https://mcp.applaunchflow.com/mcp
+```
+
+## Hosted service
+
+The public Streamable HTTP service uses OAuth 2.1 authorization code flow with
+PKCE through the AppLaunchFlow dashboard.
+
+```bash
+npm ci
+npm run build
+APPLAUNCHFLOW_BASE_URL=https://dashboard.applaunchflow.com \
+APPLAUNCHFLOW_MCP_PUBLIC_URL=https://mcp.applaunchflow.com \
+PORT=8787 \
+npm run start:http
+```
+
+Public endpoints:
+
+- MCP: `https://mcp.applaunchflow.com/mcp`
+- Protected resource metadata: `https://mcp.applaunchflow.com/.well-known/oauth-protected-resource`
+- Health: `https://mcp.applaunchflow.com/healthz`
+
+`APPLAUNCHFLOW_MCP_PUBLIC_URL` may be either the origin or the full `/mcp`
+URL; both services normalize it to the same canonical resource URL. Set
+`APPLAUNCHFLOW_MCP_PUBLIC_URL=https://mcp.applaunchflow.com/mcp` and
+`NEXT_PUBLIC_APP_URL=https://dashboard.applaunchflow.com` on the dashboard.
+
+The included `Dockerfile` produces a non-root OCI image for the hosted server.
+The MCP host and dashboard must both be served through public HTTPS in
+production. Do not expose the Node process directly without a TLS-terminating
+platform or reverse proxy.
+
+## Personalized style workflow
+
+Screenshot and social-graphics styles are prepared once for the selected app screenshots, then the chosen style is applied from cache. This lets users compare styles without paying for another AI call when they choose one.
+
+For App Store screenshots:
+
+1. `list_source_screenshots`
+2. `prepare_screenshot_styles` with 3-7 ordered paths
+3. `browse_templates` with the returned `templateIds`, `generationId`, and `catalogKey`
+4. `apply_screenshot_style` with the returned `catalogKey`
+
+For social graphics:
+
+1. `list_source_screenshots`
+2. `prepare_social_graphics_styles` with 3-7 ordered paths
+3. `browse_social_templates` with the returned `templateIds`, `generationId`, and `catalogKey`
+4. `apply_social_graphics_style` with the returned `catalogKey`
+
+The screenshot result includes phone, tablet, and desktop. The social result includes all six supported formats. `generate_layouts` and `generate_graphics` remain available for legacy direct single-template calls.
+
+## Development
+
+```bash
+npm ci
+npm run dev
+```
+
+Run `npm test` before publishing or deploying. See
+[`docs/openai-submission.md`](docs/openai-submission.md) for the final OpenAI
+submission checklist and manual test cases.

package/build/catalog.js

@@ -0,0 +1,5 @@
+export function listPublicTemplateIds(templatePayloads) {
+    return Object.keys(templatePayloads ?? {})
+        .filter((templateId) => !templateId.startsWith("__"))
+        .sort();
+}

package/build/catalog.test.js

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { listPublicTemplateIds } from "./catalog.js";
+test("listPublicTemplateIds returns sorted public templates", () => {
+    assert.deepEqual(listPublicTemplateIds({
+        beauty: {},
+        __layoutVersion: "v1",
+        action: {},
+    }), ["action", "beauty"]);
+});
+test("listPublicTemplateIds handles an absent catalog", () => {
+    assert.deepEqual(listPublicTemplateIds(undefined), []);
+});

package/build/cli-core.js

@@ -0,0 +1,20 @@
+export const APPLAUNCHFLOW_MCP_NAME = "applaunchflow";
+export const APPLAUNCHFLOW_MCP_URL = "https://mcp.applaunchflow.com/mcp";
+export function codexAddArgs() {
+    return [
+        "mcp",
+        "add",
+        APPLAUNCHFLOW_MCP_NAME,
+        "--url",
+        APPLAUNCHFLOW_MCP_URL,
+    ];
+}
+export function codexLoginArgs() {
+    return ["mcp", "login", APPLAUNCHFLOW_MCP_NAME];
+}
+export function codexStatusArgs() {
+    return ["mcp", "get", APPLAUNCHFLOW_MCP_NAME];
+}
+export function codexDisconnectArgs() {
+    return ["mcp", "remove", APPLAUNCHFLOW_MCP_NAME];
+}

package/build/cli-core.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { APPLAUNCHFLOW_MCP_NAME, APPLAUNCHFLOW_MCP_URL, codexAddArgs, codexDisconnectArgs, codexLoginArgs, codexStatusArgs, } from "./cli-core.js";
+test("Codex convenience commands use the hosted OAuth connector", () => {
+    assert.deepEqual(codexAddArgs(), [
+        "mcp",
+        "add",
+        APPLAUNCHFLOW_MCP_NAME,
+        "--url",
+        APPLAUNCHFLOW_MCP_URL,
+    ]);
+    assert.deepEqual(codexLoginArgs(), ["mcp", "login", "applaunchflow"]);
+    assert.deepEqual(codexStatusArgs(), ["mcp", "get", "applaunchflow"]);
+    assert.deepEqual(codexDisconnectArgs(), [
+        "mcp",
+        "remove",
+        "applaunchflow",
+    ]);
+});
+test("the public connector URL is a secure MCP endpoint", () => {
+    const url = new URL(APPLAUNCHFLOW_MCP_URL);
+    assert.equal(url.protocol, "https:");
+    assert.equal(url.pathname, "/mcp");
+});

package/build/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { APPLAUNCHFLOW_MCP_URL, codexAddArgs, codexDisconnectArgs, codexLoginArgs, codexStatusArgs, } from "./cli-core.js";
+function printHelp() {
+    console.log(`AppLaunchFlow MCP
+
+Usage:
+  applaunchflow connect codex
+  applaunchflow connect chatgpt
+  applaunchflow status
+  applaunchflow disconnect
+  applaunchflow url`);
+}
+function runCodex(args) {
+    const result = spawnSync("codex", args, { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`Could not run Codex: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`Codex exited with status ${result.status ?? "unknown"}`);
+    }
+}
+function codexIsConfigured() {
+    const result = spawnSync("codex", codexStatusArgs(), { stdio: "ignore" });
+    if (result.error) {
+        throw new Error(`Could not run Codex: ${result.error.message}`);
+    }
+    return result.status === 0;
+}
+function connectCodex() {
+    if (!codexIsConfigured()) {
+        runCodex(codexAddArgs());
+    }
+    runCodex(codexLoginArgs());
+}
+function connectChatGpt() {
+    console.log(`Add a custom MCP connector in ChatGPT using this URL:\n${APPLAUNCHFLOW_MCP_URL}`);
+}
+function main() {
+    const [command, target] = process.argv.slice(2);
+    if (command === "connect" && target === "codex") {
+        connectCodex();
+        return;
+    }
+    if (command === "connect" && target === "chatgpt") {
+        connectChatGpt();
+        return;
+    }
+    if (command === "status") {
+        runCodex(codexStatusArgs());
+        return;
+    }
+    if (command === "disconnect") {
+        runCodex(codexDisconnectArgs());
+        return;
+    }
+    if (command === "url") {
+        console.log(APPLAUNCHFLOW_MCP_URL);
+        return;
+    }
+    printHelp();
+    if (command)
+        process.exitCode = 1;
+}
+try {
+    main();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/build/client/api.js

@@ -0,0 +1,341 @@
+export class AppLaunchFlowApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "AppLaunchFlowApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+function buildSearchParams(query) {
+    if (!query) {
+        return "";
+    }
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((item) => params.append(key, String(item)));
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    const serialized = params.toString();
+    return serialized ? `?${serialized}` : "";
+}
+export class AppLaunchFlowClient {
+    credentials;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    buildHeaders(extraHeaders) {
+        const headers = new Headers(extraHeaders);
+        headers.set("Authorization", `Bearer ${this.credentials.token}`);
+        return headers;
+    }
+    async requestJson(path, options = {}) {
+        const url = `${this.credentials.baseUrl}${path}${buildSearchParams(options.query)}`;
+        const headers = this.buildHeaders(options.headers);
+        if (options.body !== undefined && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+        const response = await fetch(url, {
+            method: options.method || "GET",
+            headers,
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        const contentType = response.headers.get("content-type") || "";
+        const payload = contentType.includes("application/json")
+            ? await response.json()
+            : await response.text();
+        if (!response.ok) {
+            const message = typeof payload === "string"
+                ? payload
+                : payload?.error ||
+                    payload?.message ||
+                    `Request failed with status ${response.status}`;
+            throw new AppLaunchFlowApiError(message, response.status, payload);
+        }
+        return payload;
+    }
+    async createSignedUpload(args) {
+        return this.requestJson("/api/assets/upload/signed-url", {
+            method: "POST",
+            body: args,
+        });
+    }
+    async uploadBinary(uploadUrl, buffer, contentType) {
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": contentType,
+            },
+            body: new Uint8Array(buffer),
+        });
+        if (!response.ok) {
+            throw new Error(`Upload failed with status ${response.status}`);
+        }
+    }
+    listProjects() {
+        return this.requestJson("/api/projects");
+    }
+    createProject(body) {
+        return this.requestJson("/api/projects", {
+            method: "POST",
+            body,
+        });
+    }
+    deleteProject(projectId) {
+        return this.requestJson(`/api/projects/${projectId}`, {
+            method: "DELETE",
+        });
+    }
+    getProject(projectId) {
+        return this.requestJson(`/api/app/${projectId}`);
+    }
+    listScreenshots(query) {
+        return this.requestJson("/api/screenshots/list", { query });
+    }
+    listProjectScreenshots(projectId) {
+        return this.requestJson(`/api/projects/${projectId}/screenshots`);
+    }
+    generateLayouts(body) {
+        return this.requestJson("/api/screenshots/generate", {
+            method: "POST",
+            body,
+        });
+    }
+    applyScreenshotTemplate(body) {
+        return this.requestJson("/api/screenshots/apply-template", {
+            method: "POST",
+            body,
+        });
+    }
+    regenerateLayouts(body) {
+        return this.requestJson("/api/screenshots/regenerate", {
+            method: "POST",
+            body,
+        });
+    }
+    getLayout(query) {
+        return this.requestJson("/api/translations", {
+            query: {
+                generationId: query.generationId,
+                language: query.language,
+                variantId: query.variantId,
+                sign: query.sign ? 1 : undefined,
+            },
+        });
+    }
+    saveLayout(body) {
+        return this.requestJson("/api/translations", {
+            method: "POST",
+            body,
+        });
+    }
+    transformLayout(body) {
+        return this.requestJson("/api/mcp/transform", {
+            method: "POST",
+            body,
+        });
+    }
+    listTemplates() {
+        return this.requestJson("/api/mcp/templates");
+    }
+    getTemplate(templateId) {
+        return this.requestJson(`/api/mcp/templates/${templateId}`);
+    }
+    listSocialTemplates() {
+        return this.requestJson("/api/mcp/social-templates");
+    }
+    getSocialTemplate(templateId) {
+        return this.requestJson(`/api/mcp/social-templates/${templateId}`);
+    }
+    getPromoVideo(generationId, variantId) {
+        return this.requestJson("/api/promovideo/load", {
+            query: { generationId, variantId },
+        });
+    }
+    generatePromoVideo(body) {
+        return this.requestJson("/api/promovideo/generate", {
+            method: "POST",
+            body,
+        });
+    }
+    updatePromoVideo(body) {
+        return this.requestJson("/api/promovideo/update", {
+            method: "POST",
+            body,
+        });
+    }
+    clearPromoVideo(body) {
+        return this.requestJson("/api/promovideo/clear", {
+            method: "POST",
+            body,
+        });
+    }
+    createMockupAnimation(body) {
+        return this.requestJson("/api/mockups/setup", {
+            method: "POST",
+            body,
+        });
+    }
+    getMockupAnimation(generationId, variantId) {
+        return this.requestJson("/api/mockups", {
+            query: { generationId, variantId },
+        });
+    }
+    updateMockupAnimation(body) {
+        return this.requestJson("/api/mockups", {
+            method: "POST",
+            body,
+        });
+    }
+    listMockupMedia(projectId) {
+        return this.requestJson("/api/mockup-media/list", {
+            query: { projectId },
+        });
+    }
+    getMockupThemeColors(generationId) {
+        return this.requestJson("/api/mockups/theme-colors", {
+            query: { generationId },
+        });
+    }
+    lookupAppStore(id, country = "us") {
+        return this.requestJson("/api/itunes/lookup", {
+            query: { id, country },
+            headers: {},
+        });
+    }
+    translateLayouts(body) {
+        return this.requestJson("/api/screenshots/translate", {
+            method: "POST",
+            body,
+        });
+    }
+    listVariants(generationId, contentType) {
+        return this.requestJson("/api/variants", {
+            query: { generationId, contentType },
+        });
+    }
+    createVariant(body) {
+        return this.requestJson("/api/variants", {
+            method: "POST",
+            body,
+        });
+    }
+    switchVariant(variantId) {
+        return this.requestJson(`/api/variants/${variantId}`, {
+            method: "PATCH",
+            body: { isActive: true },
+        });
+    }
+    duplicateVariant(variantId) {
+        return this.requestJson(`/api/variants/${variantId}/duplicate`, {
+            method: "POST",
+        });
+    }
+    deleteVariant(variantId) {
+        return this.requestJson(`/api/variants/${variantId}`, {
+            method: "DELETE",
+        });
+    }
+    getGraphics(projectId, variantId) {
+        return this.requestJson("/api/graphics", {
+            query: { projectId, variantId },
+        });
+    }
+    getGraphicsFormat(projectId, format, variantId) {
+        return this.requestJson("/api/graphics", {
+            query: { projectId, variantId, format },
+        });
+    }
+    generateGraphics(body) {
+        return this.requestJson("/api/graphics/generate", {
+            method: "POST",
+            body,
+        });
+    }
+    applyGraphicsTemplate(body) {
+        return this.requestJson("/api/graphics/apply-template", {
+            method: "POST",
+            body,
+        });
+    }
+    saveGraphics(body) {
+        return this.requestJson("/api/graphics", {
+            method: "POST",
+            body,
+        });
+    }
+    saveGraphicsFormat(body) {
+        return this.requestJson("/api/graphics/format", {
+            method: "POST",
+            body,
+        });
+    }
+    getAsoCopy(generationId, variantId) {
+        return this.requestJson("/api/aso/copy", {
+            query: { generationId, variantId },
+        });
+    }
+    generateAsoCopy(body) {
+        return this.requestJson("/api/aso/copy", {
+            method: "POST",
+            body,
+        });
+    }
+    updateAsoCopy(body) {
+        return this.requestJson("/api/aso/copy", {
+            method: "PUT",
+            body,
+        });
+    }
+    translateAsoCopy(body) {
+        return this.requestJson("/api/aso/translate", {
+            method: "POST",
+            body,
+        });
+    }
+    suggestCompetitors(body) {
+        return this.requestJson("/api/aso/competitors/suggest", {
+            method: "POST",
+            body,
+        });
+    }
+    listSharedIllustrations(query) {
+        return this.requestJson("/api/illustrations/shared", { query });
+    }
+    listProjectIllustrations(projectId) {
+        return this.requestJson("/api/illustrations/list", {
+            query: { projectId },
+        });
+    }
+    listKeywords(query) {
+        return this.requestJson("/api/keywords", { query });
+    }
+    listKeywordCompetitors(query) {
+        return this.requestJson("/api/keywords/competitors", { query });
+    }
+    getKeywordHistory(query) {
+        return this.requestJson("/api/keywords/history", { query });
+    }
+    addKeywords(body) {
+        return this.requestJson("/api/keywords", { method: "POST", body });
+    }
+    /** List files in a project's asset subfolder (panorama, illustrations, backgrounds, etc.) */
+    async listProjectAssetFolder(projectId, folder) {
+        // Use the app endpoint for known folders, or fall back to storage listing
+        if (folder === "illustrations") {
+            return this.listProjectIllustrations(projectId);
+        }
+        // For panorama/backgrounds/logo — use the screenshots list with a folder hint
+        // These are stored under {projectId}/{folder}/ in the screenshots bucket
+        return this.requestJson(`/api/app/${projectId}/assets`, {
+            query: { folder },
+        });
+    }
+}