@okostream/mcp 0.9.1 → 0.9.3

package/dist/env.js

@@ -3,9 +3,16 @@ import { homedir } from "node:os";
 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 });
+const USER_CONFIG_PLACEHOLDER = /^\$\{user_config\.[^{}\s]+\}$/;
+function normalizeOptionalEnv(value) {
+    const normalized = value?.trim();
+    if (!normalized || USER_CONFIG_PLACEHOLDER.test(normalized))
+        return null;
+    return normalized;
+}
 function readOptionalEnv(...names) {
     for (const name of names) {
-        const value = process.env[name]?.trim();
+        const value = normalizeOptionalEnv(process.env[name]);
         if (value)
             return value;
     }
@@ -13,33 +20,39 @@ function readOptionalEnv(...names) {
 }
 function readEnvWithDefault(defaultValue, ...names) {
     for (const name of names) {
-        const value = process.env[name]?.trim();
+        const value = normalizeOptionalEnv(process.env[name]);
         if (value)
             return value;
     }
     return defaultValue;
 }
+function disableImageRoots(reason) {
+    console.error(`[oko-mcp] Local image reads disabled: ${reason}`);
+    return [];
+}
 function readImageRoots() {
-    const rawRoots = process.env.OKO_IMAGE_ROOTS?.trim();
+    const rawRoots = readOptionalEnv("OKO_IMAGE_ROOTS");
     if (!rawRoots)
         return [];
-    return rawRoots.split(delimiter).map((value) => {
+    const roots = [];
+    for (const value of rawRoots.split(delimiter)) {
         const root = value.trim();
         if (!root) {
-            throw new Error("OKO_IMAGE_ROOTS contains an empty directory entry.");
+            return disableImageRoots("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}`);
+            return disableImageRoots("OKO_IMAGE_ROOTS entries must be absolute paths.");
         }
         const resolved = resolve(expanded);
         if (resolved === parse(resolved).root) {
-            throw new Error("OKO_IMAGE_ROOTS must not allow an entire filesystem root.");
+            return disableImageRoots("OKO_IMAGE_ROOTS must not allow an entire filesystem root.");
         }
-        return resolved;
-    });
+        roots.push(resolved);
+    }
+    return roots;
 }
 export const env = {
     apiKey: readOptionalEnv("OKO_API_KEY"),

package/dist/sessionRepair.js

@@ -0,0 +1,37 @@
+export function summarizeSessionRepair(input) {
+    const fixed = !input.verificationError
+        && input.firestorePointer === null
+        && input.rtdbPointer === null;
+    const fulfilled = new Set(input.attempts
+        .filter((attempt) => attempt.status === "fulfilled")
+        .map((attempt) => attempt.path));
+    const cleared = [
+        ...(input.firestorePointer === null ? ["events.activeAnalyticsSessionId"] : []),
+        ...(input.rtdbPointer === null ? ["ctrl/activeSessionId"] : []),
+        ...(input.sessionId && fulfilled.has(`activeSessions/${input.sessionId}`)
+            ? [`activeSessions/${input.sessionId}`]
+            : []),
+        ...(input.sessionId
+            && input.deleteRtdbSessionData
+            && fulfilled.has(`events/${input.eventId}/sessions/${input.sessionId}`)
+            ? [`events/${input.eventId}/sessions/${input.sessionId}`]
+            : []),
+    ];
+    const warnings = input.attempts
+        .filter((attempt) => attempt.status === "rejected")
+        .map((attempt) => `${attempt.path}: ${attempt.error || "cleanup failed"}`);
+    if (input.verificationError) {
+        warnings.push(`postcondition verification: ${input.verificationError}`);
+    }
+    return {
+        eventId: input.eventId,
+        sessionId: input.sessionId,
+        fixed,
+        cleared,
+        warnings,
+        remainingPointers: {
+            firestore: input.firestorePointer,
+            rtdb: input.rtdbPointer,
+        },
+    };
+}

package/dist/tools.js

@@ -13,6 +13,7 @@ import { env } from "./env.js";
 import { ipLiteralFamily, isPublicUnicastAddress, normalizeIpLiteralHostname, } from "./networkPolicy.js";
 import { chatRtdb, firestore, functions, rtdb } from "./firebase.js";
 import { OKO_CONNECTION_STATUSES } from "./onboarding.js";
+import { summarizeSessionRepair } from "./sessionRepair.js";
 import { canonicalTelegramChannelSchema, telegramChannelSchema, } from "./telegramChannelSchema.js";
 import { csvCell, requireConfirm, safeString, serialize, textResult } from "./utils.js";
 import { detectAndNormalize, extractIframeSrc } from "./videoUrl.js";
@@ -867,13 +868,6 @@ function eventLinks(eventId) {
         analyticsUrl: analyticsUrl(eventId),
     };
 }
-function assertEventReadable(data, uid) {
-    const access = Array.isArray(data.accessibleBy) ? data.accessibleBy : [];
-    const editors = Array.isArray(data.editors) ? data.editors : [];
-    if (data.ownerId !== uid && !access.includes(uid) && !editors.includes(uid)) {
-        throw new Error("Event is not accessible to this organizer.");
-    }
-}
 const EVENT_ACCESS_FIELD_BY_MODE = {
     read: "accessibleBy",
     edit: "editors",
@@ -885,22 +879,44 @@ const EVENT_ACCESS_FIELD_BY_MODE = {
     moderate: "chatModerators",
     notify: "notificationSenders",
 };
-function assertEventAccess(data, uid, mode) {
+function grantAllowsMode(data, mode) {
     const field = EVENT_ACCESS_FIELD_BY_MODE[mode];
-    const principals = Array.isArray(data[field]) ? data[field] : [];
-    if (data.ownerId !== uid && !principals.includes(uid)) {
-        throw new Error(`Event does not grant ${mode} access to this organizer.`);
-    }
+    return asRecord(data.capabilities)[field] === true;
+}
+function legacyEventAllowsMode(data, uid, mode) {
+    if (data.ownerId === uid)
+        return true;
+    const fields = mode === "read"
+        ? ["accessibleBy", "editors"]
+        : [EVENT_ACCESS_FIELD_BY_MODE[mode]];
+    return fields.some((field) => (Array.isArray(data[field]) && data[field].includes(uid)));
+}
+function isFirestorePermissionDenied(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === "permission-denied"
+        || code === "firestore/permission-denied"
+        || code === "PERMISSION_DENIED";
 }
 async function readEvent(eventId, uid, mode = "read") {
-    const snap = await getDoc(doc(firestore, "events", eventId));
+    const [snap, grant] = await Promise.all([
+        getDoc(doc(firestore, "events", eventId)),
+        getDoc(doc(firestore, "eventAccess", uid, "grants", eventId)).catch((error) => {
+            if (!isFirestorePermissionDenied(error))
+                throw error;
+            return null;
+        }),
+    ]);
     if (!snap.exists())
         throw new Error("Event not found.");
     const data = snap.data();
-    if (mode === "read")
-        assertEventReadable(data, uid);
-    else
-        assertEventAccess(data, uid, mode);
+    const allowed = grant === null
+        ? legacyEventAllowsMode(data, uid, mode)
+        : data.ownerId === uid || (grant.exists() && grantAllowsMode(grant.data(), mode));
+    if (!allowed) {
+        throw new Error(`Event does not grant ${mode} access to this organizer.`);
+    }
     if (data.trashedAt && mode !== "read" && mode !== "delete") {
         throw new Error("Event is in trash. Restore it before making changes or live actions.");
     }
@@ -1046,7 +1062,7 @@ function initialEventAccess(uid) {
         notificationSenders: [uid],
     };
 }
-async function addEventWithRtdbMirror(uid, workspaceId, eventData) {
+async function addEventWithRtdbMirror(eventData) {
     const eventRef = await addDoc(collection(firestore, "events"), eventData);
     try {
         const ensureRuntime = httpsCallable(functions, "ensureEventRuntime");
@@ -1465,7 +1481,7 @@ export function registerTools(server) {
             args: ["workspaceId: workspace owned by the organizer.", "uid: member uid.", "permissions: 9 workspace permission booleans.", "confirm: must be true."],
             returns: "workspaceId, uid, and updated=true.",
             examples: ["Use to change an existing member's permissions, or direct-add a known uid."],
-            notes: ["Changing a share triggers OKO CF18 fan-out to event access, RTDB workspaceMembers, and chat roles."],
+            notes: ["Changing a share materializes lightweight event grants and updates RTDB workspace/chat mirrors."],
         }),
         inputSchema: {
             workspaceId: z.string().min(1),
@@ -1497,7 +1513,7 @@ export function registerTools(server) {
             args: ["workspaceId: workspace owned by the organizer.", "uid: member uid.", "confirm: must be true."],
             returns: "workspaceId, uid, removed=true.",
             examples: ["Use after listing workspace access and confirming the exact uid."],
-            notes: ["Removing a share triggers OKO CF18 reverse fan-out."],
+            notes: ["Removing a share revokes its event grants and RTDB workspace/chat mirrors."],
         }),
         inputSchema: { workspaceId: z.string().min(1), uid: z.string().min(1), confirm: z.boolean().optional().describe("Required true for member removal.") },
         outputSchema: z.object({ workspaceId: z.string(), uid: z.string(), removed: z.boolean() }).passthrough(),
@@ -1582,7 +1598,7 @@ export function registerTools(server) {
             args: [
                 "limit: maximum events to return, default 30, max 100.",
                 "cursor: timestamp cursor returned as nextCursor by the previous page.",
-                "workspaceId: optional client-side workspace filter.",
+                "workspaceId: optional workspace filter.",
             ],
             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."],
@@ -1597,17 +1613,42 @@ export function registerTools(server) {
     }, async (args) => {
         const { uid } = await authed(["events:read"]);
         const constraints = [
-            where("accessibleBy", "array-contains", uid),
+            ...(args.workspaceId ? [where("workspaceId", "==", args.workspaceId)] : []),
             orderBy("createdAt", "desc"),
             limit(args.limit + 1),
         ];
         if (args.cursor)
-            constraints.splice(2, 0, startAfter(parseTimestampCursor(args.cursor)));
-        const snap = await getDocs(query(collection(firestore, "events"), ...constraints));
-        const { page, hasMore } = pickPage(snap.docs, args.limit);
-        let events = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
-        if (args.workspaceId)
-            events = events.filter((event) => event.workspaceId === args.workspaceId);
+            constraints.splice(constraints.length - 1, 0, startAfter(parseTimestampCursor(args.cursor)));
+        const snap = await getDocs(query(collection(firestore, "eventAccess", uid, "grants"), ...constraints)).catch((error) => {
+            if (!isFirestorePermissionDenied(error))
+                throw error;
+            return null;
+        });
+        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 legacyConstraints = [
+            where("accessibleBy", "array-contains", uid),
+            orderBy("createdAt", "desc"),
+            limit(args.limit + 1),
+        ];
+        if (args.cursor) {
+            legacyConstraints.splice(legacyConstraints.length - 1, 0, startAfter(parseTimestampCursor(args.cursor)));
+        }
+        const legacySnap = await getDocs(query(collection(firestore, "events"), ...legacyConstraints));
+        const { page, hasMore } = pickPage(legacySnap.docs, args.limit);
+        const events = page
+            .map((item) => ({
+            id: item.id,
+            ...serialize(item.data()),
+        }))
+            .filter((event) => !args.workspaceId || event.workspaceId === args.workspaceId);
         const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().createdAt) : null;
         return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) });
     });
@@ -1678,7 +1719,7 @@ export function registerTools(server) {
         const workspaceId = args.workspaceId ?? uid;
         await assertCanCreateInWorkspace(uid, workspaceId);
         const video = normalizeVideo(args.videoUrl);
-        const docRef = await addEventWithRtdbMirror(uid, workspaceId, {
+        const docRef = await addEventWithRtdbMirror({
             ownerId: uid,
             workspaceId,
             ...initialEventAccess(uid),
@@ -2221,7 +2262,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 addEventWithRtdbMirror(uid, workspaceId, {
+        const newRef = await addEventWithRtdbMirror({
             ownerId: uid,
             workspaceId,
             ...initialEventAccess(uid),
@@ -2404,24 +2445,65 @@ export function registerTools(server) {
         const sessionId = safeString(event.activeAnalyticsSessionId) || safeString(ctrlSnap.val());
         requireConfirm(confirm, "oko_fix_orphan_session", { eventId, sessionId: sessionId || null, deleteRtdbSessionData });
         const cleanup = [
-            updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() }),
-            remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)),
+            {
+                path: "events.activeAnalyticsSessionId",
+                promise: updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() }),
+            },
+            {
+                path: "ctrl/activeSessionId",
+                promise: remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)),
+            },
         ];
-        if (sessionId)
-            cleanup.push(remove(ref(rtdb, `activeSessions/${sessionId}`)));
-        if (sessionId && deleteRtdbSessionData)
-            cleanup.push(remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`)));
-        const results = await Promise.allSettled(cleanup);
-        const warnings = results
-            .filter((result) => result.status === "rejected")
-            .map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason));
-        return textResult({
+        if (sessionId) {
+            cleanup.push({
+                path: `activeSessions/${sessionId}`,
+                promise: remove(ref(rtdb, `activeSessions/${sessionId}`)),
+            });
+        }
+        if (sessionId && deleteRtdbSessionData) {
+            cleanup.push({
+                path: `events/${eventId}/sessions/${sessionId}`,
+                promise: remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`)),
+            });
+        }
+        const settled = await Promise.allSettled(cleanup.map((operation) => operation.promise));
+        const attempts = settled.map((result, index) => {
+            const operation = cleanup[index];
+            if (!operation)
+                throw new Error("Session repair result has no matching cleanup operation.");
+            return {
+                path: operation.path,
+                status: result.status,
+                ...(result.status === "rejected" ? {
+                    error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                } : {}),
+            };
+        });
+        let firestorePointer = null;
+        let rtdbPointer = null;
+        let verificationError;
+        try {
+            const [eventAfter, ctrlAfter] = await Promise.all([
+                getDoc(doc(firestore, "events", eventId)),
+                get(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)),
+            ]);
+            firestorePointer = eventAfter.exists()
+                ? safeString(eventAfter.data().activeAnalyticsSessionId) || null
+                : null;
+            rtdbPointer = safeString(ctrlAfter.val()) || null;
+        }
+        catch (error) {
+            verificationError = error instanceof Error ? error.message : String(error);
+        }
+        return textResult(summarizeSessionRepair({
             eventId,
             sessionId: sessionId || null,
-            fixed: warnings.length === 0,
-            cleared: ["events.activeAnalyticsSessionId", "ctrl/activeSessionId", ...(sessionId ? [`activeSessions/${sessionId}`] : []), ...(sessionId && deleteRtdbSessionData ? [`events/${eventId}/sessions/${sessionId}`] : [])],
-            warnings,
-        });
+            deleteRtdbSessionData,
+            attempts,
+            firestorePointer,
+            rtdbPointer,
+            verificationError,
+        }));
     });
     server.registerTool("oko_delete_session", {
         title: "Delete analytics session",

package/dist/utils.js

@@ -19,9 +19,6 @@ export function serialize(value) {
     }
     return out;
 }
-export function docJson(snap) {
-    return { id: snap.id, ...serialize(snap.data()) };
-}
 function compactForText(value, depth = 0) {
     if (typeof value === "string" && value.length > MAX_COMPACT_STRING_LENGTH) {
         return `${value.slice(0, MAX_COMPACT_STRING_LENGTH)}... [truncated ${value.length - MAX_COMPACT_STRING_LENGTH} chars]`;

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {
@@ -31,7 +31,7 @@
     "oko-mcp": "dist/server.js"
   },
   "scripts": {
-    "prebuild": "node ../scripts/generateMcpContract.mjs --check",
+    "prebuild": "node ../scripts/generateMcpVersion.mjs && node ../scripts/generateMcpContract.mjs --check",
     "build": "tsc && node -e \"require('node:fs').chmodSync('dist/server.js', 0o755)\"",
     "test": "npm run build && node --test test/*.test.mjs",
     "smoke:tarball": "node test/tarball-smoke.mjs",