@okostream/mcp 0.3.0 → 0.4.1

package/README.md

@@ -59,6 +59,12 @@ Every tool returns JSON text plus MCP `structuredContent`. List-like tools use b
 - `oko_get_session_report` returns a compact structured session report plus markdown suitable for a human handoff.
 - Oversized responses are truncated with `truncated: true` and a `truncationMessage`.
 
+The server also exposes MCP-native onboarding:
+
+- `instructions` on initialize with the supported webinar creation flow and product invariants.
+- Resources: `oko://guide/create-webinar`, `oko://guide/platform`, `oko://guide/security`, `oko://schema/event`, `oko://capabilities`.
+- Prompts: `create_webinar_from_brief`, `audit_event_setup`, `prepare_session_report`.
+
 This package is published as source-available runtime distribution for OKO customers. `license: UNLICENSED` means all rights reserved unless a separate agreement says otherwise.
 
 ## Local Development
@@ -93,6 +99,7 @@ All tools are prefixed with `oko_` for safe discovery next to other MCP servers.
 Core discovery/read tools:
 
 - `oko_whoami`, `oko_list_workspaces`, `oko_list_my_events`, `oko_get_event`
+- `oko_validate_event_setup`
 - `oko_update_profile`, `oko_list_notifications`, `oko_mark_notifications_read`
 - `oko_get_live_state`, `oko_get_analytics`, `oko_get_session_report`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_delete_lead`
 
@@ -101,7 +108,7 @@ Event/setup/media tools:
 - `oko_create_webinar`, `oko_update_event`, `oko_delete_event`
 - `oko_duplicate_event`, `oko_move_event`
 - `oko_configure_blocks`, `oko_configure_cards`
-- `oko_upload_image`, `oko_delete_image`
+- `oko_upload_image`, `oko_upload_card_images_batch`, `oko_wait_for_image_variants`, `oko_delete_image`
 
 Live/session/chat/NMO tools:
 
@@ -126,13 +133,15 @@ Dangerous or external side-effect tools require `confirm: true`.
 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_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_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
-7. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
-8. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
-9. `oko_get_session_report` should return markdown and structured session data for a completed session.
-10. `oko_list_notifications` -> `oko_mark_notifications_read` should read and clear an own disposable notification.
-11. `oko_get_analytics` should read an existing event with analytics sessions.
+5. `oko_upload_card_images_batch` should upload multiple card images, then return ready `imageVariants`.
+6. `oko_validate_event_setup` should catch missing images/forms/buttons/video/NMO/Telegram/variants on a deliberately broken event.
+7. `oko_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
+8. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
+9. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
+10. `oko_get_session_report` should return markdown and structured session data for a completed session.
+11. `oko_list_notifications` -> `oko_mark_notifications_read` should read and clear an own disposable notification.
+12. `oko_get_analytics` should read an existing event with analytics sessions.
+13. MCP protocol smoke should report 59 tools, 5 resources, 3 prompts, and non-empty initialize instructions.
 
 CLI help:
 

