@okostream/mcp 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# OKO MCP Server
+
+MCP server for managing OKO Stream webinars as an organizer.
+
+## Quick Setup
+
+1. Create an API key in OKO: `/app/settings` -> API keys for MCP.
+2. Add the server to your MCP client config.
+
+Claude Desktop / Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "oko": {
+      "command": "npx",
+      "args": ["-y", "@okostream/mcp"],
+      "env": {
+        "OKO_API_KEY": "oko_sk_..."
+      }
+    }
+  }
+}
+```
+
+Codex:
+
+```toml
+[mcp_servers.oko]
+command = "npx"
+args = ["-y", "@okostream/mcp"]
+
+[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=...
+```
+
+## Response Contract
+
+Every tool returns JSON text plus MCP `structuredContent`. List-like tools use bounded pages:
+
+- `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`, and `oko_list_leads` 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.
+- Oversized responses are truncated with `truncated: true` and a `truncationMessage`.
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "oko": {
+      "command": "node",
+      "args": ["/absolute/path/to/okostream/mcp/dist/server.js"],
+      "env": {
+        "OKO_API_KEY": "oko_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+All tools are prefixed with `oko_` for safe discovery next to other MCP servers.
+
+Read tools include:
+
+- `oko_whoami`
+- `oko_list_workspaces`
+- `oko_list_my_events`
+- `oko_get_event`
+- `oko_get_live_state`
+- `oko_get_analytics`
+- `oko_list_recent_chat`
+- `oko_list_participants`
+- `oko_list_leads`
+
+Write/control tools include:
+
+- `oko_create_webinar`
+- `oko_update_event`
+- `oko_configure_blocks`
+- `oko_set_block_visibility`
+- `oko_refresh_viewers`
+- `oko_start_session`
+- `oko_end_session`
+- `oko_send_chat_message`
+- `oko_delete_chat_message`
+- `oko_mute_user`
+- `oko_ban_user`
+- `oko_set_chat_settings`
+- `oko_launch_checkpoint`
+- `oko_close_checkpoint`
+- `oko_publish_telegram_post`
+- `oko_create_workspace_invite`
+- `oko_delete_event`
+
+Dangerous or external side-effect tools require `confirm: true`.
+
+## Smoke
+
+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_get_analytics` should read an existing event with analytics sessions.
+
+CLI help:
+
+```bash
+npx -y @okostream/mcp --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.
+
+For stdio MCP, stdout must contain only JSON-RPC. Diagnostics belong on stderr.

package/dist/auth.js

@@ -0,0 +1,48 @@
+import { signInWithCustomToken } from "firebase/auth";
+import { auth } from "./firebase.js";
+import { env } from "./env.js";
+import { sanitizeScopes } from "./scopes.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 }),
+    });
+    if (!response.ok) {
+        const status = response.status;
+        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.`);
+    }
+    const data = await response.json();
+    if (typeof data.customToken !== "string") {
+        throw new Error("OKO API key exchange returned no customToken.");
+    }
+    return {
+        customToken: data.customToken,
+        expiresIn: typeof data.expiresIn === "number" ? data.expiresIn : 3600,
+        scopes: sanitizeScopes(data.scopes),
+    };
+}
+export async function ensureAuth(requiredScopes = []) {
+    const now = Date.now();
+    if (!state || now > state.expiresAt - 5 * 60 * 1000 || !auth.currentUser) {
+        const exchanged = await exchangeApiKey();
+        const credential = await signInWithCustomToken(auth, exchanged.customToken);
+        state = {
+            uid: credential.user.uid,
+            scopes: exchanged.scopes,
+            expiresAt: now + exchanged.expiresIn * 1000,
+        };
+    }
+    for (const scope of requiredScopes) {
+        if (!state.scopes.includes(scope)) {
+            throw new Error(`API key scope required: ${scope}. Create or choose an OKO API key with that scope.`);
+        }
+    }
+    return state;
+}
+export function currentScopes() {
+    return state?.scopes ?? [];
+}

package/dist/env.js

@@ -0,0 +1,35 @@
+import { config } from "dotenv";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_EXCHANGE_URL, DEFAULT_FIREBASE_CONFIG } from "./firebaseDefaults.js";
+config({ path: join(homedir(), ".env"), quiet: true });
+function readEnv(...names) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    throw new Error(`Missing required env var: ${names.join(" or ")}`);
+}
+function readEnvWithDefault(defaultValue, ...names) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return defaultValue;
+}
+export const env = {
+    apiKey: readEnv("OKO_API_KEY"),
+    exchangeUrl: readEnvWithDefault(DEFAULT_EXCHANGE_URL, "OKO_EXCHANGE_URL"),
+    firebase: {
+        apiKey: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.apiKey, "OKO_FIREBASE_API_KEY", "NEXT_PUBLIC_FIREBASE_API_KEY"),
+        authDomain: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.authDomain, "OKO_FIREBASE_AUTH_DOMAIN", "NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN"),
+        databaseURL: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.databaseURL, "OKO_FIREBASE_DATABASE_URL", "NEXT_PUBLIC_FIREBASE_DATABASE_URL"),
+        projectId: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.projectId, "OKO_FIREBASE_PROJECT_ID", "NEXT_PUBLIC_FIREBASE_PROJECT_ID"),
+        storageBucket: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.storageBucket, "OKO_FIREBASE_STORAGE_BUCKET", "NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET"),
+        messagingSenderId: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.messagingSenderId, "OKO_FIREBASE_MESSAGING_SENDER_ID", "NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID"),
+        appId: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.appId, "OKO_FIREBASE_APP_ID", "NEXT_PUBLIC_FIREBASE_APP_ID"),
+        chatDatabaseURL: readEnvWithDefault(DEFAULT_FIREBASE_CONFIG.chatDatabaseURL, "OKO_FIREBASE_CHAT_DB_URL", "NEXT_PUBLIC_FIREBASE_CHAT_DB_URL"),
+    },
+};

package/dist/firebase.js

@@ -0,0 +1,22 @@
+import { initializeApp, getApp, getApps } from "firebase/app";
+import { getAuth } from "firebase/auth";
+import { getDatabase } from "firebase/database";
+import { getFirestore } from "firebase/firestore";
+import { getFunctions } from "firebase/functions";
+import { env } from "./env.js";
+export const firebaseApp = getApps().length ? getApp() : initializeApp({
+    apiKey: env.firebase.apiKey,
+    authDomain: env.firebase.authDomain,
+    databaseURL: env.firebase.databaseURL,
+    projectId: env.firebase.projectId,
+    storageBucket: env.firebase.storageBucket,
+    messagingSenderId: env.firebase.messagingSenderId,
+    appId: env.firebase.appId,
+});
+export const auth = getAuth(firebaseApp);
+export const firestore = getFirestore(firebaseApp);
+export const rtdb = getDatabase(firebaseApp);
+export const chatRtdb = env.firebase.chatDatabaseURL
+    ? getDatabase(firebaseApp, env.firebase.chatDatabaseURL)
+    : getDatabase(firebaseApp);
+export const functions = getFunctions(firebaseApp, "us-central1");

package/dist/firebaseDefaults.js

@@ -0,0 +1,11 @@
+export const DEFAULT_EXCHANGE_URL = "https://us-central1-okostreamcore.cloudfunctions.net/exchangeApiKey";
+export const DEFAULT_FIREBASE_CONFIG = {
+    apiKey: "AIzaSyCbin_AY-tG62I-_n0lkpdfPf8SH9XmqAg",
+    authDomain: "okostreamcore.firebaseapp.com",
+    databaseURL: "https://okostreamcore-default-rtdb.firebaseio.com",
+    chatDatabaseURL: "https://okostreamcore-chat.firebaseio.com",
+    projectId: "okostreamcore",
+    storageBucket: "okostreamcore.firebasestorage.app",
+    messagingSenderId: "876016833190",
+    appId: "1:876016833190:web:6d12602c6c2c57491b9a67",
+};

package/dist/scopes.js

@@ -0,0 +1,22 @@
+export const MCP_SCOPES = [
+    "events:read",
+    "events:write",
+    "events:delete",
+    "setup:write",
+    "analytics:read",
+    "analytics:write",
+    "live:control",
+    "chat:write",
+    "chat:moderate",
+    "telegram:write",
+    "workspace:read",
+    "workspace:write",
+    "nmo:write",
+    "leads:read",
+];
+const SCOPE_SET = new Set(MCP_SCOPES);
+export function sanitizeScopes(scopes) {
+    if (!Array.isArray(scopes))
+        return [];
+    return scopes.filter((scope) => typeof scope === "string" && SCOPE_SET.has(scope));
+}

package/dist/server.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+if (process.argv.includes("--help")) {
+    process.stdout.write([
+        "OKO MCP Server",
+        "",
+        "Usage:",
+        "  oko-mcp",
+        "  npx -y @okostream/mcp",
+        "",
+        "Required env:",
+        "  OKO_API_KEY=oko_sk_...",
+        "",
+        "Optional env overrides:",
+        "  OKO_EXCHANGE_URL, OKO_FIREBASE_*",
+        "",
+        "The server speaks MCP over stdio. Do not run it manually before connecting a client.",
+    ].join("\n") + "\n");
+    process.exit(0);
+}
+const server = new McpServer({
+    name: "oko-mcp-server",
+    version: "0.1.0",
+});
+registerTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);