applaunchflow 0.3.1

package/build/tools/templates.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import { buildTemplateGalleryUrl, TEMPLATE_PREVIEW_DEVICE_TYPES, decorateTemplatePayload, } from "../template-previews.js";
+import { fail } from "./utils.js";
+function formatTemplateLine(template, deviceType) {
+    const parts = [
+        `${template.name} (${template.id})`,
+        typeof template.screenCount === "number"
+            ? `${template.screenCount} screens`
+            : null,
+        template.categories?.length
+            ? `categories: ${template.categories.join(", ")}`
+            : null,
+        template.description || null,
+        `Preview URL (${deviceType}): ${template.previewUrls[deviceType]}`,
+    ];
+    return parts.filter(Boolean).join(" | ");
+}
+function buildListTemplatesResult(payload, deviceType, galleryUrl) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `Fetched ${payload.templates.length} screenshot templates.`,
+                    `Open the visual gallery: ${galleryUrl}`,
+                    `Use the ${deviceType} preview resources below to compare them visually.`,
+                    "Keep the full catalog available unless the user explicitly asks for a shortlist.",
+                    "",
+                    ...payload.templates.map((template) => formatTemplateLine(template, deviceType)),
+                ].join("\n"),
+            },
+            {
+                type: "resource_link",
+                uri: galleryUrl,
+                name: "Open Template Gallery",
+                mimeType: "text/html",
+                description: "Hosted visual gallery with screenshot template previews for all available templates.",
+            },
+            ...payload.templates.map((template) => ({
+                type: "resource_link",
+                uri: template.previewResourceUris[deviceType],
+                name: `${template.name} (${deviceType} preview)`,
+                mimeType: "image/png",
+                description: template.description ||
+                    `Visual preview for the ${template.name} screenshot template.`,
+            })),
+        ],
+        structuredContent: {
+            success: true,
+            data: {
+                ...payload,
+                previewDeviceType: deviceType,
+                galleryUrl,
+            },
+            message: "Fetched templates",
+        },
+    };
+}
+function buildTemplateDetailsResult(payload) {
+    const { template } = payload;
+    const previewSummary = TEMPLATE_PREVIEW_DEVICE_TYPES.map((deviceType) => `${deviceType}: ${template.previewUrls[deviceType]} | resource: ${template.previewResourceUris[deviceType]}`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `Fetched template ${template.name} (${template.id}).`,
+                    template.description || null,
+                    typeof template.screenCount === "number"
+                        ? `Screen count: ${template.screenCount}`
+                        : null,
+                    template.categories?.length
+                        ? `Categories: ${template.categories.join(", ")}`
+                        : null,
+                    "",
+                    "Preview assets:",
+                    ...previewSummary,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            },
+            ...TEMPLATE_PREVIEW_DEVICE_TYPES.map((deviceType) => ({
+                type: "resource_link",
+                uri: template.previewResourceUris[deviceType],
+                name: `${template.name} (${deviceType} preview)`,
+                mimeType: "image/png",
+                description: template.description ||
+                    `Visual preview for the ${template.name} screenshot template.`,
+            })),
+        ],
+        structuredContent: {
+            success: true,
+            data: payload,
+            message: "Fetched template",
+        },
+    };
+}
+export function registerTemplateTools(server, client) {
+    server.registerTool("browse_templates", {
+        title: "Browse & Select Template",
+        description: "Use this visual style gallery after prepare_screenshot_styles, restricted to its returned templateIds, so the user can choose which prepared result to apply. It can also be used independently for static style discovery. Returns the selected template id. Never offer templates via text or AskUserQuestion — always open this gallery.",
+        inputSchema: {
+            deviceType: z
+                .enum(TEMPLATE_PREVIEW_DEVICE_TYPES)
+                .optional()
+                .describe("Which preview device the gallery should show first."),
+            templateIds: z
+                .array(z.string())
+                .optional()
+                .describe("Optional subset of template ids to show in the gallery."),
+            selectedTemplateId: z
+                .string()
+                .optional()
+                .describe("Optional template id to highlight in the gallery."),
+            title: z
+                .string()
+                .optional()
+                .describe("Optional gallery heading, for example the project name."),
+            generationId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Project UUID from prepare_screenshot_styles. Pass together with catalogKey to show the real personalized previews."),
+            catalogKey: z
+                .string()
+                .min(1)
+                .max(128)
+                .optional()
+                .describe("Catalog key from prepare_screenshot_styles. Pass together with generationId."),
+        },
+    }, async ({ deviceType = "phone", templateIds, selectedTemplateId, title, generationId, catalogKey, }) => {
+        try {
+            const payload = decorateTemplatePayload(await client.listTemplates(), client.credentials.baseUrl);
+            const availableIds = new Set(payload.templates.map((template) => template.id));
+            const filteredTemplateIds = templateIds?.filter((templateId) => availableIds.has(templateId)) || [];
+            const droppedTemplateIds = templateIds?.filter((templateId) => !availableIds.has(templateId)) ||
+                [];
+            if (droppedTemplateIds.length > 0) {
+                console.error(`[browse_templates] Ignoring unknown template ids not in the registry: ${droppedTemplateIds.join(", ")}`);
+            }
+            // If a caller restricted the gallery to specific ids but NONE of them
+            // are known, silently showing every template would misrepresent the
+            // prepared catalog. Fail loudly instead so the flow can re-prepare.
+            if (templateIds &&
+                templateIds.length > 0 &&
+                filteredTemplateIds.length === 0) {
+                return fail(new Error(`None of the requested template ids match the available templates (${droppedTemplateIds.join(", ")}). ` +
+                    "The prepared catalog and the template registry may be out of sync — re-run prepare_screenshot_styles and pass its returned templateIds."));
+            }
+            const galleryUrl = buildTemplateGalleryUrl(client.credentials.baseUrl, {
+                deviceType,
+                templateIds: filteredTemplateIds.length > 0 ? filteredTemplateIds : undefined,
+                selectedTemplateId: selectedTemplateId && availableIds.has(selectedTemplateId)
+                    ? selectedTemplateId
+                    : undefined,
+                title,
+                generationId,
+                catalogKey,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Paste this exact gallery URL into the user-visible reply.",
+                            `Template gallery URL: ${galleryUrl}`,
+                            "Do not say 'link above' because tool results may be collapsed or hidden.",
+                            "After you pick a template, reply with the template name or id.",
+                        ].join("\n"),
+                    },
+                    {
+                        type: "resource_link",
+                        uri: galleryUrl,
+                        name: "Open Template Gallery",
+                        mimeType: "text/html",
+                        description: "Hosted visual gallery for browsing screenshot template previews.",
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        galleryUrl,
+                        userFacingUrl: galleryUrl,
+                        deviceType,
+                        templateIds: filteredTemplateIds,
+                    },
+                    message: "Prepared template gallery",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/utils.js

@@ -0,0 +1,212 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { AppLaunchFlowApiError } from "../client/api.js";
+/**
+ * Bypass the SDK's `elicitation.url` capability gate by calling the underlying
+ * protocol `request()` method directly.  This lets us send URL-mode elicitations
+ * to clients (like Claude Code) that support them at the protocol level even when
+ * the SDK's newer capability check doesn't recognise the advertised capabilities.
+ *
+ * Falls back gracefully: callers should catch errors and offer the URL in text.
+ */
+export async function elicitUrl(server, params, options) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const proto = server.server;
+    return proto.request({ method: "elicitation/create", params }, ElicitResultSchema, options);
+}
+/**
+ * Ask the host to open a URL. Hosted connectors return false when the client
+ * does not support URL elicitation so the tool can still return the URL.
+ */
+export async function openUrl(server, url, message, options) {
+    try {
+        const result = await elicitUrl(server, {
+            mode: "url",
+            elicitationId: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+            message,
+            url,
+        }, options);
+        return result.action === "accept";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Emit periodic progress notifications while a long-running operation (e.g. the
+ * one-shot AI catalog generation behind prepare_*) is awaited. Clients that
+ * reset their request timeout on progress stay connected instead of timing out
+ * during the dead air. Returns a stop function to call in a `finally`.
+ */
+export function startProgressHeartbeat(extra, message, intervalMs = 8000) {
+    const progressToken = extra?._meta?.progressToken;
+    const sendNotification = extra?.sendNotification;
+    if (progressToken === undefined || typeof sendNotification !== "function") {
+        return () => { };
+    }
+    let progress = 0;
+    const send = () => {
+        progress += 1;
+        void sendNotification({
+            method: "notifications/progress",
+            params: { progressToken, progress, message },
+        }).catch(() => {
+            // Best-effort keepalive; a failed notification must not break the tool.
+        });
+    };
+    send();
+    const interval = setInterval(send, intervalMs);
+    if (typeof interval.unref === "function") {
+        interval.unref();
+    }
+    return () => clearInterval(interval);
+}
+/**
+ * In-memory get-before-edit gate keyed by generationId + variantId. The timestamp
+ * is retained for a future TTL sweep; current callers only check presence.
+ */
+export function createReadReceiptStore() {
+    const receipts = new Map();
+    const keyFor = (args) => [args.generationId, args.variantId || "active"].join("::");
+    return {
+        record(args) {
+            receipts.set(keyFor(args), Date.now());
+        },
+        has(args) {
+            return receipts.has(keyFor(args));
+        },
+        consume(args) {
+            receipts.delete(keyFor(args));
+        },
+    };
+}
+const READ_RECEIPT_TTL_MS = 10 * 60 * 1000;
+/**
+ * Hosted MCP requests are intentionally stateless, so the local in-memory
+ * get-before-edit gate cannot span two tool calls. These signed, short-lived
+ * receipts prove that the same access token fetched the exact target shortly
+ * before attempting an edit, without storing bearer tokens or server state.
+ */
+export function createHostedReadReceipt(target, bearerToken, now = Date.now()) {
+    const payload = Buffer.from(JSON.stringify({ target, issuedAt: now })).toString("base64url");
+    const signature = createHmac("sha256", bearerToken)
+        .update(payload)
+        .digest("base64url");
+    return `${payload}.${signature}`;
+}
+export function verifyHostedReadReceipt(receipt, target, bearerToken, now = Date.now()) {
+    if (!receipt)
+        return false;
+    const [payload, signature, extra] = receipt.split(".");
+    if (!payload || !signature || extra)
+        return false;
+    const expected = createHmac("sha256", bearerToken)
+        .update(payload)
+        .digest("base64url");
+    const providedBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expected);
+    if (providedBuffer.length !== expectedBuffer.length ||
+        !timingSafeEqual(providedBuffer, expectedBuffer)) {
+        return false;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return (decoded.target === target &&
+            typeof decoded.issuedAt === "number" &&
+            decoded.issuedAt <= now &&
+            now - decoded.issuedAt <= READ_RECEIPT_TTL_MS);
+    }
+    catch {
+        return false;
+    }
+}
+export function hostedMcpEnabled() {
+    return process.env.APPLAUNCHFLOW_MCP_REMOTE === "1";
+}
+export function ok(data, message) {
+    const text = typeof data === "string"
+        ? message
+            ? `${message}\n\n${data}`
+            : data
+        : message
+            ? `${message}\n\n${JSON.stringify(data, null, 2)}`
+            : JSON.stringify(data, null, 2);
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        structuredContent: {
+            success: true,
+            data,
+            ...(message ? { message } : {}),
+        },
+    };
+}
+function extractValidationIssues(error) {
+    if (!(error instanceof AppLaunchFlowApiError))
+        return null;
+    const body = error.body;
+    const details = body?.details ?? body?.error?.details;
+    if (!Array.isArray(details))
+        return null;
+    return details.filter((issue) => typeof issue === "object" && issue !== null);
+}
+function formatValidationIssue(issue) {
+    const path = Array.isArray(issue.path)
+        ? issue.path.join(".")
+        : (issue.path ?? "");
+    const where = path ? `\`${path}\`` : "(root)";
+    const bounds = [
+        issue.expected !== undefined ? `expected ${JSON.stringify(issue.expected)}` : null,
+        issue.received !== undefined ? `received ${JSON.stringify(issue.received)}` : null,
+        issue.maximum !== undefined ? `max ${JSON.stringify(issue.maximum)}` : null,
+        issue.minimum !== undefined ? `min ${JSON.stringify(issue.minimum)}` : null,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const parts = [where, issue.message ?? issue.code ?? "invalid"];
+    if (bounds)
+        parts.push(`(${bounds})`);
+    return `• ${parts.join(" — ")}`;
+}
+export function fail(error) {
+    const issues = extractValidationIssues(error);
+    const normalized = error instanceof AppLaunchFlowApiError
+        ? {
+            code: error.body?.error?.code ||
+                error.body?.code ||
+                `HTTP_${error.status}`,
+            type: error.body?.error?.type || "server",
+            message: error.body?.error?.message || error.message,
+            status: error.status,
+            details: error.body,
+            ...(issues ? { issues } : {}),
+        }
+        : {
+            code: "UNKNOWN",
+            type: "server",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    // For validation errors, append a compact issue summary to the visible
+    // text so the calling LLM can see exactly which field tripped Zod and
+    // self-correct on the next call instead of guessing.
+    const text = issues?.length
+        ? [normalized.message, "Issues:", ...issues.map(formatValidationIssue)].join("\n")
+        : normalized.message;
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        structuredContent: {
+            success: false,
+            error: normalized,
+        },
+    };
+}

package/build/tools/variants.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { openUrl, fail, ok } from "./utils.js";
+const contentTypeEnum = z.enum(["screenshots", "socialGraphics", "promoVideo"]);
+export function registerVariantTools(server, client) {
+    server.registerTool("list_variants", {
+        title: "List Variants",
+        description: "List variants for a generation and content type",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            contentType: contentTypeEnum,
+        },
+    }, async ({ generationId, contentType }) => {
+        try {
+            return ok(await client.listVariants(generationId, contentType), "Fetched variants");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("create_variant", {
+        title: "Create Variant",
+        description: "Create a new content variant. This is the preferred starting point when the user wants a new screenshot direction, a different template, or a fresh AI-generated take without overwriting the current variant.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            contentType: contentTypeEnum,
+            label: z.string().optional(),
+            setActive: z.boolean().optional(),
+        },
+    }, async (args, extra) => {
+        try {
+            const result = await client.createVariant(args);
+            const variantId = result?.variant?.id;
+            const generationId = args.generationId;
+            if (variantId && generationId) {
+                const editorPath = args.contentType === "socialGraphics"
+                    ? "/graphics"
+                    : args.contentType === "promoVideo"
+                        ? "/promovideo"
+                        : "/editor";
+                const params = new URLSearchParams({
+                    projectId: generationId,
+                    variantId,
+                });
+                if (args.contentType === "screenshots") {
+                    params.set("device", "phone");
+                }
+                const editorUrl = `${client.credentials.baseUrl}${editorPath}?${params.toString()}`;
+                await openUrl(server, editorUrl, "Opening the new variant in the editor.", { signal: extra.signal });
+                return ok({ ...result, editorUrl }, "Created variant");
+            }
+            return ok(result, "Created variant");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("duplicate_variant", {
+        title: "Duplicate Variant",
+        description: "Duplicate an existing variant",
+        inputSchema: {
+            variantId: z.string().uuid(),
+        },
+    }, async ({ variantId }) => {
+        try {
+            return ok(await client.duplicateVariant(variantId), "Duplicated variant");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "applaunchflow",
+  "version": "0.3.1",
+  "description": "Hosted OAuth MCP connector for AppLaunchFlow.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ynnickw/applaunchflow-mcp.git"
+  },
+  "type": "module",
+  "bin": {
+    "applaunchflow": "build/cli.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('build', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && chmod 755 build/cli.js",
+    "dev:http": "tsx src/http.ts",
+    "start:http": "node build/http.js",
+    "test": "npm run build && node --test build/*.test.js scripts/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3"
+  }
+}