package/dist/guides.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+export const OKO_MCP_INSTRUCTIONS = [
+    "You are controlling OKO Stream as an organizer through MCP tools.",
+    "Start every new workspace session with oko_whoami, then respect the returned scopes.",
+    "OKO events have no draft/live/ended status. Start/End controls manage analytics sessions only, never video streaming.",
+    "For webinar creation, prefer this flow: oko_create_webinar, oko_configure_blocks, oko_configure_cards, image uploads, oko_validate_event_setup, then return public/setup/analytics links.",
+    "For card images, create stable card ids first, then use oko_upload_card_images_batch or oko_upload_image plus oko_wait_for_image_variants.",
+    "Before destructive actions, show the exact target and require an explicit user confirmation; then pass confirm=true.",
+    "Use oko_validate_event_setup before telling the organizer that a webinar is ready.",
+    "Do not bypass OKO APIs or Firebase rules; this server is the supported organizer surface.",
+].join("\n");
+const GUIDE_RESOURCES = [
+    {
+        name: "oko_mcp_create_webinar",
+        uri: "oko://guide/create-webinar",
+        title: "Create an OKO Webinar",
+        description: "Recommended call order for creating and validating a webinar.",
+        text: [
+            "# Create an OKO Webinar",
+            "",
+            "1. Call `oko_whoami` and inspect scopes.",
+            "2. If the workspace is unclear, call `oko_list_workspaces`.",
+            "3. Call `oko_create_webinar` with title/date/workspace and video URL when known.",
+            "4. Call `oko_configure_blocks` for video, forms, CTA, banner, Telegram, and NMO settings.",
+            "5. Call `oko_configure_cards` with stable card ids before uploading card images.",
+            "6. Upload images with `oko_upload_card_images_batch` or `oko_upload_image`, then wait for variants.",
+            "7. Call `oko_validate_event_setup` and fix blocking findings.",
+            "8. Return public, setup, analytics, registration, and login links that apply to the event.",
+            "",
+            "Important: OKO has no event status. Do not invent draft/live/ended lifecycle states.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_platform",
+        uri: "oko://guide/platform",
+        title: "OKO Platform Invariants",
+        description: "Core OKO product rules that MCP clients must respect.",
+        text: [
+            "# OKO Platform Invariants",
+            "",
+            "- OKO events have no `draft`, `live`, or `ended` status field.",
+            "- Public event pages render whenever the event exists and normal access rules allow it.",
+            "- Start and End controls manage analytics sessions only; they never start or stop the video stream.",
+            "- Setup writes Firestore event structure. Live analytics and controls use RTDB mirrors and session nodes.",
+            "- Chat lives in the separate chat RTDB. Moderator actions require chat scopes and normal event access.",
+            "- NMO participant import is handled by the scoped Cloud Function `importNmoParticipants`.",
+            "- Image variants are asynchronous. A master upload is not fully ready until `imageVariants` are present.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_security",
+        uri: "oko://guide/security",
+        title: "OKO MCP Security Model",
+        description: "API-key, scopes, confirmation, and Firebase rules boundaries.",
+        text: [
+            "# OKO MCP Security Model",
+            "",
+            "The MCP server acts as the organizer user represented by `OKO_API_KEY`. It is not a platform-admin backdoor.",
+            "",
+            "Security layers:",
+            "- API keys are stored hashed in Firestore and the full secret is shown only once in the OKO UI.",
+            "- `exchangeApiKey` mints short-lived Firebase custom tokens with legacy `scopes` and rules-readable `mcpScopes`.",
+            "- MCP tools check scopes before executing.",
+            "- Firestore, RTDB, chat RTDB, and Storage rules also check `mcpScopes` for direct Firebase SDK misuse.",
+            "- Destructive or external side-effect tools require explicit `confirm:true`.",
+            "- Wrong API-key exchanges are counted per keyId; after 10 failures the keyId is locked for 15 minutes.",
+            "",
+            "- `events:read`: list and read event documents.",
+            "- `events:write`: create, duplicate, move, and update event metadata.",
+            "- `events:delete`: delete event records.",
+            "- `setup:write`: configure blocks, forms, cards, and images.",
+            "- `analytics:read`: read live state, sessions, reports, chat history.",
+            "- `analytics:write` + `live:control`: start/end/fix/delete analytics sessions.",
+            "- `live:control`: live block visibility and viewer refresh.",
+            "- `chat:write`: send organizer chat messages.",
+            "- `chat:moderate`: delete, mute, ban, unmute, unban, and chat settings.",
+            "- `telegram:write`: claim/list channels and create/cancel/publish Telegram posts.",
+            "- `workspace:read` / `workspace:write`: workspace, members, invites, notifications.",
+            "- `nmo:write`: NMO participants and checkpoints.",
+            "- `leads:read`: read form submissions; lead deletion also requires `setup:write`.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_event_schema",
+        uri: "oko://schema/event",
+        title: "OKO Event Schema Notes",
+        description: "Compact schema notes for fields most often edited by MCP clients.",
+        text: [
+            "# OKO Event Schema Notes",
+            "",
+            "Common event fields:",
+            "- `title`: user-visible webinar title.",
+            "- `meta.eventDate`: scheduled date.",
+            "- `video.originalUrl` / `video.embedUrl`: raw and normalized video URLs.",
+            "- `forms[]`: lead forms with `id`, `type`, `title`, `fields[]`, consent copy, and submit/success text.",
+            "- `blocks.primaryCta`: CTA copy, `buttonUrl` or `formId`, and visibility.",
+            "- `blocks.promoBanner`: banner copy, link/form binding, image refs, variants, and visibility.",
+            "- `blocks.cards.items[]`: stable `id`, copy, optional `buttonUrl` or `formId`, image refs, and `imageVariants`.",
+            "- `telegram.channelIds`: claimed Telegram channels for notifications.",
+            "- `nmoMode`, `nmoCriteria`, `participantUids`: NMO mode and participant gates.",
+            "- `workspaceId`, `accessibleBy`, `editors`: access mirrors required by rules and dashboard queries.",
+            "",
+            "Do not remove unknown fields when updating nested config. Use dedicated MCP tools instead of whole-document rewrites.",
+        ].join("\n"),
+    },
+    {
+        name: "oko_mcp_capabilities",
+        uri: "oko://capabilities",
+        title: "OKO MCP Capabilities",
+        description: "High-level workflows available through OKO MCP.",
+        text: [
+            "# OKO MCP Capabilities",
+            "",
+            "## Webinar setup",
+            "- Create, duplicate, move, update, validate, and delete webinars.",
+            "- Configure forms, CTA, banner, cards, video placeholder, Telegram, and NMO settings.",
+            "- Upload images from local paths, data URLs, or HTTPS URLs and wait for variants.",
+            "",
+            "## Live analytics",
+            "- Read live state, start/end analytics sessions, refresh viewers, and change block visibility.",
+            "- Read compact analytics, session reports, leads, chat history, and NMO participation data.",
+            "- Fix or delete orphan sessions only after explicit confirmation.",
+            "",
+            "## Collaboration and comms",
+            "- Manage workspaces, members, invites, notifications, and Telegram post lifecycle.",
+            "- Send organizer chat messages and moderate chat users when scoped.",
+            "- Import/remove NMO participants through scoped Cloud Functions.",
+        ].join("\n"),
+    },
+];
+function promptMessage(text) {
+    return {
+        messages: [{
+                role: "user",
+                content: { type: "text", text },
+            }],
+    };
+}
+export function registerGuides(server) {
+    for (const resource of GUIDE_RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown",
+        }, async (uri) => ({
+            contents: [{
+                    uri: uri.toString(),
+                    mimeType: "text/markdown",
+                    text: resource.text,
+                }],
+        }));
+    }
+    server.registerPrompt("create_webinar_from_brief", {
+        title: "Create Webinar From Brief",
+        description: "Plan and execute a complete OKO webinar setup from an organizer brief.",
+        argsSchema: {
+            brief: z.string().min(1).describe("Organizer brief with topic, date, audience, blocks, images, and integrations."),
+            workspaceId: z.string().optional().describe("Optional OKO workspace id."),
+        },
+    }, async ({ brief, workspaceId }) => promptMessage([
+        "Create an OKO webinar from this brief using MCP tools.",
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify scopes.",
+        "2. Create the webinar in the requested workspace if provided.",
+        "3. Configure metadata, blocks, forms, Telegram, NMO, and cards as needed.",
+        "4. Upload images only after target slots/cards exist; wait for image variants.",
+        "5. Run oko_validate_event_setup and fix actionable errors.",
+        "6. Return public, setup, analytics, registration/login links as applicable.",
+        "",
+        workspaceId ? `Workspace id: ${workspaceId}` : "Workspace id: not specified; choose the personal workspace unless the user clarifies.",
+        "",
+        "Brief:",
+        brief,
+    ].join("\n")));
+    server.registerPrompt("audit_event_setup", {
+        title: "Audit Event Setup",
+        description: "Audit an OKO event for readiness and produce a fix plan.",
+        argsSchema: {
+            eventId: z.string().min(1).describe("OKO event id to audit."),
+            focus: z.string().optional().describe("Optional focus area, for example NMO, Telegram, forms, cards, live."),
+        },
+    }, async ({ eventId, focus }) => promptMessage([
+        `Audit OKO event ${eventId}.`,
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify scopes.",
+        "2. Call oko_get_event and oko_validate_event_setup.",
+        "3. If relevant, inspect live state, Telegram posts, participants, leads, and image variant readiness.",
+        "4. Separate errors that block launch from warnings and polish suggestions.",
+        "5. Propose exact MCP tool calls needed to fix issues; execute only if the organizer asked for implementation.",
+        "",
+        focus ? `Focus: ${focus}` : "Focus: full setup readiness.",
+    ].join("\n")));
+    server.registerPrompt("prepare_session_report", {
+        title: "Prepare Session Report",
+        description: "Prepare an organizer-friendly report from OKO analytics session data.",
+        argsSchema: {
+            eventId: z.string().min(1).describe("OKO event id."),
+            sessionId: z.string().optional().describe("Optional analytics session id; omit to choose from sessions list."),
+            audience: z.string().optional().describe("Optional report audience, for example internal, client, NMO."),
+        },
+    }, async ({ eventId, sessionId, audience }) => promptMessage([
+        `Prepare a session report for OKO event ${eventId}.`,
+        "",
+        "Required flow:",
+        "1. Call oko_whoami and verify analytics:read.",
+        sessionId ? `2. Use session id ${sessionId}.` : "2. Call oko_get_analytics and choose the relevant ended session id from returned sessions.",
+        "3. Call oko_get_session_report.",
+        "4. Summarize attendance, engagement, chat, CTA/cards, geo, and NMO if present.",
+        "5. Call out data caveats separately from conclusions.",
+        "",
+        audience ? `Audience: ${audience}` : "Audience: organizer/internal.",
+    ].join("\n")));
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { OKO_MCP_INSTRUCTIONS, registerGuides } from "./guides.js";
 import { registerTools } from "./tools.js";
 if (process.argv.includes("--help")) {
     process.stdout.write([
@@ -22,8 +23,11 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.3.0",
+    version: "0.4.1",
+}, {
+    instructions: OKO_MCP_INSTRUCTIONS,
 });
+registerGuides(server);
 registerTools(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools.js

@@ -6,7 +6,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 import { z } from "zod";
-import { addDoc, arrayRemove, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, setDoc, startAfter, Timestamp, updateDoc, where, } from "firebase/firestore";
+import { addDoc, arrayRemove, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, runTransaction as runFirestoreTransaction, 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";
@@ -144,6 +144,35 @@ const deleteImageOutputSchema = z.object({
     storageDeletesAttempted: z.number().int().nonnegative(),
     storageDeleteWarnings: z.array(z.string()),
 }).passthrough();
+const imageVariantsOutputSchema = z.object({
+    eventId: z.string(),
+    kind: z.enum(IMAGE_KINDS),
+    cardId: z.string().nullable(),
+    imageId: z.string().nullable(),
+    imageUrl: z.string().url().nullable(),
+    imageMasterUrl: z.string().url().nullable(),
+    imageVariants: unknownRecordSchema.nullable(),
+    ready: z.boolean(),
+    reason: z.string().nullable(),
+    elapsedMs: z.number().int().nonnegative(),
+}).passthrough();
+const cardImagesBatchOutputSchema = z.object({
+    eventId: z.string(),
+    uploads: z.array(unknownRecordSchema),
+    variants: z.array(unknownRecordSchema),
+    ready: z.boolean(),
+    warnings: z.array(z.string()),
+}).passthrough();
+const setupValidationOutputSchema = z.object({
+    eventId: z.string(),
+    ok: z.boolean(),
+    score: z.number().int().min(0).max(100),
+    errors: z.array(unknownRecordSchema),
+    warnings: z.array(unknownRecordSchema),
+    suggestions: z.array(unknownRecordSchema),
+    nextActions: z.array(z.string()),
+    links: unknownRecordSchema,
+}).passthrough();
 const workspaceAccessOutputSchema = z.object({
     workspaceId: z.string(),
     workspace: unknownRecordSchema,
@@ -511,6 +540,7 @@ function readImageRef(eventData, kind, cardId) {
             imageId: storagePathFromDownloadUrl(safeString(banner.imageMasterUrl))?.split("/").at(-2) ?? null,
             imageUrl: safeString(banner.imageUrl) || null,
             imageMasterUrl: safeString(banner.imageMasterUrl) || null,
+            imageVariants: readImageVariants(banner.imageVariants),
         };
     }
     if (kind === "videoPlaceholder") {
@@ -520,6 +550,7 @@ function readImageRef(eventData, kind, cardId) {
             imageId: storagePathFromDownloadUrl(safeString(placeholder.imageMasterUrl))?.split("/").at(-2) ?? null,
             imageUrl: safeString(placeholder.imageUrl) || null,
             imageMasterUrl: safeString(placeholder.imageMasterUrl) || null,
+            imageVariants: readImageVariants(placeholder.imageVariants),
         };
     }
     if (!cardId)
@@ -533,6 +564,7 @@ function readImageRef(eventData, kind, cardId) {
         imageId: cardId,
         imageUrl: safeString(item.imageUrl) || null,
         imageMasterUrl: safeString(item.imageMasterUrl) || null,
+        imageVariants: readImageVariants(item.imageVariants),
     };
 }
 function cardItemsWithImage(eventData, cardId, patch) {
@@ -693,6 +725,141 @@ async function uploadMasterImage(path, image) {
     });
     return getDownloadURL(ref);
 }
+async function updateCardImageInTransaction(eventId, cardId, patch) {
+    const eventRef = doc(firestore, "events", eventId);
+    await runFirestoreTransaction(firestore, async (transaction) => {
+        const snap = await transaction.get(eventRef);
+        if (!snap.exists())
+            throw new Error("Event not found.");
+        const data = snap.data();
+        transaction.update(eventRef, {
+            "blocks.cards.items": cardItemsWithImage(data, cardId, patch),
+        });
+    });
+}
+function imageVariantReason(ref) {
+    if (!ref.imageMasterUrl && !ref.imageUrl)
+        return "image_missing";
+    if (!ref.imageMasterUrl)
+        return "master_missing";
+    if (!ref.imageVariants)
+        return "variants_pending";
+    if (!ref.imageUrl)
+        return "image_url_pending";
+    return null;
+}
+function imageVariantStatus(eventId, eventData, kind, cardId, elapsedMs) {
+    const ref = readImageRef(eventData, kind, cardId ?? undefined);
+    const reason = imageVariantReason(ref);
+    return {
+        eventId,
+        kind,
+        cardId,
+        imageId: ref.imageId,
+        imageUrl: ref.imageUrl,
+        imageMasterUrl: ref.imageMasterUrl,
+        imageVariants: ref.imageVariants,
+        ready: reason === null,
+        reason,
+        elapsedMs,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForImageVariantTargets(uid, eventId, targets, timeoutSec) {
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutSec * 1000;
+    let latest = targets.map((target) => ({
+        eventId,
+        kind: target.kind,
+        cardId: target.cardId,
+        imageId: target.cardId,
+        imageUrl: null,
+        imageMasterUrl: null,
+        imageVariants: null,
+        ready: false,
+        reason: "not_checked",
+        elapsedMs: 0,
+    }));
+    while (true) {
+        const elapsedMs = Date.now() - startedAt;
+        const event = await readEvent(eventId, uid, "read");
+        latest = targets.map((target) => imageVariantStatus(eventId, event, target.kind, target.cardId, elapsedMs));
+        if (latest.every((item) => item.ready) || Date.now() >= deadline)
+            return latest;
+        await sleep(Math.min(2000, Math.max(250, deadline - Date.now())));
+    }
+}
+async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
+    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);
+        if (kind === "promoBanner") {
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.promoBanner.imageMasterUrl": masterUrl,
+                "blocks.promoBanner.imageUrl": masterUrl,
+                "blocks.promoBanner.imageVariants": null,
+            });
+        }
+        else if (kind === "videoPlaceholder") {
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.video.placeholder.imageMasterUrl": masterUrl,
+                "blocks.video.placeholder.imageUrl": masterUrl,
+                "blocks.video.placeholder.imageVariants": null,
+            });
+        }
+        else {
+            await updateCardImageInTransaction(eventId, cardId, {
+                imageUrl: masterUrl,
+                imageMasterUrl: masterUrl,
+                imageVariants: null,
+            });
+        }
+    }
+    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 {
+        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,
+    };
+}
 async function authed(scopes) {
     return ensureAuth(scopes);
 }
@@ -763,6 +930,145 @@ async function readEvent(eventId, uid, mode = "read") {
         assertEventReadable(data, uid);
     return data;
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function validateEventSetup(eventId, event) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    const add = (target, code, path, message) => {
+        target.push({ code, path, message });
+    };
+    const blocks = asRecord(event.blocks);
+    const forms = Array.isArray(event.forms) ? event.forms.filter((item) => item && typeof item === "object") : [];
+    const formIds = eventFormIds(event);
+    const title = safeString(event.title).trim();
+    if (!title)
+        add(errors, "title_missing", "title", "Event title is required.");
+    const video = asRecord(event.video);
+    if (!safeString(video.embedUrl).trim()) {
+        add(warnings, "video_missing", "video.embedUrl", "No normalized video URL is configured.");
+    }
+    const meta = asRecord(event.meta);
+    const eventDateMs = toMillis(meta.eventDate);
+    if (eventDateMs == null) {
+        add(suggestions, "date_missing", "meta.eventDate", "Add the webinar date/time if it is known.");
+    }
+    else if (eventDateMs < Date.now() - 60 * 60 * 1000) {
+        add(warnings, "date_in_past", "meta.eventDate", "Configured webinar date appears to be in the past.");
+    }
+    const duplicateFormIds = new Set();
+    const seenFormIds = new Set();
+    forms.forEach((form, index) => {
+        const id = safeString(form.id).trim();
+        if (!id)
+            add(errors, "form_id_missing", `forms[${index}].id`, "Every form must have a stable id.");
+        else if (seenFormIds.has(id))
+            duplicateFormIds.add(id);
+        else
+            seenFormIds.add(id);
+        const fields = Array.isArray(form.fields) ? form.fields : [];
+        if (fields.length === 0)
+            add(warnings, "form_fields_missing", `forms[${index}].fields`, "Lead form has no fields.");
+    });
+    for (const id of duplicateFormIds)
+        add(errors, "form_id_duplicate", "forms", `Duplicate form id: ${id}.`);
+    const checkFormBinding = (path, formId) => {
+        const id = safeString(formId).trim();
+        if (id && !formIds.has(id))
+            add(errors, "form_binding_missing", path, `Referenced formId "${id}" does not exist in event.forms.`);
+    };
+    const promo = asRecord(blocks.promoBanner);
+    if (promo.enabled === true) {
+        checkFormBinding("blocks.promoBanner.formId", promo.formId);
+        if (!safeString(promo.link).trim() && !safeString(promo.formId).trim()) {
+            add(suggestions, "promo_target_missing", "blocks.promoBanner", "Enabled promo banner has no link or form binding.");
+        }
+        if (!safeString(promo.imageUrl).trim()) {
+            add(warnings, "promo_image_missing", "blocks.promoBanner.imageUrl", "Enabled promo banner has no image.");
+        }
+        else if (safeString(promo.imageMasterUrl).trim() && !readImageVariants(promo.imageVariants)) {
+            add(warnings, "promo_variants_pending", "blocks.promoBanner.imageVariants", "Promo banner image variants are not ready yet.");
+        }
+    }
+    const cta = asRecord(blocks.primaryCta);
+    if (cta.enabled === true) {
+        checkFormBinding("blocks.primaryCta.formId", cta.formId);
+        if (!safeString(cta.title).trim() && !safeString(cta.text).trim()) {
+            add(suggestions, "cta_copy_missing", "blocks.primaryCta", "Enabled CTA has no title or text.");
+        }
+        if (!safeString(cta.buttonLabel).trim()) {
+            add(warnings, "cta_button_missing", "blocks.primaryCta.buttonLabel", "Enabled CTA has no button label.");
+        }
+        if (safeString(cta.buttonLabel).trim() && !safeString(cta.buttonUrl).trim() && !safeString(cta.formId).trim()) {
+            add(warnings, "cta_target_missing", "blocks.primaryCta", "CTA button has no URL or form binding.");
+        }
+    }
+    const videoPlaceholder = asRecord(asRecord(blocks.video).placeholder);
+    if (videoPlaceholder.enabled === true && videoPlaceholder.mode === "image") {
+        if (!safeString(videoPlaceholder.imageUrl).trim()) {
+            add(warnings, "placeholder_image_missing", "blocks.video.placeholder.imageUrl", "Image placeholder mode is enabled but no image is configured.");
+        }
+        else if (safeString(videoPlaceholder.imageMasterUrl).trim() && !readImageVariants(videoPlaceholder.imageVariants)) {
+            add(warnings, "placeholder_variants_pending", "blocks.video.placeholder.imageVariants", "Video placeholder image variants are not ready yet.");
+        }
+    }
+    const cards = readCardsConfig(event);
+    if (cards.enabled) {
+        if (cards.items.length === 0)
+            add(warnings, "cards_empty", "blocks.cards.items", "Cards block is enabled but has no cards.");
+        const cardIds = new Set();
+        cards.items.forEach((card, index) => {
+            const path = `blocks.cards.items[${index}]`;
+            if (cardIds.has(card.id))
+                add(errors, "card_id_duplicate", `${path}.id`, `Duplicate card id: ${card.id}.`);
+            cardIds.add(card.id);
+            if (!card.title && !card.text)
+                add(suggestions, "card_copy_missing", path, "Card has no title or text.");
+            if (card.buttonLabel && !card.buttonUrl && !card.formId)
+                add(warnings, "card_target_missing", path, "Card button has no URL or form binding.");
+            if (card.formId && !formIds.has(card.formId))
+                add(errors, "card_form_missing", `${path}.formId`, `Referenced formId "${card.formId}" does not exist.`);
+            if (card.imageMasterUrl && !card.imageVariants)
+                add(warnings, "card_variants_pending", `${path}.imageVariants`, "Card image variants are not ready yet.");
+        });
+    }
+    const telegram = asRecord(event.telegram);
+    const telegramChannels = Array.isArray(telegram.channelIds) ? telegram.channelIds : [];
+    if (telegram.enabled === true && telegramChannels.length === 0 && typeof telegram.channelId !== "number") {
+        add(warnings, "telegram_channel_missing", "telegram.channelIds", "Telegram is enabled but no channel is configured.");
+    }
+    if (event.nmoMode === true) {
+        const criteria = asRecord(event.nmoCriteria);
+        const watch = typeof criteria.minWatchTimeRatio === "number" ? criteria.minWatchTimeRatio : 0.8;
+        const checkpoints = typeof criteria.minCheckpointRatio === "number" ? criteria.minCheckpointRatio : 0.8;
+        if (watch < 0 || watch > 1 || checkpoints < 0 || checkpoints > 1) {
+            add(errors, "nmo_criteria_invalid", "nmoCriteria", "NMO criteria ratios must be between 0 and 1.");
+        }
+        const participantUids = Array.isArray(event.participantUids) ? event.participantUids : [];
+        if (participantUids.length === 0) {
+            add(warnings, "nmo_participants_missing", "participantUids", "NMO mode is enabled but no participants are registered yet.");
+        }
+    }
+    const nextActions = [
+        ...errors.map((item) => `Fix error: ${item.message}`),
+        ...warnings.slice(0, 5).map((item) => `Review warning: ${item.message}`),
+    ];
+    if (nextActions.length === 0)
+        nextActions.push("No blocking setup issues found.");
+    const penalty = errors.length * 25 + warnings.length * 8 + suggestions.length * 2;
+    return {
+        eventId,
+        ok: errors.length === 0,
+        score: Math.max(0, Math.min(100, 100 - penalty)),
+        errors,
+        warnings,
+        suggestions,
+        nextActions,
+        links: eventLinks(eventId, event),
+    };
+}
 function canEditEventWithPermissions(perms) {
     return perms.editSetup === true || perms.controlLive === true || perms.startSession === true;
 }
