@okostream/mcp 0.12.3 → 0.12.5

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.5";
 
 // 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]
   };
 }
 
@@ -117348,7 +117363,7 @@ var SCOPE_UNLOCKS = {
   "chat:moderate": "chat mode, moderation, bans and mutes",
   "telegram:write": "claiming channels and publishing Telegram posts",
   "workspace:read": "listing workspaces, members, invites, notifications",
-  "workspace:write": "workspace management, invites, profile edits, moving events between workspaces",
+  "workspace:write": "workspace management, invites, profile edits",
   "leads:read": "reading and exporting leads"
 };
 function presetsWithScope(scope) {
@@ -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: {
@@ -118855,7 +118891,6 @@ async function recordToolAudit(toolName, outcome, args, startedAt, error3) {
 var REPORT_URL = `${APP_ORIGIN}/contact`;
 var KEYS_URL = `${APP_ORIGIN}/app/mcp`;
 var SCOPE_WORKAROUNDS = {
-  oko_move_event: "Without workspace:write you can still place the event in another workspace: call oko_duplicate_event with targetWorkspaceId to create a copy there. The original stays where it is; live overrides (chat mode, placeholder visibility) are not copied and must be set again on the copy.",
   oko_trash_event: "This key cannot delete events. Tell the organizer which event to remove; they can do it in the OKO cabinet, or create a key with the full preset.",
   oko_delete_event_permanently: "This key cannot delete events. Tell the organizer which event to remove; they can do it in the OKO cabinet, or create a key with the full preset.",
   oko_publish_telegram_post: "This key cannot publish to Telegram. The organizer can publish the announcement from the OKO cabinet, or create a key with the full preset."
@@ -119169,7 +119204,7 @@ function registerLifecycleTools(server2) {
       notes: [
         "Copies title, video, meta, blocks, forms, and Telegram config; does not copy analytics sessions or leads.",
         "Live overrides are NOT copied: the copy starts with chat mode public and the placeholder hidden, whatever the source had. Set them again with oko_set_chat_mode and oko_set_block_visibility on the new event.",
-        "Requires only events:write plus createEvents in the target workspace, so it also works as the way to place an event in another workspace when the key lacks workspace:write for oko_move_event."
+        "Requires only events:write plus createEvents in the target workspace. To move (not copy) an event, use oko_move_event with the same scope."
       ]
     }),
     inputSchema: {
@@ -119222,7 +119257,7 @@ function registerLifecycleTools(server2) {
       examples: ["Use when an event belongs in another workspace. Call oko_list_workspaces first to choose the target."],
       notes: [
         "Reads target workspace shares from Firestore with permissions; does not use RTDB workspaceMembers.",
-        "Requires the workspace:write scope (preset full). Keys with the operator preset cannot move events: use oko_duplicate_event with targetWorkspaceId instead, which creates a copy in the target workspace and leaves the original in place."
+        "Requires events:write plus ownership of the event (or of its source workspace) and createEvents in the target workspace; no workspace:write needed. Live overrides (chat mode, placeholder) travel with the event: they live in the event's own RTDB node."
       ]
     }),
     inputSchema: {
@@ -119233,7 +119268,7 @@ function registerLifecycleTools(server2) {
     outputSchema: updateOutputSchema,
     annotations: writeTool
   }, async ({ eventId, targetWorkspaceId, confirm }) => {
-    await authed(["events:write", "workspace:write"]);
+    await authed(["events:write"]);
     requireConfirm(confirm, "oko_move_event", { eventId, targetWorkspaceId });
     const moveEvent = httpsCallable(functions, "moveEventToWorkspace");
     const result = await moveEvent({ eventId, targetWorkspaceId });
@@ -119273,7 +119308,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 +119322,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 +119354,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.5",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {