@okostream/mcp 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.5.3 - 2026-07-10
+
+- Added an explicit product model: OKO wraps an organizer-supplied video player and does not host or start the underlying stream.
+- Added `oko://guide/nmo` and `oko://guide/telegram` for the complete NMO/CME and Telegram claim/publication workflows.
+- Documented form-button precedence, MCP product boundaries, and the Telegram auto-reminder limitation.
+- Updated the README and companion skill, and added protocol coverage for all seven onboarding resources.
+
+## 0.5.2 - 2026-07-10
+
+- Fixed webinar create/duplicate output schemas so successful writes cannot be reported as protocol failures.
+- Made Firestore event creation compensate automatically when the required RTDB mirror fails.
+- Removed a stale RTDB mirror rewrite from metadata updates.
+- Routed event deletion through an authorized server callable that cleans Firestore subcollections, both RTDB instances, Storage, participants, active sessions, and scheduled Telegram posts.
+- Added a repeatable production smoke workflow against an exact published npm version.
+
 ## 0.5.1 - 2026-07-10
 
 - Replaced hand-maintained remote-image IP ranges with a tested public-unicast policy covering IPv4, IPv6, mapped, reserved, documentation, benchmark, multicast, and private address classes.

package/README.md

@@ -52,6 +52,10 @@ OKO_IMAGE_ROOTS=/trusted/assets:/another/trusted/folder
 
 Node.js 20.18.1 or newer is required.
 
+## What OKO Does
+
+OKO is a webinar experience and operations layer, not a video-streaming host. The organizer supplies a YouTube, iframe, or other player URL; OKO adds the event page, configurable audience blocks, chat, analytics, and NMO attendance controls around it. Start/End tools control analytics sessions only, never the underlying video stream.
+
 ## Security Model
 
 - Each API key exchanges into its own Firebase identity `mcp_<keyId>`; it never inherits platform-owner claims from the organizer account.
@@ -78,7 +82,7 @@ Every tool returns JSON text plus MCP `structuredContent`. List-like tools use b
 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`.
+- Resources: `oko://guide/create-webinar`, `oko://guide/platform`, `oko://guide/security`, `oko://guide/nmo`, `oko://schema/event`, `oko://guide/telegram`, `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.
@@ -157,7 +161,7 @@ Dangerous or external side-effect tools require `confirm: true`.
 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.
+13. MCP protocol smoke should report 59 tools, 7 resources, 3 prompts, and non-empty initialize instructions.
 
 CLI help:
 

package/dist/guides.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 export const OKO_MCP_INSTRUCTIONS = [
     "You are controlling OKO Stream as an organizer through MCP tools.",
+    "OKO is a webinar experience and operations layer, not a video-streaming host. The organizer supplies a YouTube, iframe, or other player URL; OKO adds the event page, audience blocks, chat, analytics, and NMO attendance controls around it.",
+    "Use the source player or encoder to start video. In OKO, Start and End manage analytics sessions only, while blocks and chat control the attendee experience around the supplied video.",
     "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.",
@@ -41,6 +43,9 @@ const GUIDE_RESOURCES = [
         text: [
             "# OKO Platform Invariants",
             "",
+            "## Product model",
+            "OKO does not host or encode video. An organizer brings a video source such as YouTube or an iframe player. OKO builds the webinar experience around that source: an event page, configurable blocks, cards, forms, chat, analytics, and NMO attendance controls. Starting the source video happens outside OKO; starting an OKO session starts analytics only.",
+            "",
             "- 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.",
@@ -50,6 +55,33 @@ const GUIDE_RESOURCES = [
             "- Image variants are asynchronous. A master upload is not fully ready until `imageVariants` are present.",
         ].join("\n"),
     },
+    {
+        name: "oko_mcp_nmo",
+        uri: "oko://guide/nmo",
+        title: "Run an NMO / CME Webinar",
+        description: "Complete organizer workflow for NMO participants, checkpoints, and technical attendance results.",
+        text: [
+            "# Run an NMO / CME Webinar",
+            "",
+            "NMO mode is for attendance-controlled medical education webinars. OKO records technical eligibility from watch-time and checkpoint ratios; the organizer remains responsible for the formal accreditation process and participant communications.",
+            "",
+            "## Prepare",
+            "1. Create the event with its video source, then call `oko_configure_blocks` with `nmo.enabled:true`, watch-time and checkpoint criteria, and optional position/organization fields.",
+            "2. Add approved participants with `oko_add_nmo_participant` or bulk-import them with `oko_import_nmo_participants`. Inspect per-row import failures before continuing.",
+            "3. Return the event's registration and login links to participants. NMO access is gated by the imported participant list.",
+            "4. Call `oko_validate_event_setup`; an NMO event without participants or valid criteria is not ready.",
+            "",
+            "## During the webinar",
+            "1. Call `oko_start_session` when attendance analytics should begin. This does not start the supplied video stream.",
+            "2. At the organizer's explicit request, call `oko_launch_checkpoint` with `confirm:true`, then call `oko_close_checkpoint` with fresh confirmation when the response window must close.",
+            "3. Use `oko_get_live_state` and participant/analytics reads to monitor the live session. Never launch or close a checkpoint silently.",
+            "",
+            "## After the webinar",
+            "1. End the analytics session only after explicit organizer confirmation.",
+            "2. Use `oko_get_session_report` or `oko_get_analytics` with NMO rows when detailed technical attendance results are needed.",
+            "3. Report watch-time and checkpoint results as technical OKO evidence. Do not promise an official credit or certificate unless the organizer's accreditation process confirms it.",
+        ].join("\n"),
+    },
     {
         name: "oko_mcp_security",
         uri: "oko://guide/security",
@@ -109,9 +141,36 @@ const GUIDE_RESOURCES = [
             "- `nmoMode`, `nmoCriteria`, `participantUids`: NMO mode and participant gates.",
             "- `workspaceId` plus capability arrays (`accessibleBy`, `editors`, `deleters`, `liveControllers`, `chatModerators`, `sessionManagers`, `analyticsViewers`, `reportDownloaders`, `notificationSenders`) are Admin-owned access mirrors.",
             "",
+            "## Button targets and forms",
+            "A `formId` on a CTA, banner, or card button opens that event-level lead form in a popup instead of navigating away. Use `buttonUrl` only when the button should navigate to a URL. Although legacy data can contain both, set exactly one target in new MCP writes; `formId` takes precedence in the attendee UI.",
+            "",
             "Do not remove unknown fields or write access mirrors. Use dedicated MCP tools instead of whole-document rewrites.",
         ].join("\n"),
     },
+    {
+        name: "oko_mcp_telegram",
+        uri: "oko://guide/telegram",
+        title: "Connect Telegram and Publish Webinar Posts",
+        description: "Claim a Telegram channel, connect it to an event, and publish or schedule posts safely.",
+        text: [
+            "# Connect Telegram and Publish Webinar Posts",
+            "",
+            "## Claim a channel",
+            "1. Add `@OKOStreamBot` to the Telegram channel as an administrator with permission to post.",
+            "2. The bot provides a claim code for that channel. Copy it exactly; do not invent a channel ID.",
+            "3. Call `oko_claim_telegram_channel` with the claim code, optional workspace ids, and `confirm:true`.",
+            "4. Call `oko_list_telegram_channels` and choose a channel by its returned title and id.",
+            "5. Call `oko_configure_blocks` with `telegramChannelIds` to connect the claimed channel to an event.",
+            "",
+            "## Publish safely",
+            "1. Use `oko_publish_telegram_post` with the event id, returned channel id, caption, optional image/button, and `confirm:true`.",
+            "2. Include `scheduleAt` for a scheduled post. Without it, the tool sends immediately to the real channel, so show the exact channel and caption before confirmation.",
+            "3. Use `oko_list_telegram_posts` to inspect draft, scheduled, sent, or failed posts. Only cancel draft, scheduled, or failed posts with `oko_cancel_telegram_post` and `confirm:true`.",
+            "",
+            "## Automatic reminders",
+            "OKO has a platform auto-reminder job for opted-in events. The current MCP surface does not toggle `telegram.autoReminder`, so an MCP-only workflow should create a scheduled reminder post explicitly. Use the web setup if the organizer specifically needs the platform auto-reminder setting.",
+        ].join("\n"),
+    },
     {
         name: "oko_mcp_capabilities",
         uri: "oko://capabilities",
@@ -134,6 +193,12 @@ const GUIDE_RESOURCES = [
             "- 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.",
+            "",
+            "## Outside the MCP boundary",
+            "- OKO MCP does not host, encode, start, or stop the underlying video stream; configure that in the source player or encoder.",
+            "- It does not create organizer accounts, manage pricing or payments, or expose arbitrary Firebase administration.",
+            "- It does not provide a general theme designer. Use the web product or support for platform-level branding and account administration.",
+            "- It does not currently toggle the platform's Telegram auto-reminder setting; schedule a post or use the web setup instead.",
         ].join("\n"),
     },
 ];

package/dist/server.js

@@ -23,7 +23,7 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.5.1",
+    version: "0.5.3",
 }, {
     instructions: OKO_MCP_INSTRUCTIONS,
 });

package/dist/tools.js

@@ -77,11 +77,21 @@ const updateOutputSchema = z.object({
     eventId: z.string().optional(),
     updated: z.array(z.string()).optional(),
 }).passthrough();
-const createWebinarOutputSchema = {
-    id: z.string(),
+const eventLinksOutputShape = {
     url: z.string().url(),
-    workspaceId: z.string(),
+    setupUrl: z.string().url(),
+    analyticsUrl: z.string().url(),
+    registrationUrl: z.string().url(),
+    loginUrl: z.string().url(),
+    nmoRegistrationUrl: z.string().url().optional(),
+    nmoLoginUrl: z.string().url().optional(),
 };
+const createWebinarOutputSchema = z.object({
+    id: z.string(),
+    workspaceId: z.string(),
+    sourceEventId: z.string().optional(),
+    ...eventLinksOutputShape,
+}).passthrough();
 const cursorMetaSchema = {
     count: z.number().int().nonnegative(),
     limit: z.number().int().positive(),
@@ -100,7 +110,7 @@ const eventsOutputSchema = z.object({
 }).passthrough();
 const eventOutputSchema = z.object({
     id: z.string(),
-    url: z.string().url(),
+    ...eventLinksOutputShape,
 }).passthrough();
 const liveStateOutputSchema = z.object({
     eventId: z.string(),
@@ -1099,6 +1109,22 @@ function initialEventAccess(uid) {
         notificationSenders: [uid],
     };
 }
+async function addEventWithRtdbMirror(uid, workspaceId, eventData) {
+    const eventRef = await addDoc(collection(firestore, "events"), eventData);
+    try {
+        await update(ref(rtdb, `events/${eventRef.id}`), { ownerId: uid, workspaceId });
+    }
+    catch (error) {
+        try {
+            await deleteDoc(eventRef);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `RTDB mirror failed for event ${eventRef.id}, and Firestore rollback also failed.`);
+        }
+        throw error;
+    }
+    return eventRef;
+}
 async function assertCanCreateInWorkspace(uid, workspaceId) {
     if (workspaceId === uid)
         return;
@@ -2040,7 +2066,7 @@ export function registerTools(server) {
         const workspaceId = args.workspaceId ?? uid;
         await assertCanCreateInWorkspace(uid, workspaceId);
         const video = normalizeVideo(args.videoUrl);
-        const docRef = await addDoc(collection(firestore, "events"), {
+        const docRef = await addEventWithRtdbMirror(uid, workspaceId, {
             ownerId: uid,
             workspaceId,
             ...initialEventAccess(uid),
@@ -2058,10 +2084,6 @@ export function registerTools(server) {
                 promoBanner: { enabled: false, text: "", link: "", visibility: "always" },
             },
         });
-        await update(ref(rtdb, `events/${docRef.id}`), {
-            ownerId: uid,
-            workspaceId,
-        });
         return textResult({ id: docRef.id, ...eventLinks(docRef.id), workspaceId });
     });
     server.registerTool("oko_update_event", {
@@ -2096,7 +2118,7 @@ export function registerTools(server) {
         if (requiredScopes.size === 0)
             throw new Error("Provide at least one field to update.");
         const { uid } = await authed([...requiredScopes]);
-        const data = await readEvent(args.eventId, uid, "edit");
+        await readEvent(args.eventId, uid, "edit");
         const patch = {};
         if (args.title !== undefined)
             patch.title = args.title.trim();
@@ -2114,10 +2136,6 @@ export function registerTools(server) {
         if (args.pinned !== undefined)
             patch.pinned = args.pinned;
         await updateDoc(doc(firestore, "events", args.eventId), patch);
-        await update(ref(rtdb, `events/${args.eventId}`), {
-            ownerId: safeString(data.ownerId, uid),
-            workspaceId: safeString(data.workspaceId, uid),
-        });
         return textResult({ id: args.eventId, updated: Object.keys(patch) });
     });
     server.registerTool("oko_configure_blocks", {
@@ -2499,11 +2517,11 @@ export function registerTools(server) {
     server.registerTool("oko_delete_event", {
         title: "Delete event",
         description: toolDescription({
-            summary: "Delete an OKO event document.",
+            summary: "Delete an OKO event and its associated Firestore, RTDB, chat, Storage, participant, and scheduled-post data.",
             args: ["eventId: event to delete.", "confirm: must be true."],
-            returns: "deleted event id.",
+            returns: "deleted event id and cross-store cleanup counts.",
             examples: ["Use only after the user explicitly confirms the exact event title/id."],
-            notes: ["Destructive. Does not control stream state; it deletes the event record."],
+            notes: ["Destructive. The server validates the current per-event delete capability and performs idempotent cross-store cleanup."],
         }),
         inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true for deletion.") },
         outputSchema: z.object({ deleted: z.string() }).passthrough(),
@@ -2512,8 +2530,9 @@ export function registerTools(server) {
         const { uid } = await authed(["events:delete"]);
         const data = await readEvent(eventId, uid, "delete");
         requireConfirm(confirm, "oko_delete_event", { eventId, title: data.title });
-        await deleteDoc(doc(firestore, "events", eventId));
-        return textResult({ deleted: eventId });
+        const deleteEvent = httpsCallable(functions, "deleteEventCompletely");
+        const result = await deleteEvent({ eventId });
+        return textResult(result.data);
     });
     server.registerTool("oko_duplicate_event", {
         title: "Duplicate event",
@@ -2535,7 +2554,7 @@ export function registerTools(server) {
         const source = await readEvent(eventId, uid, "read");
         const workspaceId = targetWorkspaceId ?? safeString(source.workspaceId, uid);
         await assertCanCreateInWorkspace(uid, workspaceId);
-        const newRef = await addDoc(collection(firestore, "events"), {
+        const newRef = await addEventWithRtdbMirror(uid, workspaceId, {
             ownerId: uid,
             workspaceId,
             ...initialEventAccess(uid),
@@ -2551,7 +2570,6 @@ export function registerTools(server) {
             ...(source.nmoCriteria && typeof source.nmoCriteria === "object" ? { nmoCriteria: source.nmoCriteria } : {}),
             ...(source.nmoExtraFields && typeof source.nmoExtraFields === "object" ? { nmoExtraFields: source.nmoExtraFields } : {}),
         });
-        await update(ref(rtdb, `events/${newRef.id}`), { ownerId: uid, workspaceId });
         return textResult({ id: newRef.id, sourceEventId: eventId, workspaceId, ...eventLinks(newRef.id) });
     });
     server.registerTool("oko_move_event", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",
@@ -26,6 +26,7 @@
     "test": "npm run build && node --test test/*.test.mjs",
     "eval:contract": "npm run build && node eval/contract-eval.mjs",
     "eval:model": "npm run build && node eval/model-eval.mjs",
+    "smoke:prod": "node eval/prod-smoke.mjs",
     "prepublishOnly": "npm run build",
     "start": "node dist/server.js"
   },