@applaunchflow/mcp 0.1.0

package/build/tools/layouts.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+const transformOperationSchema = z.object({
+    type: z.enum([
+        "update_node",
+        "delete_node",
+        "add_node",
+        "reorder",
+        "replace_color",
+    ]).describe("Operation type. replace_color is a find-and-replace for colors across the layout — use it for bulk color changes instead of updating each text node individually. " +
+        "Example: {type:'replace_color', target:{nodeType:'screen'}, changes:{find:'#F6EFE9', replace:'#7C3AED'}} replaces that color everywhere (text marks, icon colors, backgrounds). " +
+        "Use screens:'all' to replace across all screens, or screens:[6] for a single screen."),
+    target: z.object({
+        nodeType: z
+            .string()
+            .describe("REQUIRED. The node type to target: 'screen', 'text', 'screenshot', 'illustration', 'pill', 'badge', 'blob', 'rating', 'logo', 'emoji', 'header', 'panoramaBackground', 'backgroundImage'."),
+        nodeId: z
+            .string()
+            .optional()
+            .describe("Optional. Target a specific node by id. If omitted, the operation applies to ALL nodes of nodeType in the target screens."),
+        selector: z
+            .string()
+            .optional()
+            .describe("Optional. Target screens by id: 'screenId:<id>'. Do NOT use '#' prefix."),
+        screens: z
+            .union([z.literal("all"), z.array(z.number())])
+            .optional()
+            .describe("Optional. Target specific screens by index array (e.g. [0, 1, 2]) or 'all' for every screen. If omitted, targets all screens."),
+    }),
+    changes: z.record(z.any()),
+}).superRefine((operation, ctx) => {
+    // Require nodeType for all operations except replace_color
+    if (!operation.target.nodeType && operation.type !== "replace_color") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["target", "nodeType"],
+            message: "nodeType is required in target",
+        });
+        return;
+    }
+    const payload = operation.changes?.node &&
+        typeof operation.changes.node === "object" &&
+        !Array.isArray(operation.changes.node)
+        ? operation.changes.node
+        : operation.changes;
+    if (operation.type === "add_node") {
+        if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes"],
+                message: "add_node requires a node object in changes or changes.node",
+            });
+            return;
+        }
+        if (typeof payload.id !== "string" || payload.id.trim().length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes", "id"],
+                message: "add_node requires a non-empty id field",
+            });
+        }
+        if (operation.target.nodeType === "screen" &&
+            ("text" in payload || "screenshotPath" in payload)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes"],
+                message: "When adding a screen, only provide the screen container fields. Add screenshot and text nodes with separate add_node operations targeting that screen index.",
+            });
+        }
+    }
+});
+export function registerLayoutTools(server, client) {
+    server.registerTool("get_layout", {
+        title: "Get Layout",
+        description: "Get layout JSON for the current translation before editing or reviewing a variant.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string().optional(),
+            variantId: z.string().uuid().optional(),
+            sign: z.boolean().optional(),
+        },
+    }, async ({ generationId, language, variantId, sign }) => {
+        try {
+            return ok(await client.getLayout({ generationId, language, variantId, sign }), "Fetched layout data");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("save_layout", {
+        title: "Save Layout",
+        description: "Persist a full translation layout payload",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string(),
+            variantId: z.string().uuid().optional(),
+            mobileLayout: z.record(z.any()),
+            tabletLayout: z.record(z.any()),
+            desktopLayout: z.record(z.any()).nullable().optional(),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.saveLayout(args), "Saved layout");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("transform_layout", {
+        title: "Transform Layout",
+        description: "Apply transform operations to an existing layout. Primary editing tool for text, screenshots, colors, and structure changes. " +
+            "RULES: " +
+            "1. nodeType is REQUIRED in every operation target. The backend rejects operations without it. " +
+            "2. Omit nodeId to update ALL nodes of that type in the target screens. This is the efficient way to do bulk changes (e.g. change all illustration colors: {nodeType:'illustration', screens:'all'} with changes {primaryColor:'#xxx'}). " +
+            "3. Use screens:'all' to target every screen at once. Do NOT send one operation per screen when the same change applies to all. " +
+            "4. For add_node, changes MUST include an 'id' field. " +
+            "5. To add new screens, first add empty screen containers, then populate them in a SECOND call using selector 'screenId:<id>'. " +
+            "6. Default to layouts:['mobile']. Only include tablet/desktop if the user asks.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string(),
+            variantId: z.string().uuid().optional(),
+            atomic: z.boolean().optional(),
+            layouts: z
+                .array(z.enum(["mobile", "tablet", "desktop"]))
+                .optional()
+                .describe("Which layout sizes to transform. Default to ['mobile'] unless the user explicitly asks for tablet or desktop."),
+            operations: z.array(transformOperationSchema).min(1),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.transformLayout(args), "Applied layout transform");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/localization.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+const SUPPORTED_LANGUAGE_CODES = [
+    "en", "es", "fr", "de", "it", "pt", "pt-BR", "ja", "ko",
+    "zh-CN", "zh-TW", "nl", "ru", "ar", "tr", "pl", "sv",
+    "no", "da", "fi", "cs", "hi", "hu", "ro", "uk",
+];
+export function registerLocalizationTools(server, client) {
+    server.registerTool("translate_layouts", {
+        title: "Translate Layouts",
+        description: "Translate screenshot layouts into one or more target languages using AI. " +
+            "This is the PREFERRED way to localize screenshots — do NOT manually edit text nodes for translation. " +
+            "The backend translates all text in the layout while preserving positioning, styling, and screenshots. " +
+            "Requires a source layout to already exist (generate_layouts must have been called first).",
+        inputSchema: {
+            generationId: z.string().uuid().describe("The project/generation UUID."),
+            variantId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Variant to translate. If omitted, uses the active variant."),
+            targetLanguages: z
+                .array(z.enum(SUPPORTED_LANGUAGE_CODES))
+                .min(1)
+                .describe("Array of target language codes (e.g. ['en', 'ja', 'de']). The source language is auto-detected and excluded."),
+            layouts: z
+                .array(z.enum(["mobile", "tablet", "desktop"]))
+                .optional()
+                .describe("Which layout sizes to translate. Defaults to ['mobile', 'tablet']. Include 'desktop' only if the project has a desktop layout."),
+        },
+    }, async (args) => {
+        try {
+            const body = {
+                ...args,
+                layouts: args.layouts || ["mobile", "tablet"],
+            };
+            return ok(await client.translateLayouts(body), "Translated layouts");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_translations", {
+        title: "List Translations",
+        description: "List available translations for a project variant. Returns which languages have been translated.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+        },
+    }, async ({ generationId, variantId }) => {
+        try {
+            return ok(await client.getLayout({ generationId, variantId }), "Fetched translations");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/projects.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function registerProjectTools(server, client) {
+    server.registerTool("list_projects", {
+        title: "List Projects",
+        description: "List AppLaunchFlow projects for the authenticated user",
+    }, async () => {
+        try {
+            return ok(await client.listProjects(), "Fetched projects");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("get_project", {
+        title: "Get Project",
+        description: "Get the full hub state for a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            return ok(await client.getProject(projectId), "Fetched project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("create_project", {
+        title: "Create Project",
+        description: "Create a new AppLaunchFlow project. Only app name and platform are required. " +
+            "Autofill category and description from context when possible — do not ask the user for these unless genuinely ambiguous.",
+        inputSchema: {
+            appName: z
+                .string()
+                .trim()
+                .min(1)
+                .max(120)
+                .describe("The app name."),
+            platform: z
+                .enum(["ios", "android", "both"])
+                .optional()
+                .describe("Target platform. Defaults to iOS."),
+            category: z
+                .string()
+                .trim()
+                .max(120)
+                .optional()
+                .describe("App category. Infer from the app name/context when possible (e.g. 'Travel' for a flight app)."),
+            appDescription: z
+                .string()
+                .trim()
+                .max(4000)
+                .optional()
+                .describe("Brief app description. Infer from context when possible."),
+            defaultDeviceType: z
+                .enum(["phone", "tablet", "desktop", "watch"])
+                .optional()
+                .describe("Defaults to phone. Only set if the user explicitly asks."),
+            logoPath: z
+                .string()
+                .optional()
+                .describe("Optional stored logo path from upload_screenshots when fileType=logo."),
+            metadata: z
+                .record(z.any())
+                .optional()
+                .describe("Advanced escape hatch for extra metadata fields."),
+        },
+    }, async (args) => {
+        try {
+            const platform = args.platform || "ios";
+            const metadata = stripUndefined({
+                ...(args.metadata || {}),
+                appName: args.appName,
+                platform,
+                category: args.category,
+                appDescription: args.appDescription,
+                defaultDeviceType: args.defaultDeviceType || "phone",
+                logoPath: args.logoPath,
+            });
+            const requestBody = stripUndefined({
+                name: args.appName,
+                platform,
+                metadata,
+            });
+            const created = await client.createProject(requestBody);
+            return ok({
+                project: created.project,
+                nextRecommendedStep: "upload_screenshots",
+            }, "Created project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("delete_project", {
+        title: "Delete Project",
+        description: "Delete a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            return ok(await client.deleteProject(projectId), "Deleted project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/screenshots.js

@@ -0,0 +1,107 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+export function registerScreenshotTools(server, client) {
+    server.registerTool("generate_layouts", {
+        title: "Generate Layouts",
+        description: "Generate screenshot layouts for a project. " +
+            "For existing projects, pass generationId (same as projectId) — the API fetches screenshots from storage automatically. " +
+            "Do NOT pass screenshots when using generationId. " +
+            "Only pass metadata + screenshots (without generationId) for the ephemeral upload flow. " +
+            "Do NOT pass variantId — omit it so a new variant is always created. Never overwrite an existing variant. " +
+            "Do not use this tool for small edits to an existing layout; use transform_layout instead.",
+        inputSchema: {
+            generationId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("The project/generation UUID. When provided, the API loads screenshots from storage and saves results to DB. This is the primary way to call this tool for existing projects."),
+            projectId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Only needed for the upload flow (without generationId) to sign screenshot paths."),
+            metadata: z
+                .record(z.any())
+                .optional()
+                .describe("App metadata. Required only when generationId is NOT provided (upload flow)."),
+            screenshots: z
+                .array(z.object({
+                path: z.string().optional(),
+                url: z.string().optional(),
+                filename: z.string().optional(),
+            }))
+                .optional()
+                .describe("Screenshot list. Required only when generationId is NOT provided. Do NOT send when using generationId."),
+            templateId: z.string().optional(),
+            deviceType: z.enum(["phone", "tablet", "desktop"]).optional(),
+            variantId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("DO NOT pass this. Always omit so a new variant is created. Never overwrite existing variants."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.generateLayouts(args), "Generated layouts");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_screenshots", {
+        title: "List Screenshots",
+        description: "List uploaded screenshot paths for a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+            deviceType: z.enum(["mobile", "tablet", "desktop"]).optional(),
+            platform: z.enum(["ios", "android"]).optional(),
+        },
+    }, async ({ projectId, deviceType, platform }) => {
+        try {
+            return ok(await client.listScreenshots({ projectId, deviceType, platform }), "Listed screenshots");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("view_screenshot", {
+        title: "View Screenshot",
+        description: "Fetch a screenshot image and return it for visual analysis. " +
+            "Use this to inspect screenshots — extract colors, read UI text, understand layout context, or identify visual elements. " +
+            "Pass projectId and the relative path from list_screenshots or get_layout (e.g. 'mobile/ios/1234-image.PNG').",
+        inputSchema: {
+            projectId: z.string().uuid().describe("The project UUID."),
+            path: z
+                .string()
+                .describe("Relative screenshot path (e.g. 'mobile/ios/1234-IMG.PNG') from list_screenshots or the layout's screenshot.path field."),
+        },
+    }, async ({ projectId, path }) => {
+        try {
+            const fullPath = `${projectId}/${path}`;
+            const previewUrl = `${client.credentials.baseUrl}/api/preview?path=${encodeURIComponent(fullPath)}&w=320`;
+            const headers = new Headers();
+            headers.set("Cookie", `${client.credentials.cookieName}=${client.credentials.token}`);
+            headers.set("Authorization", `Bearer ${client.credentials.token}`);
+            const response = await fetch(previewUrl, { headers });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch image: ${response.status}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const mimeType = response.headers.get("content-type") || "image/png";
+            const base64 = Buffer.from(arrayBuffer).toString("base64");
+            return {
+                content: [
+                    {
+                        type: "image",
+                        data: base64,
+                        mimeType,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/store-metadata.js

@@ -0,0 +1,66 @@
+export function extractAppStoreId(input) {
+    if (/^\d+$/.test(input)) {
+        return input;
+    }
+    const match = input.match(/id(\d+)/);
+    return match ? match[1] : null;
+}
+export async function fetchGooglePlayMetadata(urlString) {
+    const url = new URL(urlString);
+    const packageName = url.searchParams.get("id");
+    if (!packageName) {
+        throw new Error("Google Play URL must include an id query parameter");
+    }
+    const response = await fetch(url.toString(), {
+        headers: {
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+            "Accept-Language": "en-US,en;q=0.9",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Google Play request failed with status ${response.status}`);
+    }
+    const html = await response.text();
+    const scriptMatch = html.match(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/);
+    if (!scriptMatch) {
+        throw new Error("Unable to parse Google Play metadata");
+    }
+    const payload = JSON.parse(scriptMatch[1]);
+    return {
+        provider: "google_play",
+        packageName,
+        appName: payload.name || null,
+        description: payload.description || null,
+        category: payload.applicationCategory || null,
+        iconUrl: payload.image || null,
+        rating: payload.aggregateRating?.ratingValue || null,
+        ratingCount: payload.aggregateRating?.ratingCount || null,
+        url: url.toString(),
+    };
+}
+export async function lookupStoreMetadata(client, app, country = "us") {
+    if (app.includes("play.google.com")) {
+        return fetchGooglePlayMetadata(app);
+    }
+    const appId = extractAppStoreId(app);
+    if (!appId) {
+        throw new Error("Provide an App Store URL, Google Play URL, or App Store numeric id");
+    }
+    const lookup = await client.lookupAppStore(appId, country);
+    const appResult = lookup.results?.[0];
+    if (!appResult) {
+        throw new Error("App Store app not found");
+    }
+    return {
+        provider: "apple",
+        appleAppId: appId,
+        appName: appResult.trackName || null,
+        description: appResult.description || null,
+        iconUrl: appResult.artworkUrl512 || appResult.artworkUrl100 || null,
+        category: appResult.primaryGenreName || null,
+        screenshotUrls: appResult.screenshotUrls || [],
+        averageUserRating: appResult.averageUserRating || null,
+        userRatingCount: appResult.userRatingCount || null,
+        appStoreUrl: appResult.trackViewUrl || null,
+    };
+}