@okostream/mcp 0.1.1 → 0.1.2

package/README.md

@@ -106,6 +106,7 @@ Write/control tools include:
 - `oko_create_webinar`
 - `oko_update_event`
 - `oko_configure_blocks`
+- `oko_configure_cards`
 - `oko_upload_image`
 - `oko_delete_image`
 - `oko_set_block_visibility`
@@ -130,9 +131,10 @@ Dangerous or external side-effect tools require `confirm: true`.
 1. `oko_whoami` should return the organizer UID and granted scopes.
 2. `oko_list_my_events` should return only events visible to that UID.
 3. `oko_create_webinar` should create a test webinar and RTDB owner/workspace mirror.
-4. `oko_upload_image` should accept a local path or HTTPS image URL, upload `master.webp`, and let OKO generate variants.
-5. `oko_delete_image` should clear image fields and best-effort delete master/variants.
-6. `oko_get_analytics` should read an existing event with analytics sessions.
+4. `oko_configure_cards` should create/update `blocks.cards.items` and preserve card image fields by stable card id.
+5. `oko_upload_image` should accept a local path or HTTPS image URL, upload `master.webp`, and let OKO generate variants.
+6. `oko_delete_image` should clear image fields and best-effort delete master/variants.
+7. `oko_get_analytics` should read an existing event with analytics sessions.
 
 CLI help:
 

package/dist/server.js

@@ -22,7 +22,7 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.1.1",
+    version: "0.1.2",
 });
 registerTools(server);
 const transport = new StdioServerTransport();

package/dist/tools.js

@@ -17,6 +17,13 @@ import { detectAndNormalize, extractIframeSrc } from "./videoUrl.js";
 const boolOrNull = z.boolean().nullable();
 const IMAGE_KINDS = ["promoBanner", "videoPlaceholder", "card"];
 const IMAGE_VARIANT_NAMES = ["thumb_320.webp", "card_800.webp", "hero_1600.webp"];
+const CARD_IMAGE_RATIOS = ["auto", "1:1", "4:3", "3:2", "16:9", "2:3", "3:4"];
+const CARD_ID_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
+const MAX_CARD_ITEMS = 6;
+const MAX_CARD_TITLE_LENGTH = 160;
+const MAX_CARD_TEXT_LENGTH = 500;
+const MAX_CARD_BUTTON_LABEL_LENGTH = 80;
+const MAX_CARD_BUTTON_URL_LENGTH = 1000;
 const MAX_SOURCE_IMAGE_BYTES = 15 * 1024 * 1024;
 const MAX_SOURCE_IMAGE_PIXELS = 50_000_000;
 const MAX_MASTER_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -156,6 +163,32 @@ const imageSourceSchema = z.object({
 }).strict().refine((source) => Boolean(source.path) !== Boolean(source.url), {
     message: "Provide exactly one image source: path or url.",
 });
+const cardIdSchema = z.string()
+    .regex(CARD_ID_PATTERN, "Use 1-80 characters: letters, numbers, underscore, or hyphen.")
+    .describe("Stable card id. Omit to generate one; keep it to preserve images and analytics continuity.");
+const cardItemInputSchema = z.object({
+    id: cardIdSchema.optional(),
+    title: z.string().max(MAX_CARD_TITLE_LENGTH).nullable().optional(),
+    text: z.string().max(MAX_CARD_TEXT_LENGTH).nullable().optional(),
+    buttonLabel: z.string().max(MAX_CARD_BUTTON_LABEL_LENGTH).nullable().optional(),
+    buttonUrl: z.string().max(MAX_CARD_BUTTON_URL_LENGTH).nullable().optional(),
+    formId: cardIdSchema.nullable().optional(),
+}).strict();
+const cardsConfigOutputSchema = z.object({
+    eventId: z.string(),
+    updated: z.array(z.string()),
+    cards: z.object({
+        enabled: z.boolean(),
+        visibility: z.enum(["always", "hidden"]),
+        cardImageRatio: z.enum(CARD_IMAGE_RATIOS),
+        items: z.array(unknownRecordSchema),
+    }).passthrough(),
+    generatedCardIds: z.array(z.string()),
+    removedCardIds: z.array(z.string()),
+    removedCardsWithImages: z.array(z.string()),
+    preservedImageCardIds: z.array(z.string()),
+    warnings: z.array(z.string()),
+}).passthrough();
 const workspacePermissionsSchema = z.object({
     createEvents: z.boolean().optional(),
     editSetup: z.boolean().optional(),
@@ -441,6 +474,112 @@ function cardItemsWithImage(eventData, cardId, patch) {
         throw new Error(`Card ${cardId} not found in blocks.cards.items.`);
     return next;
 }
+function readImageVariants(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const data = value;
+    if (typeof data.thumbUrl !== "string" || typeof data.cardUrl !== "string" || typeof data.heroUrl !== "string") {
+        return null;
+    }
+    return {
+        thumbUrl: data.thumbUrl,
+        cardUrl: data.cardUrl,
+        heroUrl: data.heroUrl,
+    };
+}
+function readCardsConfig(eventData) {
+    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
+    const raw = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
+    const rawItems = Array.isArray(raw.items) ? raw.items : [];
+    const items = rawItems
+        .filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+        .map((item) => {
+        const fallbackId = randomUUID();
+        return {
+            id: typeof item.id === "string" && CARD_ID_PATTERN.test(item.id) ? item.id : fallbackId,
+            title: safeString(item.title).trim() || null,
+            text: safeString(item.text).trim() || null,
+            buttonLabel: safeString(item.buttonLabel).trim() || null,
+            buttonUrl: safeString(item.buttonUrl).trim() || null,
+            imageUrl: safeString(item.imageUrl).trim() || null,
+            imageMasterUrl: safeString(item.imageMasterUrl).trim() || null,
+            imageVariants: readImageVariants(item.imageVariants),
+            formId: safeString(item.formId).trim() || null,
+        };
+    });
+    const ratio = safeString(raw.cardImageRatio);
+    return {
+        enabled: raw.enabled === true,
+        visibility: raw.visibility === "hidden" ? "hidden" : "always",
+        cardImageRatio: CARD_IMAGE_RATIOS.includes(ratio) ? ratio : "16:9",
+        items,
+    };
+}
+function normalizeNullableText(value) {
+    if (value == null)
+        return null;
+    return value.trim() || null;
+}
+function normalizeCardButtonUrl(value) {
+    const trimmed = normalizeNullableText(value);
+    if (!trimmed)
+        return null;
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`Invalid card buttonUrl "${trimmed}". Use http(s), mailto, tel, or set formId instead.`);
+    }
+    if (!["http:", "https:", "mailto:", "tel:"].includes(url.protocol)) {
+        throw new Error(`Unsupported card buttonUrl protocol "${url.protocol}". Use http(s), mailto, tel, or set formId instead.`);
+    }
+    return trimmed;
+}
+function eventFormIds(eventData) {
+    const rawForms = Array.isArray(eventData.forms) ? eventData.forms : [];
+    return new Set(rawForms
+        .map((form) => form && typeof form === "object" && !Array.isArray(form) ? safeString(form.id).trim() : "")
+        .filter(Boolean));
+}
+function cardHasImage(item) {
+    return Boolean(item.imageMasterUrl || item.imageUrl || item.imageVariants);
+}
+function buildCardsItems({ inputs, existing, formIds, }) {
+    const existingById = new Map(existing.map((item) => [item.id, item]));
+    const seen = new Set();
+    const generatedCardIds = [];
+    const preservedImageCardIds = [];
+    const items = inputs.map((input) => {
+        const id = input.id ?? randomUUID();
+        if (seen.has(id))
+            throw new Error(`Duplicate card id "${id}". Each card id must be unique.`);
+        seen.add(id);
+        if (!CARD_ID_PATTERN.test(id))
+            throw new Error(`Invalid card id "${id}". Use 1-80 characters: letters, numbers, underscore, or hyphen.`);
+        if (!input.id)
+            generatedCardIds.push(id);
+        const formId = normalizeNullableText(input.formId);
+        if (formId && !formIds.has(formId)) {
+            throw new Error(`Form ${formId} not found in event.forms. Create it with oko_configure_blocks forms first, or set formId:null.`);
+        }
+        const previous = existingById.get(id);
+        if (previous && cardHasImage(previous))
+            preservedImageCardIds.push(id);
+        return {
+            id,
+            title: normalizeNullableText(input.title),
+            text: normalizeNullableText(input.text),
+            buttonLabel: normalizeNullableText(input.buttonLabel),
+            buttonUrl: normalizeCardButtonUrl(input.buttonUrl),
+            imageUrl: previous?.imageUrl ?? null,
+            imageMasterUrl: previous?.imageMasterUrl ?? null,
+            imageVariants: previous?.imageVariants ?? null,
+            formId,
+        };
+    });
+    return { items, generatedCardIds, preservedImageCardIds };
+}
 async function deleteStoragePaths(paths) {
     const warnings = [];
     for (const path of [...new Set(paths.filter(Boolean))]) {
@@ -1110,6 +1249,92 @@ export function registerTools(server) {
         await updateDoc(doc(firestore, "events", args.eventId), patch);
         return textResult({ id: args.eventId, updated: Object.keys(patch) });
     });
+    server.registerTool("oko_configure_cards", {
+        title: "Configure event cards",
+        description: toolDescription({
+            summary: "Configure the Cards setup block and replace its card list. Images are managed separately through oko_upload_image and are preserved by matching card id.",
+            args: [
+                "eventId: event to edit.",
+                "enabled: optional Cards block enabled flag.",
+                "visibility: optional default visibility, always or hidden.",
+                "cardImageRatio: optional image ratio, one of auto, 1:1, 4:3, 3:2, 16:9, 2:3, 3:4.",
+                "items: optional full replacement array, max 6 cards. Each item may include id, title, text, buttonLabel, buttonUrl, formId.",
+            ],
+            returns: "event id, updated Firestore fields, normalized cards config, generated card ids, preserved image ids, removed card ids, and warnings.",
+            examples: [
+                "Use after oko_create_webinar to create cards before uploading per-card images.",
+                "Call oko_get_event first and pass the full desired items array when editing existing cards.",
+                "Use formId instead of buttonUrl when a card button should open a lead form.",
+            ],
+            notes: [
+                "This tool replaces blocks.cards.items when items is provided; omitted text fields become null.",
+                "Existing card images are preserved only when the same card id remains in the replacement list.",
+                "buttonUrl allows http(s), mailto, or tel URLs; javascript/data URLs are rejected.",
+                "If a removed card had an image, Storage cleanup is not automatic; this matches the web Setup behavior.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            enabled: z.boolean().optional().describe("Whether the Cards block is enabled in setup."),
+            visibility: z.enum(["always", "hidden"]).optional().describe("Default visibility when no live override exists."),
+            cardImageRatio: z.enum(CARD_IMAGE_RATIOS).optional().describe("Image aspect ratio for all cards."),
+            items: z.array(cardItemInputSchema).max(MAX_CARD_ITEMS).optional().describe("Full replacement list, max 6 cards. Omit to update only block settings."),
+        },
+        outputSchema: cardsConfigOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["setup:write"]);
+        const event = await readEvent(args.eventId, uid, "edit");
+        const currentCards = readCardsConfig(event);
+        const patch = {};
+        const finalCards = {
+            enabled: args.enabled ?? currentCards.enabled,
+            visibility: args.visibility ?? currentCards.visibility,
+            cardImageRatio: args.cardImageRatio ?? currentCards.cardImageRatio,
+            items: currentCards.items,
+        };
+        const generatedCardIds = [];
+        const preservedImageCardIds = [];
+        let removedCardIds = [];
+        let removedCardsWithImages = [];
+        if (args.enabled !== undefined)
+            patch["blocks.cards.enabled"] = args.enabled;
+        if (args.visibility !== undefined)
+            patch["blocks.cards.visibility"] = args.visibility;
+        if (args.cardImageRatio !== undefined)
+            patch["blocks.cards.cardImageRatio"] = args.cardImageRatio;
+        if (args.items !== undefined) {
+            const built = buildCardsItems({
+                inputs: args.items,
+                existing: currentCards.items,
+                formIds: eventFormIds(event),
+            });
+            finalCards.items = built.items;
+            generatedCardIds.push(...built.generatedCardIds);
+            preservedImageCardIds.push(...built.preservedImageCardIds);
+            const nextIds = new Set(built.items.map((item) => item.id));
+            const removed = currentCards.items.filter((item) => !nextIds.has(item.id));
+            removedCardIds = removed.map((item) => item.id);
+            removedCardsWithImages = removed.filter(cardHasImage).map((item) => item.id);
+            patch["blocks.cards.items"] = built.items;
+        }
+        if (Object.keys(patch).length > 0) {
+            await updateDoc(doc(firestore, "events", args.eventId), patch);
+        }
+        const warnings = removedCardsWithImages.length > 0
+            ? [`Removed cards had images and their Storage files were not deleted: ${removedCardsWithImages.join(", ")}.`]
+            : [];
+        return textResult({
+            eventId: args.eventId,
+            updated: Object.keys(patch),
+            cards: finalCards,
+            generatedCardIds,
+            removedCardIds,
+            removedCardsWithImages,
+            preservedImageCardIds,
+            warnings,
+        });
+    });
     server.registerTool("oko_upload_image", {
         title: "Upload event image",
         description: toolDescription({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",