@applaunchflow/mcp 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# applaunchflow MCP
+
+Local stdio MCP server for applaunchflow.
+
+## Auth
+
+```bash
+pnpm --dir applaunchflow-mcp dev auth login --base-url http://localhost:3000
+```
+
+Credentials are stored in `~/.applaunchflow/credentials.json`.
+
+Environment overrides:
+
+- `applaunchflow_BASE_URL`
+- `applaunchflow_MCP_TOKEN`
+- `applaunchflow_MCP_COOKIE_NAME`
+
+## Run
+
+```bash
+pnpm --dir applaunchflow-mcp build
+node applaunchflow-mcp/build/index.js
+```
+
+The server uses stdio transport and exposes tools/resources for project, screenshot, layout, template, variant, graphics, and ASO workflows.

package/build/auth/credentials.js

@@ -0,0 +1,53 @@
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+const CONFIG_DIR = path.join(os.homedir(), ".applaunchflow");
+const CREDENTIALS_PATH = path.join(CONFIG_DIR, "credentials.json");
+function defaultCookieName(baseUrl) {
+    return baseUrl.startsWith("https://")
+        ? "__Secure-authjs.session-token"
+        : "authjs.session-token";
+}
+export function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+export function getCredentialsPath() {
+    return CREDENTIALS_PATH;
+}
+export async function loadStoredCredentials() {
+    try {
+        const raw = await fs.readFile(CREDENTIALS_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            ...parsed,
+            baseUrl: normalizeBaseUrl(parsed.baseUrl),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveStoredCredentials(credentials) {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    await fs.writeFile(CREDENTIALS_PATH, `${JSON.stringify(credentials, null, 2)}\n`, "utf8");
+}
+export async function clearStoredCredentials() {
+    await fs.rm(CREDENTIALS_PATH, { force: true });
+}
+export async function resolveCredentials() {
+    const baseUrl = normalizeBaseUrl(process.env.APPLAUNCHFLOW_BASE_URL || "https://dashboard.applaunchflow.com");
+    const envToken = process.env.APPLAUNCHFLOW_MCP_TOKEN;
+    if (envToken) {
+        return {
+            baseUrl,
+            token: envToken,
+            cookieName: process.env.APPLAUNCHFLOW_MCP_COOKIE_NAME || defaultCookieName(baseUrl),
+            createdAt: new Date().toISOString(),
+        };
+    }
+    const stored = await loadStoredCredentials();
+    if (!stored) {
+        throw new Error(`No AppLaunchFlow MCP credentials found. Run \`applaunchflow-mcp auth login --base-url ${baseUrl}\`.`);
+    }
+    return stored;
+}

package/build/auth/login.js

@@ -0,0 +1,92 @@
+import { createServer } from "http";
+import { spawn } from "child_process";
+import { normalizeBaseUrl, saveStoredCredentials, } from "./credentials.js";
+function openBrowser(url) {
+    const platform = process.platform;
+    const command = platform === "darwin"
+        ? "open"
+        : platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch (error) {
+        console.error(`Failed to open the browser automatically. Open this URL manually: ${url}`);
+        if (error instanceof Error) {
+            console.error(error.message);
+        }
+    }
+}
+async function createCallbackListener() {
+    const callbackPath = "/callback";
+    let resolveAddress = null;
+    const addressPromise = new Promise((resolve) => {
+        resolveAddress = resolve;
+    });
+    const responsePromise = new Promise((resolve, reject) => {
+        const server = createServer((request, response) => {
+            const requestUrl = new URL(request.url || "/", "http://127.0.0.1:0");
+            if (requestUrl.pathname !== callbackPath) {
+                response.statusCode = 404;
+                response.end("Not found");
+                return;
+            }
+            const token = requestUrl.searchParams.get("token");
+            const cookieName = requestUrl.searchParams.get("cookieName");
+            const baseUrl = requestUrl.searchParams.get("baseUrl");
+            const expiresAt = requestUrl.searchParams.get("expiresAt") || undefined;
+            if (!token || !cookieName || !baseUrl) {
+                response.statusCode = 400;
+                response.end("Missing token payload");
+                return;
+            }
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            response.end("<!doctype html><html><body><h1>AppLaunchFlow MCP connected</h1><p>You can close this tab now.</p></body></html>");
+            clearTimeout(timeout);
+            server.close();
+            resolve({
+                baseUrl: normalizeBaseUrl(baseUrl),
+                token,
+                cookieName,
+                expiresAt,
+            });
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            resolveAddress?.(address);
+        });
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Timed out waiting for browser authentication"));
+        }, 5 * 60 * 1000);
+    });
+    const address = await addressPromise;
+    return {
+        callbackUrl: `http://127.0.0.1:${address.port}${callbackPath}`,
+        responsePromise,
+    };
+}
+export async function login(baseUrl) {
+    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+    const { callbackUrl, responsePromise } = await createCallbackListener();
+    const authorizeUrl = new URL("/auth/mcp", normalizedBaseUrl);
+    authorizeUrl.searchParams.set("callback", callbackUrl);
+    authorizeUrl.searchParams.set("name", "Local MCP");
+    console.error(`Opening AppLaunchFlow authorization in your browser...`);
+    console.error(`If nothing opens, visit: ${authorizeUrl.toString()}`);
+    openBrowser(authorizeUrl.toString());
+    const received = await responsePromise;
+    const credentials = {
+        ...received,
+        createdAt: new Date().toISOString(),
+    };
+    await saveStoredCredentials(credentials);
+    console.error(`Login successful! Connected to ${credentials.baseUrl}`);
+    return credentials;
+}

package/build/client/api.js

@@ -0,0 +1,248 @@
+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("Cookie", `${this.credentials.cookieName}=${this.credentials.token}`);
+        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 });
+    }
+    generateLayouts(body) {
+        return this.requestJson("/api/screenshots/generate", {
+            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}`);
+    }
+    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 },
+        });
+    }
+    generateGraphics(body) {
+        return this.requestJson("/api/graphics/generate", {
+            method: "POST",
+            body,
+        });
+    }
+    saveGraphics(body) {
+        return this.requestJson("/api/graphics", {
+            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 },
+        });
+    }
+    /** 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 },
+        });
+    }
+}

package/build/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { clearStoredCredentials, getCredentialsPath, loadStoredCredentials, resolveCredentials, } from "./auth/credentials.js";
+import { login } from "./auth/login.js";
+import { AppLaunchFlowClient } from "./client/api.js";
+import { registerPrompts } from "./prompts/register.js";
+import { registerResources } from "./resources/register.js";
+import { TemplateSelectionCoordinator } from "./template-selection.js";
+import { registerAssetTools } from "./tools/assets.js";
+import { registerLayoutTools } from "./tools/layouts.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerScreenshotTools } from "./tools/screenshots.js";
+import { registerTemplateTools } from "./tools/templates.js";
+import { registerLocalizationTools } from "./tools/localization.js";
+import { registerVariantTools } from "./tools/variants.js";
+const SERVER_INSTRUCTIONS = `
+AppLaunchFlow MCP is screenshot-focused at this stage.
+Only use it for screenshot project setup, screenshot uploads, screenshot template generation, variants, and direct screenshot layout editing.
+Do not treat this MCP as an ASO, localization, graphics, or promo-video assistant.
+
+Use AppLaunchFlow MCP as an execution tool, not a questionnaire.
+
+Default behavior:
+- For concrete requests on an existing project, act directly instead of asking follow-up questions.
+- Only ask when a missing detail is required to avoid a materially wrong result, or when the request is genuinely ambiguous.
+- Do not force menu-style "what would you like to do next?" steps after each tool call.
+- The user can edit layouts in natural language. Translate those requests into direct MCP actions.
+- If a tool returns a user-facing URL, repeat the exact URL in the assistant reply. Do not say "link above" or assume tool output is visible to the user.
+
+Preferred workflows:
+- New screenshot direction or template on an existing project: call generate_layouts WITHOUT a variantId — a new variant is always created automatically. Never overwrite existing variants.
+- For small, precise edits to existing known nodes, transform_layout can be used directly.
+- For any composition-sensitive edit, inspect the current layout first with get_layout. This includes adding screens, reusing screenshots, changing screenshot placement, moving text, changing spacing, or anything that should match the existing visual system.
+- Use transform_layout as the primary tool for editing current screens once you have enough layout context.
+- Default to layouts: ["mobile"] for transform_layout. Only include tablet/desktop if the user explicitly asks.
+- When editing a single screen, scope the transform to just that screen using the screens parameter (e.g. screens: [2]). Do not transform the entire layout when only one screen needs changes.
+- For adding new screens to an existing layout, prefer direct layout editing when the user wants to keep the current design. Only generate a fresh variant when the user asks for a new AI-generated layout/template.
+- When adding or editing elements, ensure text and screenshots do not overlap. Verify that positions place elements in distinct, non-conflicting areas of the canvas.
+- After composition-sensitive edits, inspect the returned translation or re-fetch the layout before reporting success. If elements overlap or are poorly positioned, fix them before telling the user the edit is done.
+- ALWAYS use browse_templates when a template choice is needed. Never offer templates via text bullet points or AskUserQuestion. The gallery opens in the browser and returns the user's selection automatically.
+- Use actual visual previews from the template tools/resources. Do not rely on adjective-heavy descriptions alone.
+- Keep the full template catalog available when the user is browsing templates. Only narrow to a small shortlist if the user explicitly asks for recommendations or fewer options.
+
+Translation and localization:
+- When the user asks to translate, localize, or create a version in another language, ALWAYS use translate_layouts. Do NOT manually edit text nodes via transform_layout for translation.
+- translate_layouts uses AI to translate all text while preserving layout, positioning, and styling.
+- To apply the same transform across all screens, use transform_layout with screens: "all" in the target.
+
+Project creation should be fast and simple:
+1. Ask for the app name and platform (iOS or Android) using AskUserQuestion. Default platform to iOS.
+2. Autofill category and description from context (e.g. "Skyscanner" → category "Travel"). Do not ask the user for these.
+3. Call create_project immediately. Do not ask for confirmation or optional fields unless the user volunteers them.
+4. After creation, recommend uploading screenshots as the next step.
+`.trim();
+async function runAuthCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "login") {
+        const baseUrlFlagIndex = rest.findIndex((value) => value === "--base-url");
+        const baseUrl = baseUrlFlagIndex >= 0
+            ? rest[baseUrlFlagIndex + 1]
+            : process.env.APPLAUNCHFLOW_BASE_URL || "https://dashboard.applaunchflow.com";
+        await login(baseUrl);
+        return;
+    }
+    if (subcommand === "logout") {
+        await clearStoredCredentials();
+        console.error(`Removed credentials at ${getCredentialsPath()}`);
+        return;
+    }
+    if (subcommand === "status") {
+        const credentials = await loadStoredCredentials();
+        if (!credentials) {
+            console.error("No stored AppLaunchFlow MCP credentials");
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`Base URL: ${credentials.baseUrl}`);
+        console.error(`Cookie name: ${credentials.cookieName}`);
+        if (credentials.expiresAt) {
+            console.error(`Expires at: ${credentials.expiresAt}`);
+        }
+        console.error(`Credentials file: ${getCredentialsPath()}`);
+        return;
+    }
+    console.error("Usage: applaunchflow-mcp auth <login|logout|status> [--base-url <url>]");
+    process.exitCode = 1;
+}
+async function startServer() {
+    const credentials = await resolveCredentials();
+    const client = new AppLaunchFlowClient(credentials);
+    const templateSelectionCoordinator = new TemplateSelectionCoordinator();
+    const server = new McpServer({
+        name: "applaunchflow-mcp",
+        version: "0.1.0",
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    registerPrompts(server);
+    registerResources(server, client);
+    registerProjectTools(server, client);
+    registerAssetTools(server, client);
+    registerScreenshotTools(server, client);
+    registerLayoutTools(server, client);
+    registerTemplateTools(server, client, templateSelectionCoordinator);
+    registerLocalizationTools(server, client);
+    registerVariantTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function main() {
+    const [, , command, ...args] = process.argv;
+    if (command === "auth") {
+        await runAuthCommand(args);
+        return;
+    }
+    try {
+        await startServer();
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.stack || error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+void main();

package/build/prompts/register.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.registerPrompt("create-project-wizard", {
+        title: "Create Project Wizard",
+        description: "Guide the user through quick project creation: ask app name + platform, then create immediately.",
+        argsSchema: {
+            userGoal: z
+                .string()
+                .optional()
+                .describe("Optional user request or project idea to keep in view."),
+        },
+    }, async ({ userGoal }) => ({
+        description: "Use this prompt when the user wants to create a project through AppLaunchFlow MCP.",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Create an AppLaunchFlow project quickly.",
+                        "Ask for the app name and platform (iOS or Android) using AskUserQuestion.",
+                        "Autofill category and description from context — do not ask the user for these.",
+                        "Call create_project immediately after getting the name and platform.",
+                        "After creation, recommend uploading screenshots as the next step.",
+                        userGoal ? `User goal: ${userGoal}` : null,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("direct-editing-workflow", {
+        title: "Direct Editing Workflow",
+        description: "Guide layout editing on an existing screenshot variant without inventing a new visual system.",
+        argsSchema: {
+            userGoal: z
+                .string()
+                .optional()
+                .describe("Optional concrete editing request."),
+        },
+    }, async ({ userGoal }) => ({
+        description: "Use this prompt when the user wants to edit an existing layout or add screens while preserving the current design language.",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Operate directly on the existing AppLaunchFlow screenshot layout.",
+                        "For small text-only edits to known nodes, transform_layout can be used directly.",
+                        "For any composition-sensitive edit, call get_layout first and inspect the relevant existing screens before building transform operations.",
+                        "Composition-sensitive edits include adding screens, reusing screenshots, changing screenshot placement, moving text, changing spacing, or any request that should match the current style.",
+                        "When preserving the current design, copy actual numeric values from nearby screens: text positions, widths, zIndex, screenshot position, scale, rotation, and typography attributes.",
+                        "Do not invent a fresh composition unless the user explicitly asks for a redesign.",
+                        "After applying composition-sensitive transforms, inspect the returned translation or fetch the layout again and verify that the new screens match the existing style and do not overlap key content.",
+                        userGoal ? `User goal: ${userGoal}` : null,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            },
+        ],
+    }));
+}