@okostream/mcp 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.4 - 2026-07-10
+
+- Separated NMO from the standard webinar workflow throughout instructions, resources, prompts, README, and the companion skill.
+- Marked NMO as an unfinished special MVP mode that must only be enabled after an explicit organizer request and limitation disclosure.
+- Documented the current NMO gaps: hardened email-link/strict single-device, checkpoint auto-close, official portal integration, and remaining Sprint 2 UX/automation.
+- Added protocol assertions preventing future onboarding from silently presenting NMO as a normal production-ready webinar option.
+
+## 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.

package/README.md

@@ -52,6 +52,12 @@ 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.
+
+Standard webinars are the default supported workflow. NMO is a separate unfinished MVP mode and must be enabled only on an explicit organizer request after reviewing `oko://guide/nmo`; it is not a normal option inferred from a medical topic or audience.
+
 ## 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 +84,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 +163,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,9 @@
 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.",
+    "Default to a standard webinar. NMO is a separate unfinished MVP mode, not a normal webinar option: never infer or enable it from the audience or topic. Use it only after the organizer explicitly requests NMO and accepts the current limitations in oko://guide/nmo.",
     "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.",
@@ -24,13 +27,14 @@ const GUIDE_RESOURCES = [
             "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.",
+            "4. Call `oko_configure_blocks` for video, forms, CTA, banner, and Telegram 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.",
+            "NMO is not part of this standard workflow. If the organizer explicitly requests the separate NMO MVP mode, read `oko://guide/nmo`, disclose its current limitations, and follow that workflow separately.",
         ].join("\n"),
     },
     {
@@ -41,6 +45,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 +57,41 @@ 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: "NMO Mode (Special MVP Workflow)",
+        description: "Separate unfinished NMO mode: current MVP workflow, limits, participants, checkpoints, and technical results.",
+        text: [
+            "# NMO Mode (Special MVP Workflow)",
+            "",
+            "NMO is a separate, unfinished MVP mode for attendance-controlled medical education webinars. It is not part of a standard OKO webinar and must never be enabled because the audience happens to be doctors or the topic is medical. Proceed only when the organizer explicitly requests NMO and understands the limitations below.",
+            "",
+            "## Current limits",
+            "- The hardened email-link login and strict instant single-device enforcement are not finished.",
+            "- Checkpoint timeout does not auto-close the checkpoint; the organizer must close it manually.",
+            "- OKO is not integrated with the official NMO portal and does not issue an official credit or certificate.",
+            "- Sprint 2 operator UX and automation remain incomplete. Treat this as a controlled pilot workflow, not a default production promise.",
+            "",
+            "Within those limits, OKO can record technical eligibility from watch-time and checkpoint ratios. The organizer remains responsible for participant communication, identity assurance, accreditation, and the decision to use the mode.",
+            "",
+            "## Available MVP workflow",
+            "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 only as technical OKO evidence. Do not present the NMO mode as complete or promise an official credit, certificate, strict identity proof, or production readiness.",
+        ].join("\n"),
+    },
     {
         name: "oko_mcp_security",
         uri: "oko://guide/security",
@@ -109,9 +151,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",
@@ -122,7 +191,7 @@ const GUIDE_RESOURCES = [
             "",
             "## Webinar setup",
             "- Create, duplicate, move, update, validate, and delete webinars.",
-            "- Configure forms, CTA, banner, cards, video placeholder, Telegram, and NMO settings.",
+            "- Configure forms, CTA, banner, cards, video placeholder, and Telegram settings for standard webinars.",
             "- Upload images from local paths, data URLs, or HTTPS URLs and wait for variants.",
             "",
             "## Live analytics",
@@ -133,7 +202,16 @@ const GUIDE_RESOURCES = [
             "## 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.",
+            "",
+            "## NMO special mode (unfinished MVP)",
+            "- Only after an explicit organizer request, configure NMO criteria, import/remove participants, run manual checkpoints, and read technical attendance evidence.",
+            "- Read `oko://guide/nmo` and disclose its current limitations before enabling or operating the mode.",
+            "",
+            "## 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"),
     },
 ];
@@ -172,10 +250,11 @@ export function registerGuides(server) {
         "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.",
+        "3. Configure metadata, standard blocks, forms, Telegram, and cards as needed.",
+        "4. Do not enable NMO unless the brief explicitly requests the separate NMO MVP mode. If it does, read oko://guide/nmo and disclose the current limitations before any NMO write.",
+        "5. Upload images only after target slots/cards exist; wait for image variants.",
+        "6. Run oko_validate_event_setup and fix actionable errors.",
+        "7. Return public, setup, and analytics links; include NMO registration/login links only for an explicitly requested NMO event.",
         "",
         workspaceId ? `Workspace id: ${workspaceId}` : "Workspace id: not specified; choose the personal workspace unless the user clarifies.",
         "",
@@ -196,8 +275,9 @@ export function registerGuides(server) {
         "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.",
+        "4. If nmoMode is enabled, read oko://guide/nmo and report the unfinished-mode limitations separately from setup findings.",
+        "5. Separate errors that block launch from warnings and polish suggestions.",
+        "6. 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")));

package/dist/server.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "MCP server for managing OKO Stream webinars as an organizer.",
   "license": "UNLICENSED",
   "type": "module",