@okostream/mcp 0.12.3 → 0.12.4

package/dist/server.js

@@ -116223,7 +116223,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.12.3";
+var OKO_MCP_VERSION = "0.12.4";
 
 // build/auth.js
 var state = null;
@@ -116518,6 +116518,11 @@ async function readEvent(eventId, uid, mode = "read") {
 
 // build/tools/imagePipeline.js
 var IMAGE_KINDS = ["promoBanner", "videoPlaceholder", "card"];
+var IMAGE_ADVICE = {
+  promoBanner: "Banner advice: a wide landscape image at least 1600 px wide (3:1 to 5:1 works best, for example 1600\xD7400); keep text inside the middle 80% so it survives mobile scaling; JPEG/PNG/WebP/AVIF up to 15 MB, stored as WebP with 320/800/1600 px variants.",
+  videoPlaceholder: "Placeholder advice: it covers the 16:9 video slot, so use a 16:9 image at least 1600\xD7900 px; avoid small text; JPEG/PNG/WebP/AVIF up to 15 MB, stored as WebP with 320/800/1600 px variants.",
+  card: "Card advice: match the cardImageRatio chosen in oko_configure_cards (1:1 is the safest), at least 800 px on the short side; JPEG/PNG/WebP/AVIF up to 15 MB, stored as WebP with 320/800/1600 px variants."
+};
 var IMAGE_VARIANT_NAMES = ["thumb_320.webp", "card_800.webp", "hero_1600.webp"];
 var CARD_IMAGE_RATIOS = ["auto", "1:1", "4:3", "3:2", "16:9", "2:3", "3:4"];
 var CARD_ID_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
@@ -117004,6 +117009,16 @@ async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
   const previous = readImageRef(event, kind, cardId);
   const sourceBuffer = await readImageSource(source);
   const remoteNotes = takeRemoteFetchNotes();
+  const eventBlocks = event.blocks && typeof event.blocks === "object" ? event.blocks : {};
+  const placeholderCfg = eventBlocks.video?.placeholder && typeof eventBlocks.video.placeholder === "object" ? eventBlocks.video.placeholder : {};
+  const blockEnabled = kind === "promoBanner" ? eventBlocks.promoBanner?.enabled === true : kind === "videoPlaceholder" ? placeholderCfg.enabled === true : readCardsConfig(event).enabled;
+  const enableInstruction = kind === "promoBanner" ? "oko_configure_blocks promoBanner.enabled=true" : kind === "videoPlaceholder" ? "oko_configure_blocks videoPlaceholder.enabled=true" : "oko_configure_cards enabled=true";
+  const uploadHints = [
+    blockEnabled ? `The ${kind} block is enabled: the new image appears on the page as soon as the variants are ready.` : `The ${kind} block is disabled in setup, so viewers will not see this image until it is enabled (${enableInstruction}). Uploading never enables a block by itself.`,
+    ...kind === "videoPlaceholder" && placeholderCfg.mode !== "image" ? ['The placeholder mode is not "image": set oko_configure_blocks videoPlaceholder.mode="image" for this picture to be used.'] : [],
+    ...kind === "videoPlaceholder" ? ['The placeholder is shown to viewers only while its live switch is on: oko_set_block_visibility block "placeholder" visible=true.'] : [],
+    IMAGE_ADVICE[kind]
+  ];
   const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
   const deleteWarnings = [];
   let deletesAttempted = 0;
@@ -117029,7 +117044,7 @@ async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
     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,
-    ...remoteNotes.length ? { hints: remoteNotes } : {}
+    hints: [...remoteNotes, ...uploadHints]
   };
 }
 
@@ -118086,6 +118101,8 @@ function validateEventSetup(eventId, event) {
     } 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.");
     }
+  } else if (safeString(promo.imageUrl).trim() || safeString(promo.imageMasterUrl).trim()) {
+    add(suggestions, "promo_disabled_with_image", "blocks.promoBanner.enabled", 'Promo banner has an uploaded image but is disabled in setup, so viewers never see it. Enable it with oko_configure_blocks promoBanner.enabled=true; to hide it only during the live show, keep it enabled and use oko_set_block_visibility block "banner" visible=false.');
   }
   const cta = asRecord(blocks.primaryCta);
   if (cta.enabled === true) {
@@ -118108,6 +118125,9 @@ function validateEventSetup(eventId, event) {
       add(warnings, "placeholder_variants_pending", "blocks.video.placeholder.imageVariants", "Video placeholder image variants are not ready yet.");
     }
   }
+  if (videoPlaceholder.enabled === true) {
+    add(suggestions, "placeholder_needs_live_switch", "blocks.video.placeholder", 'The video placeholder is shown to viewers only while its live switch is on: call oko_set_block_visibility block "placeholder" visible=true before the start and visible=false (or null) once the stream is playing.');
+  }
   const cards = readCardsConfig(event);
   cards.repairedIdPositions.forEach((position) => {
     add(errors, "card_id_missing", `blocks.cards.items[${position}].id`, "Card has no usable id in Firestore; its image cannot be matched and will be dropped on the next update.");
@@ -118410,7 +118430,8 @@ function registerEventTools(server2) {
       notes: [
         "A block toggle and its image are independent: enabling a block here works with an image already uploaded via oko_upload_image, and uploading an image never enables the block by itself.",
         "promoBanner has no text field by design: the banner is image+link. blocks.promoBanner.text seen in event documents is legacy and is never rendered on the event page.",
-        'videoPlaceholder.enabled only allows the placeholder; viewers see it after oko_set_block_visibility with block "placeholder" and visible true (a live override, stored outside the event document). Chat, CTA, banner and cards appear as soon as they are enabled here.'
+        'videoPlaceholder.enabled only allows the placeholder; viewers see it after oko_set_block_visibility with block "placeholder" and visible true (a live override, stored outside the event document). Chat, CTA, banner and cards appear as soon as they are enabled here.',
+        "Setup toggle vs live override: enabled=false removes a block from the page for everyone and persists (its uploaded image stays); oko_set_block_visibility hides or shows an enabled block temporarily and is the tool for the live show. Uploading an image never enables a block."
       ]
     }),
     inputSchema: {
@@ -118498,6 +118519,17 @@ function registerEventTools(server2) {
     }
     await updateDoc(doc(firestore, "events", args.eventId), patch);
     const hints = [];
+    const currentBlocks = current.blocks && typeof current.blocks === "object" ? current.blocks : {};
+    const bannerHasImage = Boolean(safeString(currentBlocks.promoBanner?.imageUrl) || safeString(currentBlocks.promoBanner?.imageMasterUrl));
+    if (args.promoBanner?.enabled === false && bannerHasImage) {
+      hints.push('The promo banner is now disabled in setup: it disappears from the page for everyone, while its uploaded image stays in place. If the goal was to hide it only during the live show and bring it back with one call, re-enable it here and use oko_set_block_visibility block "banner" visible=false instead.');
+    }
+    if (args.promoBanner?.enabled === true && !bannerHasImage) {
+      hints.push(`The promo banner is enabled but has no image yet: upload one with oko_upload_image kind "promoBanner". ${IMAGE_ADVICE.promoBanner}`);
+    }
+    if (args.chat?.enabled !== void 0 || args.promoBanner?.enabled !== void 0 || args.primaryCta?.enabled !== void 0 || args.videoPlaceholder?.enabled !== void 0) {
+      hints.push("Setup toggles (enabled) decide whether a block exists on the page and persist; live overrides (oko_set_block_visibility) show or hide an enabled block temporarily during the show. Uploading an image never enables a block.");
+    }
     if (args.videoPlaceholder?.enabled === true) {
       hints.push('The video placeholder is enabled but not yet visible to viewers: call oko_set_block_visibility with block "placeholder" and visible true (confirm true) to show it. It is a live override stored outside the event document.');
     }
@@ -118623,7 +118655,11 @@ function registerImageTools(server2) {
         "Uploading an image does not enable its block: toggle the block independently via oko_configure_blocks, in either order.",
         "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."
+        "For card images, imageId is the cardId so OKO CF4 can update the correct item.",
+        IMAGE_ADVICE.promoBanner,
+        IMAGE_ADVICE.videoPlaceholder,
+        IMAGE_ADVICE.card,
+        "The result carries hints: whether the target block is enabled, what still hides the image (placeholder mode/live switch), and the advice above."
       ]
     }),
     inputSchema: {
@@ -119273,7 +119309,8 @@ function registerLiveTools(server2) {
       returns: "eventId, block, and effective override value.",
       examples: ["Use visible=false to hide the CTA live; use visible=null to return to setup defaults."],
       notes: [
-        "block=chat with visible=false PAUSES message input: viewers keep seeing the chat history but cannot send. It does not hide the chat panel."
+        "block=chat with visible=false PAUSES message input: viewers keep seeing the chat history but cannot send. It does not hide the chat panel.",
+        "Live overrides sit on top of setup: a block disabled in setup (oko_configure_blocks enabled=false) stays absent whatever the override; visible=null returns an enabled block to its setup default. Use overrides for the live show, setup toggles for permanent changes."
       ]
     }),
     inputSchema: {
@@ -119286,8 +119323,17 @@ function registerLiveTools(server2) {
     annotations: idempotentWriteTool
   }, async ({ eventId, block, visible, confirm }) => {
     const { uid } = await authed(["live:control"]);
-    await readEvent(eventId, uid, "live");
+    const event = await readEvent(eventId, uid, "live");
     requireConfirm(confirm, "oko_set_block_visibility", { eventId, block, visible });
+    const setupBlocks = event.blocks && typeof event.blocks === "object" ? event.blocks : {};
+    const setupEnabled = {
+      chat: setupBlocks.chat?.enabled === true,
+      banner: setupBlocks.promoBanner?.enabled === true,
+      cta: setupBlocks.primaryCta?.enabled === true,
+      cards: setupBlocks.cards?.enabled === true,
+      placeholder: setupBlocks.video?.placeholder?.enabled === true
+    };
+    const hints = setupEnabled[block] ? [visible === null ? "Override removed: the block follows its setup visibility again." : `Live override applied on top of setup; visible=null returns the ${block} block to its setup default.`] : [`The ${block} block is disabled in setup, so this live override has no visible effect until it is enabled (${block === "cards" ? "oko_configure_cards enabled=true" : "oko_configure_blocks"}).`];
     const paths = {
       chat: "chatVisible",
       banner: "bannerVisible",
@@ -119309,14 +119355,14 @@ function registerLiveTools(server2) {
           await remove(modeRef);
         await remove(legacyRef);
       }
-      return textResult({ eventId, block, visible });
+      return textResult({ eventId, block, visible, hints });
     }
     const target = ref(rtdb, `events/${eventId}/ctrl/${paths[block]}`);
     if (visible === null)
       await remove(target);
     else
       await set(target, visible);
-    return textResult({ eventId, block, visible });
+    return textResult({ eventId, block, visible, hints });
   });
   server2.registerTool("oko_refresh_viewers", {
     title: "Refresh viewers",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {