@okostream/mcp 0.1.0 → 0.1.2

package/README.md

@@ -106,6 +106,9 @@ 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`
 - `oko_refresh_viewers`
 - `oko_start_session`
@@ -128,7 +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_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/firebase.js

@@ -3,6 +3,7 @@ import { getAuth } from "firebase/auth";
 import { getDatabase } from "firebase/database";
 import { getFirestore } from "firebase/firestore";
 import { getFunctions } from "firebase/functions";
+import { getStorage } from "firebase/storage";
 import { env } from "./env.js";
 export const firebaseApp = getApps().length ? getApp() : initializeApp({
     apiKey: env.firebase.apiKey,
@@ -20,3 +21,4 @@ export const chatRtdb = env.firebase.chatDatabaseURL
     ? getDatabase(firebaseApp, env.firebase.chatDatabaseURL)
     : getDatabase(firebaseApp);
 export const functions = getFunctions(firebaseApp, "us-central1");
+export const storage = getStorage(firebaseApp);

package/dist/server.js

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

package/dist/tools.js

@@ -1,12 +1,38 @@
+import { lookup } from "node:dns/promises";
+import { stat, readFile } from "node:fs/promises";
+import { isIP } from "node:net";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import sharp from "sharp";
 import { z } from "zod";
 import { addDoc, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, setDoc, startAfter, Timestamp, updateDoc, where, } from "firebase/firestore";
 import { get, endBefore, limitToLast, orderByKey, push, query as dbQuery, ref, remove, runTransaction, serverTimestamp as rtdbServerTimestamp, set, update, } from "firebase/database";
 import { httpsCallable } from "firebase/functions";
+import { deleteObject, getDownloadURL, ref as storageRef, uploadBytes, } from "firebase/storage";
 import { ensureAuth, currentScopes } from "./auth.js";
-import { chatRtdb, firestore, functions, rtdb } from "./firebase.js";
+import { chatRtdb, firestore, functions, rtdb, storage } from "./firebase.js";
 import { csvCell, requireConfirm, safeString, serialize, textResult } from "./utils.js";
 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;
+const TARGET_MASTER_IMAGE_BYTES = 600 * 1024;
+const MAX_MASTER_IMAGE_DIMENSION = 1600;
+const REMOTE_IMAGE_TIMEOUT_MS = 15_000;
+const REMOTE_IMAGE_MAX_REDIRECTS = 3;
+const ALLOWED_SOURCE_IMAGE_FORMATS = new Set(["jpeg", "png", "webp", "gif", "avif"]);
+const ALLOWED_REMOTE_IMAGE_TYPES = new Set(["image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif", "image/avif"]);
 const MAX_FIRESTORE_TIMELINE_BUCKETS = 1500;
 const DEFAULT_LIST_LIMIT = 30;
 const MAX_LIST_LIMIT = 100;
@@ -95,6 +121,25 @@ const leadsOutputSchema = z.object({
     csv: z.string().optional(),
     ...cursorMetaSchema,
 }).passthrough();
+const imageOutputSchema = z.object({
+    eventId: z.string(),
+    kind: z.enum(IMAGE_KINDS),
+    imageId: z.string(),
+    storagePath: z.string(),
+    masterUrl: z.string().url(),
+    variantsPending: z.boolean(),
+    sourceBytes: z.number().int().nonnegative(),
+    masterBytes: z.number().int().nonnegative(),
+    note: z.string(),
+}).passthrough();
+const deleteImageOutputSchema = z.object({
+    eventId: z.string(),
+    kind: z.enum(IMAGE_KINDS),
+    imageId: z.string().nullable(),
+    deleted: z.boolean(),
+    storageDeletesAttempted: z.number().int().nonnegative(),
+    storageDeleteWarnings: z.array(z.string()),
+}).passthrough();
 const formFieldSchema = z.object({
     id: z.string().min(1).optional(),
     label: z.string().max(120),
@@ -112,6 +157,38 @@ const formSchema = z.object({
     consentRequired: z.boolean().default(true),
     fields: z.array(formFieldSchema).max(30),
 }).strict();
+const imageSourceSchema = z.object({
+    path: z.string().min(1).optional().describe("Local image path on the MCP client machine."),
+    url: z.string().url().optional().describe("HTTPS image URL to fetch from the MCP client machine."),
+}).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(),
@@ -154,6 +231,391 @@ function pickPage(items, max) {
 function randomId() {
     return Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
+function imageStoragePath(eventId, uid, kind, imageId) {
+    return `events/${eventId}/${uid}/images/${kind}/${imageId}/master.webp`;
+}
+function storagePathFromDownloadUrl(downloadUrl) {
+    if (!downloadUrl)
+        return null;
+    const match = downloadUrl.match(/\/o\/([^?]+)/);
+    if (!match)
+        return null;
+    const encodedPath = match[1];
+    if (!encodedPath)
+        return null;
+    try {
+        return decodeURIComponent(encodedPath);
+    }
+    catch {
+        return null;
+    }
+}
+function variantPathsFromMasterPath(masterPath) {
+    if (!masterPath.endsWith("/master.webp"))
+        return [];
+    return IMAGE_VARIANT_NAMES.map((name) => masterPath.replace(/master\.webp$/, name));
+}
+function resolveLocalImagePath(inputPath) {
+    const expanded = inputPath === "~" || inputPath.startsWith("~/")
+        ? join(homedir(), inputPath.slice(2))
+        : inputPath;
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
+}
+function isBlockedHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local");
+}
+function isBlockedIp(address) {
+    const normalized = address.toLowerCase().startsWith("::ffff:")
+        ? address.slice(7)
+        : address;
+    const version = isIP(normalized);
+    if (version === 4) {
+        const [a = -1, b = -1] = normalized.split(".").map((part) => Number(part));
+        return a === 0
+            || a === 10
+            || a === 127
+            || (a === 169 && b === 254)
+            || (a === 172 && b >= 16 && b <= 31)
+            || (a === 192 && b === 168);
+    }
+    if (version === 6) {
+        return normalized === "::1"
+            || normalized.startsWith("fc")
+            || normalized.startsWith("fd")
+            || normalized.startsWith("fe80:");
+    }
+    return false;
+}
+async function assertRemoteImageUrlAllowed(url) {
+    if (url.protocol !== "https:") {
+        throw new Error("Image URL must use https://.");
+    }
+    if (url.username || url.password) {
+        throw new Error("Image URL must not include embedded credentials.");
+    }
+    if (isBlockedHostname(url.hostname)) {
+        throw new Error("Image URL host is not allowed. Use a public HTTPS image URL.");
+    }
+    if (isIP(url.hostname)) {
+        if (isBlockedIp(url.hostname)) {
+            throw new Error("Image URL points to a private/local IP address, which is not allowed.");
+        }
+        return;
+    }
+    const addresses = await lookup(url.hostname, { all: true });
+    if (addresses.some((item) => isBlockedIp(item.address))) {
+        throw new Error("Image URL resolves to a private/local IP address, which is not allowed.");
+    }
+}
+async function responseBufferWithLimit(response, maxBytes) {
+    const body = response.body;
+    if (!body) {
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.byteLength > maxBytes)
+            throw new Error(`Image exceeds ${Math.floor(maxBytes / 1024 / 1024)}MB limit.`);
+        return bytes;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value);
+            total += chunk.byteLength;
+            if (total > maxBytes) {
+                throw new Error(`Image exceeds ${Math.floor(maxBytes / 1024 / 1024)}MB limit.`);
+            }
+            chunks.push(chunk);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+}
+async function readRemoteImage(rawUrl, redirects = 0) {
+    if (redirects > REMOTE_IMAGE_MAX_REDIRECTS) {
+        throw new Error("Image URL has too many redirects.");
+    }
+    const url = new URL(rawUrl);
+    await assertRemoteImageUrlAllowed(url);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REMOTE_IMAGE_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            redirect: "manual",
+            signal: controller.signal,
+            headers: { accept: "image/avif,image/webp,image/png,image/jpeg,image/gif" },
+        });
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get("location");
+            if (!location)
+                throw new Error(`Image URL redirected with HTTP ${response.status} but no Location header.`);
+            return readRemoteImage(new URL(location, url).toString(), redirects + 1);
+        }
+        if (!response.ok) {
+            throw new Error(`Image URL fetch failed with HTTP ${response.status}.`);
+        }
+        const contentType = (response.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
+        if (!contentType || !contentType.startsWith("image/")) {
+            throw new Error("Image URL must return Content-Type image/*.");
+        }
+        if (!ALLOWED_REMOTE_IMAGE_TYPES.has(contentType)) {
+            throw new Error(`Image URL Content-Type ${contentType} is not supported. Use JPEG, PNG, WEBP, GIF, or AVIF.`);
+        }
+        const contentLength = Number(response.headers.get("content-length") ?? 0);
+        if (Number.isFinite(contentLength) && contentLength > MAX_SOURCE_IMAGE_BYTES) {
+            throw new Error("Image URL is larger than 15MB.");
+        }
+        return responseBufferWithLimit(response, MAX_SOURCE_IMAGE_BYTES);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error("Image URL fetch timed out.");
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readLocalImage(inputPath) {
+    const filePath = resolveLocalImagePath(inputPath);
+    const info = await stat(filePath);
+    if (!info.isFile())
+        throw new Error("Image path must point to a regular file.");
+    if (info.size > MAX_SOURCE_IMAGE_BYTES)
+        throw new Error("Image file is larger than 15MB.");
+    return readFile(filePath);
+}
+async function readImageSource(source) {
+    if (source.path)
+        return readLocalImage(source.path);
+    if (source.url)
+        return readRemoteImage(source.url);
+    throw new Error("Provide image source path or url.");
+}
+async function compressToMasterWebp(input) {
+    const metadata = await sharp(input, { limitInputPixels: MAX_SOURCE_IMAGE_PIXELS }).metadata();
+    if (!metadata.format || !ALLOWED_SOURCE_IMAGE_FORMATS.has(metadata.format)) {
+        throw new Error(`Unsupported image format ${metadata.format ?? "unknown"}. Use JPEG, PNG, WEBP, GIF, or AVIF.`);
+    }
+    const transformer = sharp(input, { limitInputPixels: MAX_SOURCE_IMAGE_PIXELS })
+        .rotate()
+        .resize({
+        width: MAX_MASTER_IMAGE_DIMENSION,
+        height: MAX_MASTER_IMAGE_DIMENSION,
+        fit: "inside",
+        withoutEnlargement: true,
+    });
+    let last = null;
+    for (const quality of [88, 84, 80, 76, 72]) {
+        const out = await transformer.clone().webp({ quality }).toBuffer();
+        last = out;
+        if (out.byteLength <= TARGET_MASTER_IMAGE_BYTES)
+            return out;
+    }
+    if (!last)
+        throw new Error("Image compression failed.");
+    if (last.byteLength > MAX_MASTER_IMAGE_BYTES) {
+        throw new Error("Compressed image is still larger than Firebase Storage 10MB limit.");
+    }
+    return last;
+}
+function readImageRef(eventData, kind, cardId) {
+    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
+    if (kind === "promoBanner") {
+        const banner = (blocks.promoBanner && typeof blocks.promoBanner === "object" ? blocks.promoBanner : {});
+        return {
+            imageId: storagePathFromDownloadUrl(safeString(banner.imageMasterUrl))?.split("/").at(-2) ?? null,
+            imageUrl: safeString(banner.imageUrl) || null,
+            imageMasterUrl: safeString(banner.imageMasterUrl) || null,
+        };
+    }
+    if (kind === "videoPlaceholder") {
+        const video = (blocks.video && typeof blocks.video === "object" ? blocks.video : {});
+        const placeholder = (video.placeholder && typeof video.placeholder === "object" ? video.placeholder : {});
+        return {
+            imageId: storagePathFromDownloadUrl(safeString(placeholder.imageMasterUrl))?.split("/").at(-2) ?? null,
+            imageUrl: safeString(placeholder.imageUrl) || null,
+            imageMasterUrl: safeString(placeholder.imageMasterUrl) || null,
+        };
+    }
+    if (!cardId)
+        throw new Error("cardId is required when kind is card.");
+    const cards = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
+    const items = Array.isArray(cards.items) ? cards.items : [];
+    const item = items.find((raw) => Boolean(raw) && typeof raw === "object" && raw.id === cardId);
+    if (!item)
+        throw new Error(`Card ${cardId} not found in blocks.cards.items. Create/configure the card before uploading its image.`);
+    return {
+        imageId: cardId,
+        imageUrl: safeString(item.imageUrl) || null,
+        imageMasterUrl: safeString(item.imageMasterUrl) || null,
+    };
+}
+function cardItemsWithImage(eventData, cardId, patch) {
+    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
+    const cards = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
+    const items = Array.isArray(cards.items) ? cards.items : [];
+    let found = false;
+    const next = items.map((raw) => {
+        const item = (raw && typeof raw === "object" ? raw : {});
+        if (item.id !== cardId)
+            return item;
+        found = true;
+        return { ...item, ...patch };
+    });
+    if (!found)
+        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))]) {
+        try {
+            await deleteObject(storageRef(storage, path));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`${path}: ${msg}`);
+        }
+    }
+    return warnings;
+}
+async function deleteStorageUrls(masterUrl, fallbackUrl) {
+    const paths = [];
+    const masterPath = storagePathFromDownloadUrl(masterUrl);
+    if (masterPath) {
+        paths.push(masterPath, ...variantPathsFromMasterPath(masterPath));
+    }
+    else {
+        const fallbackPath = storagePathFromDownloadUrl(fallbackUrl);
+        if (fallbackPath)
+            paths.push(fallbackPath);
+    }
+    const warnings = await deleteStoragePaths(paths);
+    return { attempted: [...new Set(paths)].length, warnings };
+}
+async function uploadMasterImage(path, image) {
+    const ref = storageRef(storage, path);
+    await uploadBytes(ref, new Uint8Array(image), {
+        contentType: "image/webp",
+        cacheControl: "private, no-store",
+        customMetadata: { "Cache-Control": "private, no-store" },
+    });
+    return getDownloadURL(ref);
+}
 async function authed(scopes) {
     return ensureAuth(scopes);
 }
@@ -787,6 +1249,249 @@ 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({
+            summary: "Upload and compress an image for an OKO setup block, then write the master URL back to Firestore.",
+            args: [
+                "eventId: event to edit.",
+                "kind: promoBanner, videoPlaceholder, or card.",
+                "cardId: required when kind=card; must match an existing blocks.cards.items id.",
+                "source: exactly one of local path or HTTPS image URL.",
+            ],
+            returns: "eventId, kind, imageId, Storage path, masterUrl, byte counts, and a note that CF-generated variants are pending.",
+            examples: [
+                'Use kind="promoBanner" with source.url to set a webinar banner from an image link.',
+                'Use kind="card" with cardId after the card item already exists.',
+            ],
+            notes: [
+                "The MCP server reads local paths on the organizer machine.",
+                "Remote URLs must be public HTTPS images, max 15MB; private/local hosts are blocked.",
+                "For card images, imageId is the cardId so OKO CF4 can update the correct item.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            kind: z.enum(IMAGE_KINDS).describe("Target image slot."),
+            cardId: z.string().min(1).optional().describe("Required when kind=card."),
+            source: imageSourceSchema.describe("Image source: exactly one of path or url."),
+        },
+        outputSchema: imageOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, kind, cardId, source }) => {
+        const { uid } = await authed(["setup:write"]);
+        if (kind === "card" && !cardId)
+            throw new Error("cardId is required when kind is card.");
+        if (kind !== "card" && cardId)
+            throw new Error("cardId is only valid when kind is card.");
+        const event = await readEvent(eventId, uid, "edit");
+        const previous = readImageRef(event, kind, cardId);
+        const sourceBuffer = await readImageSource(source);
+        const masterBuffer = await compressToMasterWebp(sourceBuffer);
+        const imageId = kind === "card" ? cardId : randomUUID();
+        const masterPath = imageStoragePath(eventId, uid, kind, imageId);
+        const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
+        const deleteWarnings = [];
+        let deletesAttempted = 0;
+        if (kind === "card" && previousMasterPath === masterPath) {
+            const variantPaths = variantPathsFromMasterPath(masterPath);
+            deletesAttempted += variantPaths.length;
+            deleteWarnings.push(...await deleteStoragePaths(variantPaths));
+        }
+        let masterUrl = null;
+        try {
+            masterUrl = await uploadMasterImage(masterPath, masterBuffer);
+            const patch = {};
+            if (kind === "promoBanner") {
+                patch["blocks.promoBanner.imageMasterUrl"] = masterUrl;
+                patch["blocks.promoBanner.imageUrl"] = masterUrl;
+                patch["blocks.promoBanner.imageVariants"] = null;
+            }
+            else if (kind === "videoPlaceholder") {
+                patch["blocks.video.placeholder.imageMasterUrl"] = masterUrl;
+                patch["blocks.video.placeholder.imageUrl"] = masterUrl;
+                patch["blocks.video.placeholder.imageVariants"] = null;
+            }
+            else {
+                patch["blocks.cards.items"] = cardItemsWithImage(event, cardId, {
+                    imageUrl: masterUrl,
+                    imageMasterUrl: masterUrl,
+                    imageVariants: null,
+                });
+            }
+            await updateDoc(doc(firestore, "events", eventId), patch);
+        }
+        catch (err) {
+            if (masterUrl) {
+                await deleteStoragePaths([masterPath, ...variantPathsFromMasterPath(masterPath)]).catch(() => []);
+            }
+            throw err;
+        }
+        if (kind !== "card" || (previousMasterPath && previousMasterPath !== masterPath) || (!previous.imageMasterUrl && previous.imageUrl)) {
+            const cleanup = await deleteStorageUrls(previous.imageMasterUrl, previous.imageUrl);
+            deletesAttempted += cleanup.attempted;
+            deleteWarnings.push(...cleanup.warnings);
+        }
+        return textResult({
+            eventId,
+            kind,
+            imageId,
+            storagePath: masterPath,
+            masterUrl,
+            variantsPending: true,
+            sourceBytes: sourceBuffer.byteLength,
+            masterBytes: masterBuffer.byteLength,
+            note: "Image master uploaded. CF generateImageVariants should publish thumb/card/hero variants and update imageUrl/imageVariants in about 10-30 seconds.",
+            storageDeletesAttempted: deletesAttempted,
+            storageDeleteWarnings: deleteWarnings,
+        });
+    });
+    server.registerTool("oko_delete_image", {
+        title: "Delete event image",
+        description: toolDescription({
+            summary: "Delete an OKO setup block image from Storage and clear the corresponding Firestore image fields.",
+            args: [
+                "eventId: event to edit.",
+                "kind: promoBanner, videoPlaceholder, or card.",
+                "cardId: required when kind=card.",
+                "confirm: must be true.",
+            ],
+            returns: "eventId, kind, deleted=true, and best-effort Storage cleanup warnings if any.",
+            examples: ["Use only after confirming the exact event and image slot with the user."],
+            notes: ["Destructive. Storage cleanup mirrors the web Setup screen: failed object deletes do not block clearing Firestore fields."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            kind: z.enum(IMAGE_KINDS).describe("Target image slot."),
+            cardId: z.string().min(1).optional().describe("Required when kind=card."),
+            confirm: z.boolean().optional().describe("Required true for image deletion."),
+        },
+        outputSchema: deleteImageOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, kind, cardId, confirm }) => {
+        const { uid } = await authed(["setup:write"]);
+        if (kind === "card" && !cardId)
+            throw new Error("cardId is required when kind is card.");
+        if (kind !== "card" && cardId)
+            throw new Error("cardId is only valid when kind is card.");
+        const event = await readEvent(eventId, uid, "edit");
+        const previous = readImageRef(event, kind, cardId);
+        requireConfirm(confirm, "oko_delete_image", { eventId, kind, cardId: cardId ?? null, imageId: previous.imageId });
+        const cleanup = await deleteStorageUrls(previous.imageMasterUrl, previous.imageUrl);
+        const patch = {};
+        if (kind === "promoBanner") {
+            patch["blocks.promoBanner.imageMasterUrl"] = deleteField();
+            patch["blocks.promoBanner.imageUrl"] = deleteField();
+            patch["blocks.promoBanner.imageVariants"] = deleteField();
+        }
+        else if (kind === "videoPlaceholder") {
+            patch["blocks.video.placeholder.imageMasterUrl"] = deleteField();
+            patch["blocks.video.placeholder.imageUrl"] = deleteField();
+            patch["blocks.video.placeholder.imageVariants"] = deleteField();
+        }
+        else {
+            patch["blocks.cards.items"] = cardItemsWithImage(event, cardId, {
+                imageUrl: null,
+                imageMasterUrl: null,
+                imageVariants: null,
+            });
+        }
+        await updateDoc(doc(firestore, "events", eventId), patch);
+        return textResult({
+            eventId,
+            kind,
+            imageId: previous.imageId ?? (kind === "card" ? cardId : null),
+            deleted: true,
+            storageDeletesAttempted: cleanup.attempted,
+            storageDeleteWarnings: cleanup.warnings,
+        });
+    });
     server.registerTool("oko_delete_event", {
         title: "Delete event",
         description: toolDescription({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",
@@ -32,6 +32,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.2.3",
     "firebase": "^12.10.0",
+    "sharp": "^0.33.5",
     "zod": "^3.25.76"
   },
   "devDependencies": {