@okostream/mcp 0.10.0 → 0.11.0

package/dist/tools.js

@@ -940,7 +940,7 @@ function validateEventSetup(eventId, event) {
         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.");
+        add(warnings, "video_missing", "video.embedUrl", "No normalized video URL is configured. This warning is for the organizer only and never appears as page text above other blocks. Without a video URL the player slot shows a small 'video not configured' notice, but when the video placeholder block is enabled and switched on, the placeholder fully covers that slot and viewers see only the placeholder.");
     }
     const meta = asRecord(event.meta);
     const eventDateMs = toMillis(meta.eventDate);
@@ -1156,6 +1156,35 @@ function timestampCursorFrom(value) {
     const millis = toMillis(value);
     return millis == null ? null : String(millis);
 }
+function parseIsoBound(value, label) {
+    if (value === undefined)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid ${label}: expected an ISO timestamp such as 2026-08-28T00:00:00+03:00.`);
+    }
+    return Timestamp.fromMillis(parsed);
+}
+// Компактная карточка события из полного (сериализованного) документа —
+// той же формы, что grant-проекция в eventAccess.
+function compactEventFromFullDoc(event) {
+    const meta = (event.meta && typeof event.meta === "object" ? event.meta : {});
+    const telegram = (event.telegram && typeof event.telegram === "object" ? event.telegram : {});
+    return {
+        id: event.id,
+        ownerId: event.ownerId ?? null,
+        workspaceId: event.workspaceId ?? null,
+        title: event.title ?? null,
+        createdAt: event.createdAt ?? null,
+        eventDate: meta.eventDate ?? null,
+        speakerName: meta.speakerName ?? null,
+        pinned: event.pinned === true,
+        telegramEnabled: telegram.enabled === true,
+        trashed: Boolean(event.trashedAt),
+        trashedAt: event.trashedAt ?? null,
+        activeAnalyticsSessionId: event.activeAnalyticsSessionId ?? null,
+    };
+}
 function compactAnalyticsSession(raw, options) {
     const session = serialize(raw);
     const timeline = Array.isArray(session.timeline) ? session.timeline : null;
@@ -1603,24 +1632,40 @@ export function registerTools(server) {
             summary: "List OKO events visible to the authenticated organizer.",
             args: [
                 "limit: maximum events to return, default 30, max 100.",
-                "cursor: timestamp cursor returned as nextCursor by the previous page.",
+                "cursor: pagination cursor returned as nextCursor by the previous page; reuse it with the same filters.",
                 "workspaceId: optional workspace filter.",
+                'detail: "compact" (default) returns the light card projection; "full" returns complete event documents.',
+                "from/to: optional ISO timestamps bounding meta.eventDate; sorting switches to eventDate descending and undated events are excluded.",
             ],
             returns: "events plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
-            examples: ["Use limit=10 first; if hasMore is true, call again with cursor=nextCursor."],
+            examples: [
+                "Use limit=10 first; if hasMore is true, call again with cursor=nextCursor.",
+                'For "today\'s webinar" pass from/to covering the day; use detail="full" only when block contents are needed.',
+            ],
         }),
         inputSchema: {
             limit: limitField(),
             cursor: cursorField,
             workspaceId: z.string().optional().describe("Optional workspace id to filter returned events."),
+            detail: z.enum(["compact", "full"]).default("compact").describe('Response shape: "compact" card projection (default) or "full" event documents.'),
+            from: z.string().optional().describe("Include only events with meta.eventDate at or after this ISO timestamp."),
+            to: z.string().optional().describe("Include only events with meta.eventDate at or before this ISO timestamp."),
         },
         outputSchema: eventsOutputSchema,
         annotations: readOnlyTool,
     }, async (args) => {
         const { uid } = await authed(["events:read"]);
+        const fromTs = parseIsoBound(args.from, "from");
+        const toTs = parseIsoBound(args.to, "to");
+        const dateFiltered = fromTs !== null || toTs !== null;
+        const orderField = dateFiltered ? "eventDate" : "createdAt";
         const constraints = [
-            ...(args.workspaceId ? [where("workspaceId", "==", args.workspaceId)] : []),
-            orderBy("createdAt", "desc"),
+            // При датном фильтре workspaceId отсеивается по загруженной странице:
+            // составного индекса grants(workspaceId+eventDate) нет намеренно.
+            ...(!dateFiltered && args.workspaceId ? [where("workspaceId", "==", args.workspaceId)] : []),
+            ...(fromTs ? [where("eventDate", ">=", fromTs)] : []),
+            ...(toTs ? [where("eventDate", "<=", toTs)] : []),
+            orderBy(orderField, "desc"),
             limit(args.limit + 1),
         ];
         if (args.cursor)
@@ -1632,12 +1677,29 @@ export function registerTools(server) {
         });
         if (snap !== null) {
             const { page, hasMore } = pickPage(snap.docs, args.limit);
-            const eventDocuments = await Promise.all(page.map((item) => (getDoc(doc(firestore, "events", item.id)))));
-            const events = eventDocuments.flatMap((item) => (item.exists()
-                ? [{ id: item.id, ...serialize(item.data()) }]
-                : []));
-            const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().createdAt) : null;
-            return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) });
+            const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data()[orderField]) : null;
+            const pageItems = dateFiltered && args.workspaceId
+                ? page.filter((item) => item.data().workspaceId === args.workspaceId)
+                : page;
+            let events;
+            if (args.detail === "full") {
+                const eventDocuments = await Promise.all(pageItems.map((item) => (getDoc(doc(firestore, "events", item.id)))));
+                events = eventDocuments.flatMap((item) => (item.exists()
+                    ? [{ id: item.id, ...serialize(item.data()) }]
+                    : []));
+            }
+            else {
+                // Компактный режим отдаёт grant-проекцию как есть — без чтения
+                // полных документов событий.
+                events = pageItems.map((item) => {
+                    const data = serialize(item.data());
+                    delete data.schemaVersion;
+                    delete data.uid;
+                    delete data.eventId;
+                    return { id: item.id, ...data };
+                });
+            }
+            return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) }, { truncationHint: 'Use a smaller limit, cursor pagination, or detail="compact".' });
         }
         const legacyConstraints = [
             where("accessibleBy", "array-contains", uid),
@@ -1649,14 +1711,26 @@ export function registerTools(server) {
         }
         const legacySnap = await getDocs(query(collection(firestore, "events"), ...legacyConstraints));
         const { page, hasMore } = pickPage(legacySnap.docs, args.limit);
+        const fromMs = fromTs ? fromTs.toMillis() : null;
+        const toMs = toTs ? toTs.toMillis() : null;
         const events = page
             .map((item) => ({
             id: item.id,
             ...serialize(item.data()),
         }))
-            .filter((event) => !args.workspaceId || event.workspaceId === args.workspaceId);
+            .filter((event) => !args.workspaceId || event.workspaceId === args.workspaceId)
+            .filter((event) => {
+            if (fromMs === null && toMs === null)
+                return true;
+            const meta = (event.meta && typeof event.meta === "object" ? event.meta : {});
+            const ms = typeof meta.eventDate === "string" ? Date.parse(meta.eventDate) : NaN;
+            if (!Number.isFinite(ms))
+                return false;
+            return (fromMs === null || ms >= fromMs) && (toMs === null || ms <= toMs);
+        })
+            .map((event) => (args.detail === "full" ? event : compactEventFromFullDoc(event)));
         const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().createdAt) : null;
-        return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) });
+        return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) }, { truncationHint: 'Use a smaller limit, cursor pagination, or detail="compact".' });
     });
     server.registerTool("oko_get_event", {
         title: "Get event",
@@ -1820,6 +1894,10 @@ export function registerTools(server) {
             ],
             returns: "event id and the list of Firestore fields updated.",
             examples: ["Use after oko_create_webinar to set chat visibility, CTA/form binding, and other audience blocks."],
+            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.",
+            ],
         }),
         inputSchema: {
             eventId: eventIdField,
@@ -2001,6 +2079,7 @@ export function registerTools(server) {
                 'Use kind="card" with cardId after the card item already exists.',
             ],
             notes: [
+                "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.",
@@ -2393,6 +2472,105 @@ export function registerTools(server) {
         await set(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), Date.now());
         return textResult({ eventId, refreshed: true });
     });
+    server.registerTool("oko_set_live_badge", {
+        title: "Set live badge",
+        description: toolDescription({
+            summary: "Control the public 'Live' badge on the event page.",
+            args: [
+                "eventId: event to control.",
+                "mode: session (follows the analytics session, product default), manual (badge shown now for durationMinutes), schedule (shown around meta.eventDate), hidden (never shown).",
+                "durationMinutes: badge window for manual/schedule, 15-1440 minutes, default 120.",
+                "confirm: must be true.",
+            ],
+            returns: "eventId, mode, durationMinutes.",
+            examples: ['Use mode="manual" during an unscheduled stream; return to mode="session" afterwards.'],
+            notes: ["The badge is a page indicator only; it never starts or stops video or analytics."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            mode: z.enum(["session", "manual", "schedule", "hidden"]).describe("Live badge mode."),
+            durationMinutes: z.number().int().min(15).max(1440).optional().describe("Badge window in minutes for manual/schedule modes; default 120."),
+            confirm: z.boolean().optional().describe("Required true to change the public live badge."),
+        },
+        outputSchema: basicEventOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ eventId, mode, durationMinutes, confirm }) => {
+        const { uid } = await authed(["live:control"]);
+        await readEvent(eventId, uid, "live");
+        requireConfirm(confirm, "oko_set_live_badge", { eventId, mode, durationMinutes: durationMinutes ?? null });
+        const value = { mode, durationMinutes: durationMinutes ?? 120 };
+        await set(ref(rtdb, `events/${eventId}/ctrl/liveBadge`), value);
+        return textResult({ eventId, ...value });
+    });
+    server.registerTool("oko_set_chat_mode", {
+        title: "Set chat mode",
+        description: toolDescription({
+            summary: "Set who can send chat messages on the public event page.",
+            args: [
+                "eventId: event to control.",
+                "mode: public (anyone), auth (signed-in viewers only), owner (organizers only), off (input closed, history stays visible), or null to reset to the product default (public).",
+                "confirm: must be true.",
+            ],
+            returns: "eventId and the effective chat mode.",
+            examples: ['Use mode="off" to pause a chat storm; use mode=null or "public" to reopen.'],
+            notes: [
+                'This is the full replacement for the legacy pause via oko_set_block_visibility(block="chat"): prefer oko_set_chat_mode.',
+                "History always stays visible to viewers; mode only gates sending.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            mode: z.enum(["public", "auth", "owner", "off"]).nullable().describe("Chat mode; null resets the override to the default."),
+            confirm: z.boolean().optional().describe("Required true to change the live chat mode."),
+        },
+        outputSchema: basicEventOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ eventId, mode, confirm }) => {
+        const { uid } = await authed(["live:control"]);
+        await readEvent(eventId, uid, "live");
+        requireConfirm(confirm, "oko_set_chat_mode", { eventId, mode });
+        const target = ref(rtdb, `events/${eventId}/ctrl/chatMode`);
+        if (mode === null)
+            await remove(target);
+        else
+            await set(target, mode);
+        return textResult({ eventId, mode });
+    });
+    server.registerTool("oko_force_viewer_reload", {
+        title: "Force viewer reload",
+        description: toolDescription({
+            summary: "Force a hard page reload for every connected viewer (emergency recovery).",
+            args: ["eventId: event whose viewer pages must reload.", "confirm: must be true."],
+            returns: "eventId and reloaded=true.",
+            examples: ["Use only when viewer pages are stuck (broken bundle or state) and oko_refresh_viewers did not help."],
+            notes: [
+                "Server enforces a 120-second cooldown per event; a repeated call returns the seconds left.",
+                "Viewers reload with up to 4 seconds of jitter. Prefer oko_refresh_viewers for ordinary content updates.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            confirm: z.boolean().optional().describe("Required true to hard-reload all viewer pages."),
+        },
+        outputSchema: basicEventOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, confirm }) => {
+        const { uid } = await authed(["live:control"]);
+        await readEvent(eventId, uid, "live");
+        requireConfirm(confirm, "oko_force_viewer_reload", { eventId });
+        const forceReload = httpsCallable(functions, "forceViewerReload");
+        try {
+            await forceReload({ eventId });
+        }
+        catch (error) {
+            const details = error.details;
+            if (typeof details?.retryInSec === "number") {
+                throw new Error(`Force reload is cooling down: retry in ${details.retryInSec} seconds.`);
+            }
+            throw error;
+        }
+        return textResult({ eventId, reloaded: true });
+    });
     server.registerTool("oko_start_session", {
         title: "Start analytics session",
         description: toolDescription({

package/dist/utils.js

@@ -52,7 +52,7 @@ export function textResult(data, options = {}) {
         structuredContent = {
             ...compactForText(structuredContent),
             truncated: true,
-            truncationMessage: `Response JSON exceeded ${maxChars} characters. ${options.truncationHint ?? "Use limit/cursor or narrower include options."}`,
+            truncationMessage: `Response JSON exceeded ${maxChars} characters. ${options.truncationHint ?? "Use a smaller limit or cursor pagination."}`,
         };
     }
     return {

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generateMcpVersion.mjs from mcp/package.json. Do not edit.
-export const OKO_MCP_VERSION = "0.10.0";
+export const OKO_MCP_VERSION = "0.11.0";

package/package.json

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