applaunchflow 0.3.1

package/build/resources/register.js

@@ -0,0 +1,115 @@
+import { Buffer } from "node:buffer";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildTemplatePreviewUrl, decorateTemplatePayload, isSafeTemplateId, isTemplatePreviewDeviceType, } from "../template-previews.js";
+import { LAYOUT_SCHEMA_RESOURCE, PROJECT_CREATION_WIZARD_RESOURCE, SUPPORTED_DEVICES, TRANSFORM_SCHEMA_RESOURCE, VIDEO_CONFIG_SCHEMA_RESOURCE, WORKFLOW_GUIDE_RESOURCE, } from "./data.js";
+function asJsonResource(uri, payload) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+function asBinaryResource(uri, mimeType, blob) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType,
+                blob,
+            },
+        ],
+    };
+}
+export function registerResources(server, client) {
+    server.registerResource("layout-schema", "applaunchflow://schema/layout", {
+        title: "Layout Schema",
+        description: "Full field-level reference for the layout JSON used by BOTH screenshots and social graphics: every node type, its properties and valid value ranges. Read before hand-writing or editing layout JSON.",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, LAYOUT_SCHEMA_RESOURCE));
+    server.registerResource("video-config-schema", "applaunchflow://schema/video-config", {
+        title: "Promo Video Config Schema",
+        description: "Full field-level reference for the Remotion VideoConfig: scene types and their content shapes, theme, text styles, ken burns, choreography preset ids, audio. Read before editing a promo video config.",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, VIDEO_CONFIG_SCHEMA_RESOURCE));
+    server.registerResource("transform-schema", "applaunchflow://schema/transforms", {
+        title: "Transform Schema",
+        description: "Supported transform_layout operations, the selector syntax (including the pitfalls that silently match every screen), and the valid node types. Read before calling transform_layout.",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, TRANSFORM_SCHEMA_RESOURCE));
+    server.registerResource("template-catalog", "applaunchflow://templates", {
+        title: "Template Catalog",
+        description: "Current screenshot template catalog",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, decorateTemplatePayload(await client.listTemplates(), client.credentials.baseUrl)));
+    server.registerResource("template-preview", new ResourceTemplate("applaunchflow://templates/{templateId}/preview/{deviceType}", {
+        list: undefined,
+    }), {
+        title: "Template Preview",
+        description: "Rendered preview image for a screenshot template and device type.",
+        mimeType: "image/png",
+    }, async (uri, { templateId, deviceType }) => {
+        const resolvedTemplateId = Array.isArray(templateId)
+            ? templateId[0]
+            : templateId;
+        const resolvedDeviceType = Array.isArray(deviceType)
+            ? deviceType[0]
+            : deviceType;
+        if (!isSafeTemplateId(resolvedTemplateId) ||
+            !isTemplatePreviewDeviceType(resolvedDeviceType)) {
+            throw new Error("Invalid template preview request");
+        }
+        const headers = new Headers();
+        headers.set("Authorization", `Bearer ${client.credentials.token}`);
+        const previewUrl = buildTemplatePreviewUrl(client.credentials.baseUrl, resolvedTemplateId, resolvedDeviceType);
+        const response = await fetch(previewUrl, {
+            headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch template preview ${resolvedTemplateId}/${resolvedDeviceType}: HTTP ${response.status}`);
+        }
+        const mimeType = response.headers.get("content-type") || "image/png";
+        const arrayBuffer = await response.arrayBuffer();
+        const blob = Buffer.from(arrayBuffer).toString("base64");
+        return asBinaryResource(uri.href, mimeType, blob);
+    });
+    server.registerResource("project-creation-wizard", "applaunchflow://wizard/project-creation", {
+        title: "Project Creation Wizard",
+        description: "The exact guided flow used by the UI create-project wizard",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, PROJECT_CREATION_WIZARD_RESOURCE));
+    server.registerResource("workflow-guide", "applaunchflow://guide/workflows", {
+        title: "Workflow Guide",
+        description: "Preferred MCP workflows for generating and editing projects",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, WORKFLOW_GUIDE_RESOURCE));
+    server.registerResource("devices", "applaunchflow://devices", {
+        title: "Supported Devices",
+        description: "Device frame identifiers and dimensions",
+        mimeType: "application/json",
+    }, async (uri) => asJsonResource(uri.href, SUPPORTED_DEVICES));
+    server.registerResource("project-state", new ResourceTemplate("applaunchflow://project/{projectId}/state", {
+        list: undefined,
+    }), {
+        title: "Project State",
+        description: "Project state summary with variants and translations",
+        mimeType: "application/json",
+    }, async (uri, { projectId }) => {
+        const resolvedProjectId = Array.isArray(projectId) ? projectId[0] : projectId;
+        const [project, translations, screenshotVariants] = await Promise.all([
+            client.getProject(resolvedProjectId),
+            client.getLayout({ generationId: resolvedProjectId }),
+            client.listVariants(resolvedProjectId, "screenshots"),
+        ]);
+        return asJsonResource(uri.href, {
+            project,
+            translations,
+            variants: {
+                screenshots: screenshotVariants,
+            },
+        });
+    });
+}

package/build/social-template-previews.js

@@ -0,0 +1,84 @@
+export const SOCIAL_FORMATS = [
+    "og",
+    "x_post",
+    "instagram_story",
+    "play_store_feature",
+    "x_header",
+    "linkedin_banner",
+];
+export function isSocialFormat(value) {
+    return SOCIAL_FORMATS.includes(value);
+}
+export function buildSocialTemplatePreviewPath(templateId, format) {
+    return `/template-examples/social/${format}/${templateId}.png`;
+}
+export function buildSocialTemplatePreviewUrl(baseUrl, templateId, format) {
+    return new URL(buildSocialTemplatePreviewPath(templateId, format), baseUrl).toString();
+}
+export function buildSocialTemplatePreviewResourceUri(templateId, format) {
+    return `applaunchflow://social-templates/${encodeURIComponent(templateId)}/preview/${format}`;
+}
+export function buildSocialTemplateGalleryUrl(baseUrl, options) {
+    const url = new URL("/template-gallery", baseUrl);
+    url.searchParams.set("kind", "social");
+    if (options?.format) {
+        url.searchParams.set("format", options.format);
+    }
+    if (options?.templateIds?.length) {
+        url.searchParams.set("ids", options.templateIds.join(","));
+    }
+    if (options?.selectedTemplateId) {
+        url.searchParams.set("selected", options.selectedTemplateId);
+    }
+    if (options?.title) {
+        url.searchParams.set("title", options.title);
+    }
+    if (options?.returnTo) {
+        url.searchParams.set("returnTo", options.returnTo);
+    }
+    if (options?.generationId && options?.catalogKey) {
+        url.searchParams.set("generationId", options.generationId);
+        url.searchParams.set("catalogKey", options.catalogKey);
+    }
+    return url.toString();
+}
+function decorateSocialTemplate(template, baseUrl) {
+    const previewUrls = Object.fromEntries(SOCIAL_FORMATS.map((format) => [
+        format,
+        template.previewUrls?.[format] ||
+            buildSocialTemplatePreviewUrl(baseUrl, template.id, format),
+    ]));
+    const previewResourceUris = Object.fromEntries(SOCIAL_FORMATS.map((format) => [
+        format,
+        buildSocialTemplatePreviewResourceUri(template.id, format),
+    ]));
+    return {
+        ...template,
+        previewUrls,
+        previewResourceUris,
+    };
+}
+export function decorateSocialTemplatePayload(payload, baseUrl) {
+    if (payload &&
+        typeof payload === "object" &&
+        "templates" in payload &&
+        Array.isArray(payload.templates)) {
+        const typedPayload = payload;
+        return {
+            ...typedPayload,
+            templates: typedPayload.templates.map((template) => decorateSocialTemplate(template, baseUrl)),
+        };
+    }
+    if (payload &&
+        typeof payload === "object" &&
+        "template" in payload &&
+        payload.template &&
+        typeof payload.template === "object") {
+        const typedPayload = payload;
+        return {
+            ...typedPayload,
+            template: decorateSocialTemplate(typedPayload.template, baseUrl),
+        };
+    }
+    return payload;
+}

package/build/template-previews.js

@@ -0,0 +1,83 @@
+export const TEMPLATE_PREVIEW_DEVICE_TYPES = [
+    "phone",
+    "tablet",
+    "desktop",
+];
+export function isTemplatePreviewDeviceType(value) {
+    return TEMPLATE_PREVIEW_DEVICE_TYPES.includes(value);
+}
+export function isSafeTemplateId(templateId) {
+    return /^[a-z0-9-]+$/i.test(templateId);
+}
+export function buildTemplatePreviewPath(templateId, deviceType) {
+    return `/template-examples/${deviceType}/${templateId}.png`;
+}
+export function buildTemplatePreviewUrl(baseUrl, templateId, deviceType) {
+    return new URL(buildTemplatePreviewPath(templateId, deviceType), baseUrl).toString();
+}
+export function buildTemplatePreviewResourceUri(templateId, deviceType) {
+    return `applaunchflow://templates/${encodeURIComponent(templateId)}/preview/${deviceType}`;
+}
+export function buildTemplateGalleryUrl(baseUrl, options) {
+    const url = new URL("/template-gallery", baseUrl);
+    if (options?.deviceType) {
+        url.searchParams.set("device", options.deviceType);
+    }
+    if (options?.templateIds?.length) {
+        url.searchParams.set("ids", options.templateIds.join(","));
+    }
+    if (options?.selectedTemplateId) {
+        url.searchParams.set("selected", options.selectedTemplateId);
+    }
+    if (options?.title) {
+        url.searchParams.set("title", options.title);
+    }
+    if (options?.returnTo) {
+        url.searchParams.set("returnTo", options.returnTo);
+    }
+    if (options?.generationId && options?.catalogKey) {
+        url.searchParams.set("generationId", options.generationId);
+        url.searchParams.set("catalogKey", options.catalogKey);
+    }
+    return url.toString();
+}
+function decorateTemplate(template, baseUrl) {
+    const previewUrls = Object.fromEntries(TEMPLATE_PREVIEW_DEVICE_TYPES.map((deviceType) => [
+        deviceType,
+        template.previewUrls?.[deviceType] ||
+            buildTemplatePreviewUrl(baseUrl, template.id, deviceType),
+    ]));
+    const previewResourceUris = Object.fromEntries(TEMPLATE_PREVIEW_DEVICE_TYPES.map((deviceType) => [
+        deviceType,
+        buildTemplatePreviewResourceUri(template.id, deviceType),
+    ]));
+    return {
+        ...template,
+        previewUrls,
+        previewResourceUris,
+    };
+}
+export function decorateTemplatePayload(payload, baseUrl) {
+    if (payload &&
+        typeof payload === "object" &&
+        "templates" in payload &&
+        Array.isArray(payload.templates)) {
+        const typedPayload = payload;
+        return {
+            ...typedPayload,
+            templates: typedPayload.templates.map((template) => decorateTemplate(template, baseUrl)),
+        };
+    }
+    if (payload &&
+        typeof payload === "object" &&
+        "template" in payload &&
+        payload.template &&
+        typeof payload.template === "object") {
+        const typedPayload = payload;
+        return {
+            ...typedPayload,
+            template: decorateTemplate(typedPayload.template, baseUrl),
+        };
+    }
+    return payload;
+}

package/build/tool-metadata.js

@@ -0,0 +1,112 @@
+import { z } from "zod";
+const readOnly = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const createOrAppend = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const overwriteOrDelete = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const openWorldCreate = {
+    ...createOrAppend,
+    openWorldHint: true,
+};
+export const TOOL_ANNOTATIONS = {
+    list_projects: readOnly,
+    get_project: readOnly,
+    create_project: createOrAppend,
+    delete_project: overwriteOrDelete,
+    upload_screenshots: openWorldCreate,
+    list_illustrations: readOnly,
+    upload_asset: openWorldCreate,
+    prepare_screenshot_styles: createOrAppend,
+    apply_screenshot_style: createOrAppend,
+    generate_layouts: createOrAppend,
+    list_source_screenshots: readOnly,
+    list_screenshots: readOnly,
+    view_screenshot: readOnly,
+    get_layout: readOnly,
+    save_layout: overwriteOrDelete,
+    transform_layout: overwriteOrDelete,
+    browse_templates: readOnly,
+    prepare_social_graphics_styles: createOrAppend,
+    apply_social_graphics_style: createOrAppend,
+    browse_social_templates: readOnly,
+    generate_graphics: createOrAppend,
+    get_graphics: readOnly,
+    get_graphics_format: readOnly,
+    save_graphics: overwriteOrDelete,
+    save_graphics_format: overwriteOrDelete,
+    generate_promo_video: createOrAppend,
+    get_promo_video: readOnly,
+    update_promo_video: overwriteOrDelete,
+    clear_promo_video: overwriteOrDelete,
+    create_mockup_animation: createOrAppend,
+    get_mockup_animation: readOnly,
+    update_mockup_animation: overwriteOrDelete,
+    list_mockup_media: readOnly,
+    list_mockup_presets: readOnly,
+    translate_layouts: createOrAppend,
+    list_translations: readOnly,
+    list_variants: readOnly,
+    create_variant: createOrAppend,
+    duplicate_variant: createOrAppend,
+    list_keywords: readOnly,
+    list_keyword_competitors: readOnly,
+    add_keywords: createOrAppend,
+    get_keyword_history: readOnly,
+};
+const OAUTH_SECURITY_SCHEME = {
+    type: "oauth2",
+    scopes: [
+        "projects:read",
+        "projects:write",
+        "assets:write",
+        "generations:write",
+    ],
+};
+const GENERIC_OUTPUT_SCHEMA = {
+    success: z.boolean(),
+    data: z.unknown().optional(),
+    message: z.string().optional(),
+    error: z.unknown().optional(),
+};
+/**
+ * Apply the submission metadata contract centrally so local and hosted
+ * transports cannot silently drift. Registration throws when a new tool is
+ * added without an explicit safety classification.
+ */
+export function installToolMetadataPolicy(server, options = {}) {
+    const registerTool = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => {
+        const annotations = TOOL_ANNOTATIONS[name];
+        if (!annotations) {
+            throw new Error(`Missing tool safety annotations for ${name}`);
+        }
+        const existingMeta = (config._meta || {});
+        return registerTool(name, {
+            ...config,
+            annotations: {
+                ...(config.annotations || {}),
+                ...annotations,
+            },
+            outputSchema: config.outputSchema || GENERIC_OUTPUT_SCHEMA,
+            _meta: {
+                ...existingMeta,
+                ...(options.hosted
+                    ? { securitySchemes: [OAUTH_SECURITY_SCHEME] }
+                    : {}),
+            },
+        }, callback);
+    });
+}

package/build/tool-metadata.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createAppLaunchFlowServer } from "./index.js";
+import { TOOL_ANNOTATIONS } from "./tool-metadata.js";
+test("all registered tools expose submission safety metadata and output schemas", async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const server = createAppLaunchFlowServer({
+        baseUrl: "https://dashboard.applaunchflow.com",
+        token: "test-token",
+    });
+    const client = new Client({ name: "metadata-test", version: "1.0.0" });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    try {
+        const { tools } = await client.listTools();
+        assert.equal(tools.length, 43);
+        assert.deepEqual(tools.map((tool) => tool.name).sort(), Object.keys(TOOL_ANNOTATIONS).sort());
+        for (const tool of tools) {
+            assert.deepEqual(tool.annotations, TOOL_ANNOTATIONS[tool.name]);
+            assert.equal(tool.outputSchema?.type, "object");
+            assert.ok(tool.title, `${tool.name} must have a title`);
+            assert.ok(tool.description, `${tool.name} must have a description`);
+            assert.deepEqual(tool._meta?.securitySchemes?.map((scheme) => scheme.type), ["oauth2"]);
+        }
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+});