@@ -1618,6 +1924,26 @@ export function registerTools(server) {
         const data = await readEvent(eventId, uid, "read");
         return textResult({ id: eventId, ...serialize(data), ...eventLinks(eventId, data) });
     });
+    server.registerTool("oko_validate_event_setup", {
+        title: "Validate event setup",
+        description: toolDescription({
+            summary: "Run a read-only setup readiness lint for one OKO event.",
+            args: ["eventId: OKO event document id."],
+            returns: "ok flag, score, errors, warnings, suggestions, next actions, and useful links.",
+            examples: [
+                "Use after creating/configuring a webinar and before telling the organizer it is ready.",
+                "Use before live-session prep to catch missing video, pending image variants, invalid form bindings, or NMO participant gaps.",
+            ],
+            notes: ["This tool does not modify the event and does not start/end analytics sessions."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: setupValidationOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:read"]);
+        const data = await readEvent(eventId, uid, "read");
+        return textResult(validateEventSetup(eventId, data));
+    });
     server.registerTool("oko_create_webinar", {
         title: "Create webinar",
         description: toolDescription({
@@ -1944,72 +2270,89 @@ export function registerTools(server) {
         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(await uploadEventImageForUser(uid, eventId, kind, cardId, source));
+    });
+    server.registerTool("oko_upload_card_images_batch", {
+        title: "Upload card images batch",
+        description: toolDescription({
+            summary: "Upload images for multiple existing cards, preserving card metadata with Firestore transactions and waiting for generated variants.",
+            args: [
+                "eventId: event to edit.",
+                "images: 1-6 card image uploads. Each cardId must already exist in blocks.cards.items.",
+                "timeoutSec: max wait for all CF-generated image variants, default 60 seconds.",
+            ],
+            returns: "eventId, per-card upload details, per-card variant readiness, ready flag, and warnings.",
+            examples: [
+                "Use after oko_configure_cards has returned stable card ids.",
+                "Use for webinar cards where an agent generated several local images and needs to attach all of them.",
+            ],
+            notes: [
+                "This is a workflow tool for cards only. Use oko_upload_image for promoBanner or videoPlaceholder.",
+                "The tool does not create cards; it only attaches images to existing cards.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            images: z.array(z.object({
+                cardId: cardIdSchema.describe("Existing card id."),
+                source: imageSourceSchema.describe("Image source for this card."),
+            }).strict()).min(1).max(MAX_CARD_ITEMS).describe("Card images to upload."),
+            timeoutSec: z.number().int().min(1).max(120).default(60).describe("Maximum seconds to wait for all generated variants."),
+        },
+        outputSchema: cardImagesBatchOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, images, timeoutSec }) => {
+        const { uid } = await authed(["setup:write"]);
+        const uploads = [];
+        for (const image of images) {
+            uploads.push(await uploadEventImageForUser(uid, eventId, "card", image.cardId, image.source));
         }
+        const variants = await waitForImageVariantTargets(uid, eventId, images.map((image) => ({ kind: "card", cardId: image.cardId })), timeoutSec);
+        const warnings = variants
+            .filter((item) => !item.ready)
+            .map((item) => `Card ${item.cardId ?? "unknown"} variants are not ready yet: ${item.reason ?? "unknown"}.`);
         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,
+            uploads,
+            variants,
+            ready: variants.every((item) => item.ready),
+            warnings,
         });
     });
+    server.registerTool("oko_wait_for_image_variants", {
+        title: "Wait for image variants",
+        description: toolDescription({
+            summary: "Poll an event image slot until Cloud Function generated thumb/card/hero variants are visible in Firestore.",
+            args: [
+                "eventId: event to inspect.",
+                "kind: promoBanner, videoPlaceholder, or card.",
+                "cardId: required when kind=card.",
+                "timeoutSec: max wait, default 60 seconds.",
+            ],
+            returns: "image URLs, imageVariants, ready flag, pending reason, and elapsed time.",
+            examples: ["Use after oko_upload_image to avoid checking the UI before image variants are ready."],
+            notes: ["Read-only. It does not trigger variant generation; it only waits for CF4's Firestore update."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            kind: z.enum(IMAGE_KINDS).describe("Target image slot."),
+            cardId: z.string().min(1).optional().describe("Required when kind=card."),
+            timeoutSec: z.number().int().min(1).max(120).default(60).describe("Maximum seconds to wait."),
+        },
+        outputSchema: imageVariantsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, kind, cardId, timeoutSec }) => {
+        const { uid } = await authed(["events:read"]);
+        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 statuses = await waitForImageVariantTargets(uid, eventId, [{ kind, cardId: cardId ?? null }], timeoutSec);
+        const status = statuses[0];
+        if (!status)
+            throw new Error("Image variant status was not produced.");
+        return textResult(status);
+    });
     server.registerTool("oko_delete_image", {
         title: "Delete event image",
         description: toolDescription({
@@ -2042,25 +2385,27 @@ export function registerTools(server) {
         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();
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.promoBanner.imageMasterUrl": deleteField(),
+                "blocks.promoBanner.imageUrl": deleteField(),
+                "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();
+            await updateDoc(doc(firestore, "events", eventId), {
+                "blocks.video.placeholder.imageMasterUrl": deleteField(),
+                "blocks.video.placeholder.imageUrl": deleteField(),
+                "blocks.video.placeholder.imageVariants": deleteField(),
+            });
         }
         else {
-            patch["blocks.cards.items"] = cardItemsWithImage(event, cardId, {
+            await updateCardImageInTransaction(eventId, cardId, {
                 imageUrl: null,
                 imageMasterUrl: null,
                 imageVariants: null,
             });
         }
-        await updateDoc(doc(firestore, "events", eventId), patch);
         return textResult({
             eventId,
             kind,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",
@@ -21,7 +21,7 @@
     "oko-mcp": "dist/server.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"require('node:fs').chmodSync('dist/server.js', 0o755)\"",
     "prepublishOnly": "npm run build",
     "start": "node dist/server.js"
   },