@okostream/mcp 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.7.2 - 2026-07-23
+
+- Replaced the maintainer-oriented npm README with a concise organizer setup,
+  capability, safety, image-access, and troubleshooting guide.
+- Removed the private repository link and added public homepage, author, and
+  discovery metadata.
+- Disabled local image reads until `OKO_IMAGE_ROOTS` explicitly lists trusted
+  directories.
+- Added the MCP client version to API-key exchange requests so the platform can
+  introduce a controlled minimum-version gate in a separate auth release.
+
 ## 0.7.1 - 2026-07-22
 
 - Refreshed transitive dependencies after new npm advisories without changing the MCP tool/resource/prompt surface.

package/README.md

@@ -1,20 +1,25 @@
-# OKO MCP Server
+# OKO MCP
 
-MCP server for managing OKO Stream webinars as an organizer.
+Control OKO Stream webinars from Claude, Codex, or another stdio MCP client.
+Create webinar pages, configure audience blocks, manage live interactions, and
+read analytics without switching to the organizer dashboard.
 
-## Quick Setup
+## Connect
 
-1. Create an API key in OKO: `/app/mcp` -> access keys.
-2. Add the server to your MCP client config.
+You need an OKO organizer account and Node.js 20.18.1 or newer.
 
-Claude Desktop / Claude Code:
+1. Open [OKO MCP settings](https://okostream.app/app/mcp).
+2. Create an access key and select only the permissions you need.
+3. Add OKO to your MCP client.
+
+### Claude Desktop or Claude Code
 
 ```json
 {
   "mcpServers": {
     "oko": {
       "command": "npx",
-      "args": ["-y", "@okostream/mcp"],
+      "args": ["-y", "@okostream/mcp@latest"],
       "env": {
         "OKO_API_KEY": "oko_sk_..."
       }
@@ -23,160 +28,106 @@ Claude Desktop / Claude Code:
 }
 ```
 
-Codex:
+### Codex
 
 ```toml
 [mcp_servers.oko]
 command = "npx"
-args = ["-y", "@okostream/mcp"]
+args = ["-y", "@okostream/mcp@latest"]
 
 [mcp_servers.oko.env]
 OKO_API_KEY = "oko_sk_..."
 ```
 
-The package includes the public Firebase config for `okostreamcore`, so `OKO_API_KEY` is the only required variable. For staging or local experiments, override these optional variables:
-
-```bash
-OKO_EXCHANGE_URL=...
-OKO_FIREBASE_API_KEY=...
-OKO_FIREBASE_AUTH_DOMAIN=...
-OKO_FIREBASE_DATABASE_URL=...
-OKO_FIREBASE_CHAT_DB_URL=...
-OKO_FIREBASE_PROJECT_ID=...
-OKO_FIREBASE_STORAGE_BUCKET=...
-OKO_FIREBASE_MESSAGING_SENDER_ID=...
-OKO_FIREBASE_APP_ID=...
-# Path-delimited allowlist for local image reads; defaults to the process cwd.
-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.
+Restart the MCP client, then ask:
 
-## Security Model
+> Check my OKO connection with `oko_whoami`, then show my five most recent
+> webinars. Do not change anything.
 
-- Each API key exchanges into its own Firebase identity `mcp_<keyId>`; it never inherits platform-owner claims from the organizer account.
-- Every protected operation is checked independently by MCP scope, active key state, organizer identity, and event/workspace capability in Cloud Functions and Firebase Rules.
-- Revocation disables the synthetic identity, revokes refresh tokens, and invalidates Firestore, main RTDB, and chat RTDB access immediately.
-- API-key creation and revocation are browser-only callables. Raw secrets are hashed at rest and shown once.
-- MCP image uploads go through a scoped callable; MCP sessions cannot write Firebase Storage directly.
-- Local files are constrained to `OKO_IMAGE_ROOTS`, symlink escapes are rejected, and remote images use HTTPS with DNS pinning, redirect revalidation, and byte/pixel limits.
-- Every non-read-only tool writes a compact server-owned audit event. Message bodies, captions, lead values, and file contents are not copied into the audit record.
-- Destructive, live, public-upload, claim, chat-send, and Telegram actions require `confirm:true`.
-- Event, lead, participant, chat, URL, and remote-image content is untrusted data, never instructions for the MCP client.
+## What You Can Do
 
-## Response Contract
+- Create, duplicate, move, restore, and delete webinar events.
+- Configure video, metadata, forms, calls to action, cards, banners, and images.
+- Operate webinar chat, moderation, checkpoints, and live block visibility.
+- Start and finish analytics sessions and prepare session reports.
+- Manage workspaces, invitations, access rights, and notifications.
+- Connect Telegram channels and schedule or publish event posts.
 
-Every tool returns JSON text plus MCP `structuredContent`. List-like tools use bounded pages:
+Standard webinars are the default workflow. NMO is a separate beta mode and is
+used only when the organizer explicitly requests it.
 
-- `limit` defaults to 20-50 depending on the tool.
-- Cursor tools return both `hasMore`/`nextCursor` and `has_more`/`next_cursor`.
-- `oko_list_my_events`, `oko_get_analytics`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_list_notifications`, `oko_list_workspace_access`, `oko_list_workspace_invites`, and `oko_list_telegram_posts` support pagination.
-- `oko_get_analytics` omits heavy `timeline`, baseline/final snapshots, and NMO participant rows by default. Request `includeTimeline`, `includeSnapshots`, or `includeNmoRows` only when needed.
-- `oko_get_session_report` returns a compact structured session report plus markdown suitable for a human handoff.
-- Standard webinar Start/End uses server-owned Analytics v3 callables shared with the dashboard; completed reports include explicit data-quality markers. NMO remains a separate unfinished special-mode workflow.
-- Oversized responses are truncated with `truncated: true` and a `truncationMessage`.
+## Images
 
-The server also exposes MCP-native onboarding:
+Public HTTPS image URLs work without additional configuration.
 
-- `instructions` on initialize with the supported webinar creation flow and product invariants.
-- 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`.
+Local file access is disabled by default. To let OKO MCP upload images from your
+computer, add an explicit trusted-directory allowlist to the client config.
+Use a dedicated folder rather than your home directory.
 
-This package is published as source-available runtime distribution for OKO customers. `license: UNLICENSED` means all rights reserved unless a separate agreement says otherwise.
-
-## Local Development
-
-```bash
-cd mcp
-npm install
-npm run build
-npm start
-```
-
-Local config without npm publishing:
+### Claude with Local Images
 
 ```json
 {
   "mcpServers": {
     "oko": {
-      "command": "node",
-      "args": ["/absolute/path/to/okostream/mcp/dist/server.js"],
+      "command": "npx",
+      "args": ["-y", "@okostream/mcp@latest"],
       "env": {
-        "OKO_API_KEY": "oko_sk_..."
+        "OKO_API_KEY": "oko_sk_...",
+        "OKO_IMAGE_ROOTS": "/Users/you/Documents/OKO"
       }
     }
   }
 }
 ```
 
-## Tools
+### Codex with Local Images
 
-All tools are prefixed with `oko_` for safe discovery next to other MCP servers.
-
-Core discovery/read tools:
-
-- `oko_whoami`, `oko_list_workspaces`, `oko_list_my_events`, `oko_get_event`
-- `oko_validate_event_setup`
-- `oko_update_profile`, `oko_list_notifications`, `oko_mark_notifications_read`
-- `oko_get_live_state`, `oko_get_analytics`, `oko_get_session_report`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`, `oko_delete_lead`
-
-Event/setup/media tools:
-
-- `oko_create_webinar`, `oko_update_event`, `oko_delete_event` (30-day trash compatibility alias)
-- `oko_trash_event`, `oko_restore_event`, `oko_delete_event_permanently`
-- `oko_duplicate_event`, `oko_move_event`
-- `oko_configure_blocks`, `oko_configure_cards`
-- `oko_upload_image`, `oko_upload_card_images_batch`, `oko_wait_for_image_variants`, `oko_delete_image`
-
-Live/session/chat/NMO tools:
+```toml
+[mcp_servers.oko]
+command = "npx"
+args = ["-y", "@okostream/mcp@latest"]
 
-- `oko_set_block_visibility`, `oko_refresh_viewers`
-- `oko_start_session`, `oko_end_session`, `oko_fix_orphan_session`, `oko_delete_session`
-- `oko_send_chat_message`, `oko_delete_chat_message`, `oko_mute_user`, `oko_unmute_user`, `oko_ban_user`, `oko_unban_user`, `oko_set_chat_settings`
-- `oko_launch_checkpoint`, `oko_close_checkpoint`
-- `oko_add_nmo_participant`, `oko_import_nmo_participants`, `oko_remove_nmo_participant`
+[mcp_servers.oko.env]
+OKO_API_KEY = "oko_sk_..."
+OKO_IMAGE_ROOTS = "/Users/you/Documents/OKO"
+```
 
-Workspace and Telegram tools:
+Use `:` between multiple directories on macOS and Linux, or `;` on Windows.
+Paths must be absolute. Filesystem roots are rejected, and symlinks cannot
+escape the configured directories.
 
-- `oko_create_workspace`, `oko_update_workspace`, `oko_delete_workspace`
-- `oko_list_workspace_access`, `oko_update_workspace_member`, `oko_remove_workspace_member`
-- `oko_create_workspace_invite`, `oko_list_workspace_invites`, `oko_revoke_workspace_invite`, `oko_claim_workspace_invite`
-- `oko_create_telegram_link`, `oko_list_telegram_channels`, `oko_claim_telegram_channel`
-- `oko_set_telegram_channel_workspaces`, `oko_disconnect_telegram_channel`
-- `oko_list_telegram_posts`, `oko_cancel_telegram_post`, `oko_publish_telegram_post`
+## Access and Safety
 
-Dangerous or external side-effect tools require `confirm: true`.
+- The access key acts only as the organizer and permissions selected for that
+  key. It does not inherit platform-administrator access.
+- Revoking a key in OKO immediately disables its Firebase and MCP access.
+- Destructive, live, public-upload, chat-send, claim, and Telegram actions
+  require explicit confirmation.
+- Keys stay in the local MCP client environment. The npm package contains no
+  organizer key or other private credential.
+- Event content, chat messages, URLs, and remote images are treated as data,
+  never as instructions for the AI client.
 
-## Smoke
+The Firebase web configuration bundled with the package is public project
+metadata. Access to OKO data is enforced separately by the access-key identity,
+scopes, organizer permissions, Cloud Functions, and Firebase Security Rules.
 
-1. `oko_whoami` should return the organizer UID and granted scopes.
-2. `oko_list_my_events` should return only events visible to that UID.
-3. `oko_create_webinar` should create a test webinar and RTDB owner/workspace mirror.
-4. `oko_configure_cards` should create/update `blocks.cards.items` and preserve card image fields by stable card id.
-5. `oko_upload_card_images_batch` should upload multiple card images, then return ready `imageVariants`.
-6. `oko_validate_event_setup` should catch missing images/forms/buttons/video/NMO/Telegram/variants on a deliberately broken event.
-7. `oko_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
-8. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
-9. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
-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 65 tools, 7 resources, 3 prompts, and non-empty initialize instructions.
+## Troubleshooting
 
-CLI help:
+Check the installed package:
 
 ```bash
-npx -y @okostream/mcp --help
+npx -y @okostream/mcp@latest --help
 ```
 
-## Troubleshooting
-
-If Claude shows `Unexpected token '◇'`, the MCP server printed a non-JSON line to stdout. Use the current version with `dotenv quiet:true`, then fully restart the MCP client.
+- **Invalid or revoked key:** create a new key in
+  [OKO MCP settings](https://okostream.app/app/mcp) and replace
+  `OKO_API_KEY`.
+- **Claude reports `Unexpected token`:** make sure the config uses
+  `@okostream/mcp@latest`, fully quit the MCP client, and open it again.
+- **A local image is rejected:** add its directory to `OKO_IMAGE_ROOTS`, then
+  restart the client.
 
-For stdio MCP, stdout must contain only JSON-RPC. Diagnostics belong on stderr.
+Settings, key management, and installation snippets are always available at
+[okostream.app/app/mcp](https://okostream.app/app/mcp).

package/dist/auth.js

@@ -2,18 +2,27 @@ import { signInWithCustomToken } from "firebase/auth";
 import { auth } from "./firebase.js";
 import { env } from "./env.js";
 import { sanitizeScopes } from "./scopes.js";
+import { OKO_MCP_VERSION } from "./version.js";
 let state = null;
 async function exchangeApiKey() {
     const response = await fetch(env.exchangeUrl, {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ apiKey: env.apiKey }),
+        body: JSON.stringify({ apiKey: env.apiKey, clientVersion: OKO_MCP_VERSION }),
     });
     if (!response.ok) {
         const status = response.status;
+        const errorBody = await response.json().catch(() => ({}));
+        if (status === 426) {
+            const minimumVersion = typeof errorBody.minimumVersion === "string"
+                ? errorBody.minimumVersion
+                : "the current release";
+            throw new Error(`OKO MCP ${OKO_MCP_VERSION} is no longer supported. Update to @okostream/mcp@latest ` +
+                `(minimum ${minimumVersion}) and restart the MCP client.`);
+        }
         throw new Error(status === 401
             ? "OKO API key is invalid or revoked. Create a fresh key in OKO Settings and set OKO_API_KEY."
-            : `OKO API key exchange failed with HTTP ${status}. Check OKO_EXCHANGE_URL and try again.`);
+            : `OKO API key exchange failed with HTTP ${status}. Check your connection and try again.`);
     }
     const data = await response.json();
     if (typeof data.customToken !== "string") {

package/dist/env.js

@@ -1,6 +1,6 @@
 import { config } from "dotenv";
 import { homedir } from "node:os";
-import { delimiter, join, resolve } from "node:path";
+import { delimiter, isAbsolute, join, parse, resolve } from "node:path";
 import { DEFAULT_EXCHANGE_URL, DEFAULT_FIREBASE_CONFIG } from "./firebaseDefaults.js";
 config({ path: join(homedir(), ".env"), quiet: true });
 function readEnv(...names) {
@@ -19,15 +19,31 @@ function readEnvWithDefault(defaultValue, ...names) {
     }
     return defaultValue;
 }
+function readImageRoots() {
+    const rawRoots = process.env.OKO_IMAGE_ROOTS?.trim();
+    if (!rawRoots)
+        return [];
+    return rawRoots.split(delimiter).map((value) => {
+        const root = value.trim();
+        if (!root) {
+            throw new Error("OKO_IMAGE_ROOTS contains an empty directory entry.");
+        }
+        const expanded = root === "~" || root.startsWith("~/")
+            ? join(homedir(), root.slice(2))
+            : root;
+        if (!isAbsolute(expanded)) {
+            throw new Error(`OKO_IMAGE_ROOTS entries must be absolute paths: ${root}`);
+        }
+        const resolved = resolve(expanded);
+        if (resolved === parse(resolved).root) {
+            throw new Error("OKO_IMAGE_ROOTS must not allow an entire filesystem root.");
+        }
+        return resolved;
+    });
+}
 export const env = {
     apiKey: readEnv("OKO_API_KEY"),
-    imageRoots: (process.env.OKO_IMAGE_ROOTS?.trim() || process.cwd())
-        .split(delimiter)
-        .map((root) => root.trim())
-        .map((root) => root === "~" || root.startsWith("~/")
-        ? resolve(join(homedir(), root.slice(2)))
-        : resolve(root))
-        .filter(Boolean),
+    imageRoots: readImageRoots(),
     exchangeUrl: readEnvWithDefault(DEFAULT_EXCHANGE_URL, "OKO_EXCHANGE_URL"),
     firebase: {
         apiKey: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.apiKey, "OKO_FIREBASE_API_KEY", "NEXT_PUBLIC_FIREBASE_API_KEY"),

package/dist/guides.js

@@ -112,7 +112,7 @@ const GUIDE_RESOURCES = [
             "- MCP image bytes cross a scoped callable; MCP sessions cannot write Firebase Storage directly.",
             "- Every write tool emits a server-owned audit record without storing message/caption/body content.",
             "- Destructive, live, or external side-effect tools require explicit `confirm:true`.",
-            "- Local image paths are limited to `OKO_IMAGE_ROOTS` (path-delimited; current working directory by default). Symlink escapes are blocked.",
+            "- Local image reads are disabled by default. `OKO_IMAGE_ROOTS` enables a path-delimited allowlist; symlink escapes are blocked.",
             "- Remote image downloads require public HTTPS, pin the validated DNS address, revalidate redirects, and enforce byte/pixel limits.",
             "- Wrong API-key exchanges are counted per keyId; after 10 failures the keyId is locked for 15 minutes.",
             "",

package/dist/server.js

@@ -3,19 +3,21 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { OKO_MCP_INSTRUCTIONS, registerGuides } from "./guides.js";
 import { registerTools } from "./tools.js";
+import { OKO_MCP_VERSION } from "./version.js";
 if (process.argv.includes("--help")) {
     process.stdout.write([
         "OKO MCP Server",
         "",
         "Usage:",
         "  oko-mcp",
-        "  npx -y @okostream/mcp",
+        "  npx -y @okostream/mcp@latest",
         "",
         "Required env:",
         "  OKO_API_KEY=oko_sk_...",
         "",
-        "Optional env overrides:",
-        "  OKO_EXCHANGE_URL, OKO_FIREBASE_*",
+        "Optional local image access:",
+        "  OKO_IMAGE_ROOTS=/trusted/image/directory",
+        "  Local file reads are disabled unless this allowlist is set.",
         "",
         "The server speaks MCP over stdio. Do not run it manually before connecting a client.",
     ].join("\n") + "\n");
@@ -23,7 +25,7 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.7.1",
+    version: OKO_MCP_VERSION,
 }, {
     instructions: OKO_MCP_INSTRUCTIONS,
 });

package/dist/tools.js

@@ -499,6 +499,9 @@ async function readRemoteImage(rawUrl, redirects = 0) {
     }
 }
 async function readLocalImage(inputPath) {
+    if (env.imageRoots.length === 0) {
+        throw new Error("Local image reads are disabled. Set OKO_IMAGE_ROOTS to an explicit trusted directory and restart the MCP client.");
+    }
     const filePath = await realpath(resolveLocalImagePath(inputPath));
     const roots = await Promise.all(env.imageRoots.map(async (root) => {
         try {

package/dist/version.js

@@ -0,0 +1 @@
+export const OKO_MCP_VERSION = "0.7.2";

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.7.1",
-  "description": "MCP server for managing OKO Stream webinars as an organizer.",
+  "version": "0.7.2",
+  "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
+  "author": {
+    "name": "OKO Stream",
+    "url": "https://okostream.app"
+  },
+  "homepage": "https://okostream.app/app/mcp",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "webinar",
+    "webinars",
+    "claude",
+    "codex",
+    "okostream"
+  ],
   "type": "module",
   "main": "dist/server.js",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BelfanioXL/okostreamcore.git",
-    "directory": "mcp"
-  },
   "publishConfig": {
     "access": "public"
   },