@okostream/mcp 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.6.0 - 2026-07-10
+
+- Replaced legacy profile/workspace Telegram arrays with canonical server-owned channel operations.
+- Added personal Telegram linking, explicit workspace sharing, channel disconnect, and event-scoped channel discovery.
+- Added 30-day event trash, restore, and exact-title permanent deletion tools; retained `oko_delete_event` as a recoverable trash alias.
+- Prevented cancellation of `delivery_unknown` Telegram posts and resolved channels server-side before publication to reduce duplicate or unauthorized sends.
+
 ## 0.5.4 - 2026-07-10
 
 - Separated NMO from the standard webinar workflow throughout instructions, resources, prompts, README, and the companion skill.

package/README.md

@@ -127,7 +127,8 @@ Core discovery/read tools:
 
 Event/setup/media tools:
 
-- `oko_create_webinar`, `oko_update_event`, `oko_delete_event`
+- `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`
@@ -145,7 +146,9 @@ Workspace and Telegram tools:
 - `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_list_telegram_channels`, `oko_claim_telegram_channel`, `oko_list_telegram_posts`, `oko_cancel_telegram_post`, `oko_publish_telegram_post`
+- `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`
 
 Dangerous or external side-effect tools require `confirm: true`.
 
@@ -163,7 +166,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, 7 resources, 3 prompts, and non-empty initialize instructions.
+13. MCP protocol smoke should report 65 tools, 7 resources, 3 prompts, and non-empty initialize instructions.
 
 CLI help:
 

package/dist/guides.js

@@ -118,14 +118,14 @@ const GUIDE_RESOURCES = [
             "",
             "- `events:read`: list and read event documents.",
             "- `events:write`: create, duplicate, move, and update event metadata.",
-            "- `events:delete`: delete event records.",
+            "- `events:delete`: move events to trash, restore them, and permanently delete already-trashed events.",
             "- `setup:write`: configure blocks, forms, cards, and images.",
             "- `analytics:read`: read live state, sessions, reports, chat history.",
             "- `analytics:write` + `live:control`: start/end/fix/delete analytics sessions.",
             "- `live:control`: live block visibility and viewer refresh.",
             "- `chat:write`: send organizer chat messages.",
             "- `chat:moderate`: delete, mute, ban, unmute, unban, and chat settings.",
-            "- `telegram:write`: claim/list channels and create/cancel/publish Telegram posts.",
+            "- `telegram:write`: link personal Telegram, claim/list/share/disconnect channels, and create/cancel/publish Telegram posts.",
             "- `workspace:read` / `workspace:write`: workspace, members, invites, notifications.",
             "- `nmo:write`: NMO participants and checkpoints.",
             "- `leads:read`: read form submissions; lead deletion also requires `setup:write`.",
@@ -166,16 +166,18 @@ const GUIDE_RESOURCES = [
             "# 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.",
+            "1. Call `oko_create_telegram_link`, open its one-time @OKOStreamBot link in the organizer's personal Telegram account, and complete the link there.",
+            "2. Add `@OKOStreamBot` to the target channel as an administrator with permission to post.",
+            "3. The bot provides a claim code for that channel. Copy it exactly; do not invent a channel ID.",
+            "4. Call `oko_claim_telegram_channel` with the claim code, optional owned workspace ids, and `confirm:true`. The server verifies that the linked personal Telegram user is a channel administrator.",
+            "5. Call `oko_list_telegram_channels` and choose a channel by its returned title and id. Pass `eventId` when workspace-shared channels should be included.",
+            "6. Use `oko_set_telegram_channel_workspaces` to replace explicit workspace sharing, or `oko_disconnect_telegram_channel` to disconnect an owned channel; both require confirmation.",
+            "7. 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`.",
+            "3. Use `oko_list_telegram_posts` to inspect draft, scheduled, sent, failed, or delivery-unknown posts. Only cancel draft, pending, scheduled, or failed posts with `oko_cancel_telegram_post` and `confirm:true`; review delivery-unknown manually to avoid duplicate publication.",
             "",
             "## 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.",
@@ -190,7 +192,7 @@ const GUIDE_RESOURCES = [
             "# OKO MCP Capabilities",
             "",
             "## Webinar setup",
-            "- Create, duplicate, move, update, validate, and delete webinars.",
+            "- Create, duplicate, move, update, and validate webinars; trash them for 30 days, restore them, or permanently delete an already-trashed event with exact-title confirmation.",
             "- 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.",
             "",

package/dist/server.js

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

package/dist/tools.js

@@ -2,7 +2,7 @@ import { lookup } from "node:dns/promises";
 import { stat, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import sharp from "sharp";
 import { Agent, fetch as undiciFetch } from "undici";
 import { z } from "zod";
@@ -43,7 +43,7 @@ const ANALYTICS_TIMELINE_DEFAULT_LIMIT = 120;
 const MAX_NMO_IMPORT_PARTICIPANTS = 200;
 const MAX_WORKSPACE_NAME_LENGTH = 120;
 const MAX_WORKSPACE_INVITE_CODE_LENGTH = 64;
-const TELEGRAM_POST_STATUSES = ["draft", "scheduled", "sent", "failed"];
+const TELEGRAM_POST_STATUSES = ["draft", "scheduled", "sent", "failed", "delivery_unknown"];
 const readOnlyTool = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -145,6 +145,8 @@ const imageOutputSchema = z.object({
     variantsPending: z.boolean(),
     sourceBytes: z.number().int().nonnegative(),
     masterBytes: z.number().int().nonnegative(),
+    imageWidth: z.number().int().positive(),
+    imageHeight: z.number().int().positive(),
     note: z.string(),
 }).passthrough();
 const deleteImageOutputSchema = z.object({
@@ -275,6 +277,10 @@ const telegramChannelSchema = z.object({
     title: z.string().max(200).optional(),
     username: z.string().max(120).nullable().optional(),
 }).strict();
+const canonicalTelegramChannelSchema = telegramChannelSchema.extend({
+    workspaceIds: z.array(z.string()).max(50),
+    owned: z.boolean(),
+}).strict();
 const profileDisplayNameSchema = z.string().max(40).nullable();
 const timezoneSchema = z.string()
     .min(1)
@@ -346,7 +352,7 @@ function pickPage(items, max) {
     };
 }
 function randomId() {
-    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+    return randomUUID();
 }
 function imageStoragePath(eventId, uid, kind, imageId) {
     return `events/${eventId}/${uid}/images/${kind}/${imageId}/master.webp`;
@@ -631,6 +637,8 @@ function readCardsConfig(eventData) {
             imageUrl: safeString(item.imageUrl).trim() || null,
             imageMasterUrl: safeString(item.imageMasterUrl).trim() || null,
             imageVariants: readImageVariants(item.imageVariants),
+            imageWidth: typeof item.imageWidth === "number" ? item.imageWidth : null,
+            imageHeight: typeof item.imageHeight === "number" ? item.imageHeight : null,
             formId: safeString(item.formId).trim() || null,
         };
     });
@@ -702,6 +710,8 @@ function buildCardsItems({ inputs, existing, formIds, }) {
             imageUrl: previous?.imageUrl ?? null,
             imageMasterUrl: previous?.imageMasterUrl ?? null,
             imageVariants: previous?.imageVariants ?? null,
+            imageWidth: previous?.imageWidth ?? null,
+            imageHeight: previous?.imageHeight ?? null,
             formId,
         };
     });
@@ -814,49 +824,28 @@ async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
     const previous = readImageRef(event, kind, cardId);
     const sourceBuffer = await readImageSource(source);
     const masterBuffer = await compressToMasterWebp(sourceBuffer);
-    const imageId = kind === "card" ? cardId : randomUUID();
-    const masterPath = imageStoragePath(eventId, uid, kind, imageId);
     const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
     const deleteWarnings = [];
     let deletesAttempted = 0;
-    if (kind === "card" && previousMasterPath === masterPath) {
-        const variantPaths = variantPathsFromMasterPath(masterPath);
+    const expectedCardPath = kind === "card" ? imageStoragePath(eventId, uid, kind, cardId) : null;
+    if (expectedCardPath && previousMasterPath === expectedCardPath) {
+        const variantPaths = variantPathsFromMasterPath(expectedCardPath);
         deletesAttempted += variantPaths.length;
         deleteWarnings.push(...await deleteStoragePaths(eventId, variantPaths));
     }
-    let masterUrl = null;
+    let uploaded = null;
     try {
-        const uploaded = await uploadMasterImage(eventId, kind, cardId, masterBuffer);
-        masterUrl = uploaded.masterUrl;
-        if (kind === "promoBanner") {
-            await updateDoc(doc(firestore, "events", eventId), {
-                "blocks.promoBanner.imageMasterUrl": masterUrl,
-                "blocks.promoBanner.imageUrl": masterUrl,
-                "blocks.promoBanner.imageVariants": null,
-            });
-        }
-        else if (kind === "videoPlaceholder") {
-            await updateDoc(doc(firestore, "events", eventId), {
-                "blocks.video.placeholder.imageMasterUrl": masterUrl,
-                "blocks.video.placeholder.imageUrl": masterUrl,
-                "blocks.video.placeholder.imageVariants": null,
-            });
-        }
-        else {
-            await updateCardImageInTransaction(eventId, cardId, {
-                imageUrl: masterUrl,
-                imageMasterUrl: masterUrl,
-                imageVariants: null,
-            });
-        }
+        uploaded = await uploadMasterImage(eventId, kind, cardId, masterBuffer);
     }
     catch (err) {
-        if (masterUrl) {
-            await deleteStoragePaths(eventId, [masterPath, ...variantPathsFromMasterPath(masterPath)]).catch(() => []);
+        if (uploaded) {
+            await deleteStoragePaths(eventId, [uploaded.storagePath, ...variantPathsFromMasterPath(uploaded.storagePath)]).catch(() => []);
         }
         throw err;
     }
-    if (kind !== "card" || (previousMasterPath && previousMasterPath !== masterPath) || (!previous.imageMasterUrl && previous.imageUrl)) {
+    if (!uploaded)
+        throw new Error("Image upload did not return a result.");
+    if (kind !== "card" || (previousMasterPath && previousMasterPath !== uploaded.storagePath) || (!previous.imageMasterUrl && previous.imageUrl)) {
         const cleanup = await deleteStorageUrls(eventId, previous.imageMasterUrl, previous.imageUrl);
         deletesAttempted += cleanup.attempted;
         deleteWarnings.push(...cleanup.warnings);
@@ -864,12 +853,14 @@ async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
     return {
         eventId,
         kind,
-        imageId,
-        storagePath: masterPath,
-        masterUrl,
+        imageId: uploaded.imageId,
+        storagePath: uploaded.storagePath,
+        masterUrl: uploaded.masterUrl,
         variantsPending: true,
         sourceBytes: sourceBuffer.byteLength,
-        masterBytes: masterBuffer.byteLength,
+        masterBytes: uploaded.masterBytes,
+        imageWidth: uploaded.imageWidth,
+        imageHeight: uploaded.imageHeight,
         note: "Image master uploaded. CF generateImageVariants should publish thumb/card/hero variants and update imageUrl/imageVariants in about 10-30 seconds.",
         storageDeletesAttempted: deletesAttempted,
         storageDeleteWarnings: deleteWarnings,
@@ -955,6 +946,9 @@ async function readEvent(eventId, uid, mode = "read") {
         assertEventReadable(data, uid);
     else
         assertEventAccess(data, uid, mode);
+    if (data.trashedAt && mode !== "read" && mode !== "delete") {
+        throw new Error("Event is in trash. Restore it before making changes or live actions.");
+    }
     return data;
 }
 function asRecord(value) {
@@ -1112,16 +1106,11 @@ function initialEventAccess(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 });
+        const ensureRuntime = httpsCallable(functions, "ensureEventRuntime");
+        await ensureRuntime({ eventId: eventRef.id });
     }
     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;
+        console.error(`[OKO MCP] RTDB mirror deferred to onEventCreated for event ${eventRef.id}:`, error);
     }
     return eventRef;
 }
@@ -1160,7 +1149,7 @@ function normalizeWorkspacePermissions(value) {
     return out;
 }
 function randomInviteCode() {
-    return Math.random().toString(36).slice(2, 8).toUpperCase();
+    return randomBytes(8).toString("hex").toUpperCase();
 }
 function normalizeEmail(value) {
     return value.trim().toLowerCase();
@@ -1236,43 +1225,6 @@ function parseNmoParticipantsCsv(csv) {
         return parsed.data;
     });
 }
-async function readTelegramChannels(uid, includeWorkspaceChannels) {
-    const channelsById = new Map();
-    const profileSnap = await getDoc(doc(firestore, "userProfiles", uid));
-    const profileChannels = Array.isArray(profileSnap.data()?.telegramChannels) ? profileSnap.data()?.telegramChannels : [];
-    for (const raw of profileChannels) {
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            continue;
-        const ch = raw;
-        if (typeof ch.chatId !== "number")
-            continue;
-        channelsById.set(ch.chatId, { ...serialize(ch), source: "profile" });
-    }
-    if (includeWorkspaceChannels) {
-        const workspaces = await listVisibleWorkspaces(uid, true);
-        for (const workspace of workspaces) {
-            const workspaceId = safeString(workspace.id);
-            const workspaceName = safeString(workspace.name);
-            const channels = Array.isArray(workspace.telegramChannels) ? workspace.telegramChannels : [];
-            for (const raw of channels) {
-                if (!raw || typeof raw !== "object" || Array.isArray(raw))
-                    continue;
-                const ch = raw;
-                if (typeof ch.chatId !== "number")
-                    continue;
-                const prev = channelsById.get(ch.chatId) ?? {};
-                const visibleInWorkspaces = Array.isArray(prev.visibleInWorkspaces) ? prev.visibleInWorkspaces : [];
-                channelsById.set(ch.chatId, {
-                    ...prev,
-                    ...serialize(ch),
-                    source: prev.source ? "profile+workspace" : "workspace",
-                    visibleInWorkspaces: [...visibleInWorkspaces, { id: workspaceId, name: workspaceName }],
-                });
-            }
-        }
-    }
-    return [...channelsById.values()].sort((a, b) => safeString(a.title).localeCompare(safeString(b.title)));
-}
 async function listVisibleWorkspaces(uid, includeShared) {
     const out = [];
     const ownedSnap = await getDocs(query(collection(firestore, "workspaces"), where("ownerId", "==", uid)));
@@ -1291,34 +1243,6 @@ async function listVisibleWorkspaces(uid, includeShared) {
     }
     return out;
 }
-async function syncTelegramChannelToWorkspaces(uid, channel, workspaceIds) {
-    const updated = [];
-    if (workspaceIds.length === 0)
-        return updated;
-    const profileRef = doc(firestore, "userProfiles", uid);
-    const profileSnap = await getDoc(profileRef);
-    const channels = Array.isArray(profileSnap.data()?.telegramChannels) ? [...profileSnap.data().telegramChannels] : [];
-    const nextProfileChannels = channels.map((item) => {
-        if (item.chatId !== channel.chatId)
-            return item;
-        const current = Array.isArray(item.workspaceIds) ? item.workspaceIds.filter((id) => typeof id === "string") : [];
-        return { ...item, workspaceIds: [...new Set([...current, ...workspaceIds])] };
-    });
-    await setDoc(profileRef, { telegramChannels: nextProfileChannels }, { merge: true });
-    for (const workspaceId of workspaceIds) {
-        await readWorkspaceForOwner(workspaceId, uid);
-        const wsRef = doc(firestore, "workspaces", workspaceId);
-        const wsSnap = await getDoc(wsRef);
-        const wsChannels = Array.isArray(wsSnap.data()?.telegramChannels) ? wsSnap.data().telegramChannels : [];
-        if (!wsChannels.some((item) => item.chatId === channel.chatId)) {
-            await updateDoc(wsRef, {
-                telegramChannels: [...wsChannels, { chatId: channel.chatId, title: channel.title ?? "", username: channel.username ?? null }],
-            });
-            updated.push(workspaceId);
-        }
-    }
-    return updated;
-}
 async function readAgg(eventId) {
     const snap = await get(ref(rtdb, `events/${eventId}/agg`));
     const agg = (snap.val() ?? {});
@@ -2171,7 +2095,10 @@ export function registerTools(server) {
         outputSchema: updateOutputSchema,
         annotations: writeTool,
     }, async (args) => {
-        const { uid } = await authed(["setup:write"]);
+        const requiredScopes = ["setup:write"];
+        if (args.nmo !== undefined)
+            requiredScopes.push("nmo:write");
+        const { uid } = await authed(requiredScopes);
         await readEvent(args.eventId, uid, "edit");
         const patch = {};
         if (args.chat?.enabled !== undefined)
@@ -2489,6 +2416,8 @@ export function registerTools(server) {
                 "blocks.promoBanner.imageMasterUrl": deleteField(),
                 "blocks.promoBanner.imageUrl": deleteField(),
                 "blocks.promoBanner.imageVariants": deleteField(),
+                "blocks.promoBanner.imageWidth": deleteField(),
+                "blocks.promoBanner.imageHeight": deleteField(),
             });
         }
         else if (kind === "videoPlaceholder") {
@@ -2496,6 +2425,8 @@ export function registerTools(server) {
                 "blocks.video.placeholder.imageMasterUrl": deleteField(),
                 "blocks.video.placeholder.imageUrl": deleteField(),
                 "blocks.video.placeholder.imageVariants": deleteField(),
+                "blocks.video.placeholder.imageWidth": deleteField(),
+                "blocks.video.placeholder.imageHeight": deleteField(),
             });
         }
         else {
@@ -2503,6 +2434,8 @@ export function registerTools(server) {
                 imageUrl: null,
                 imageMasterUrl: null,
                 imageVariants: null,
+                imageWidth: null,
+                imageHeight: null,
             });
         }
         return textResult({
@@ -2515,25 +2448,92 @@ export function registerTools(server) {
         });
     });
     server.registerTool("oko_delete_event", {
-        title: "Delete event",
+        title: "Move event to trash",
         description: toolDescription({
-            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 and cross-store cleanup counts.",
-            examples: ["Use only after the user explicitly confirms the exact event title/id."],
-            notes: ["Destructive. The server validates the current per-event delete capability and performs idempotent cross-store cleanup."],
+            summary: "Move an OKO event to the 30-day trash. This compatibility alias has the same behavior as oko_trash_event.",
+            args: ["eventId: event to move to trash.", "confirm: must be true."],
+            returns: "trashed event id and purge deadline in epoch milliseconds.",
+            examples: ["Use after showing the exact event title and asking the organizer to confirm moving it to trash."],
+            notes: ["Recoverable for 30 days with oko_restore_event. This does not create an event lifecycle status."],
         }),
-        inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true for deletion.") },
-        outputSchema: z.object({ deleted: z.string() }).passthrough(),
+        inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true to move the event to trash.") },
+        outputSchema: z.object({ trashed: z.string(), purgeAfter: z.number().nullable() }).passthrough(),
         annotations: destructiveTool,
     }, async ({ eventId, confirm }) => {
         const { uid } = await authed(["events:delete"]);
         const data = await readEvent(eventId, uid, "delete");
         requireConfirm(confirm, "oko_delete_event", { eventId, title: data.title });
-        const deleteEvent = httpsCallable(functions, "deleteEventCompletely");
-        const result = await deleteEvent({ eventId });
+        const trash = httpsCallable(functions, "trashEvent");
+        const result = await trash({ eventId });
         return textResult(result.data);
     });
+    server.registerTool("oko_trash_event", {
+        title: "Move event to trash",
+        description: toolDescription({
+            summary: "Move an OKO event to the recoverable 30-day trash.",
+            args: ["eventId: event to move to trash.", "confirm: must be true."],
+            returns: "trashed event id and purge deadline in epoch milliseconds.",
+            examples: ["Use after showing the exact event title and asking the organizer to confirm moving it to trash."],
+            notes: ["End any active analytics session first. Restore with oko_restore_event before the purge deadline."],
+        }),
+        inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true to move the event to trash.") },
+        outputSchema: z.object({ trashed: z.string(), purgeAfter: z.number().nullable() }).passthrough(),
+        annotations: destructiveTool,
+    }, async ({ eventId, confirm }) => {
+        const { uid } = await authed(["events:delete"]);
+        const event = await readEvent(eventId, uid, "delete");
+        requireConfirm(confirm, "oko_trash_event", { eventId, title: event.title });
+        const trash = httpsCallable(functions, "trashEvent");
+        return textResult((await trash({ eventId })).data);
+    });
+    server.registerTool("oko_restore_event", {
+        title: "Restore event",
+        description: toolDescription({
+            summary: "Restore an OKO event from the 30-day trash before its purge deadline.",
+            args: ["eventId: trashed event to restore."],
+            returns: "restored event id.",
+            examples: ["Use when the organizer asks to undo a trash action."],
+            notes: ["Idempotent. Fails after the trash retention deadline has expired."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: z.object({ restored: z.string() }).passthrough(),
+        annotations: idempotentWriteTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:delete"]);
+        await readEvent(eventId, uid, "delete");
+        const restore = httpsCallable(functions, "restoreEvent");
+        return textResult((await restore({ eventId })).data);
+    });
+    server.registerTool("oko_delete_event_permanently", {
+        title: "Delete event permanently",
+        description: toolDescription({
+            summary: "Permanently delete a trashed OKO event and all associated Firestore, RTDB, chat, Storage, participant, session, and Telegram data.",
+            args: [
+                "eventId: trashed event to delete permanently.",
+                "confirmTitle: exact current event title, including case and spacing.",
+                "confirm: must be true.",
+            ],
+            returns: "deleted event id and cross-store cleanup counts.",
+            examples: ["Read the event first, show its exact title, and proceed only after the organizer explicitly types or confirms that exact title."],
+            notes: ["Irreversible. The event must already be in trash; use oko_trash_event first."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            confirmTitle: z.string().max(500).describe("Exact current event title."),
+            confirm: z.boolean().optional().describe("Required true for permanent deletion."),
+        },
+        outputSchema: z.object({ deleted: z.string(), cleanup: unknownRecordSchema }).passthrough(),
+        annotations: destructiveTool,
+    }, async ({ eventId, confirmTitle, confirm }) => {
+        const { uid } = await authed(["events:delete"]);
+        const event = await readEvent(eventId, uid, "delete");
+        const title = safeString(event.title);
+        if (confirmTitle !== title)
+            throw new Error("confirmTitle must exactly match the current event title.");
+        requireConfirm(confirm, "oko_delete_event_permanently", { eventId, title });
+        const remove = httpsCallable(functions, "deleteEventCompletely");
+        return textResult((await remove({ eventId, confirmTitle })).data);
+    });
     server.registerTool("oko_duplicate_event", {
         title: "Duplicate event",
         description: toolDescription({
@@ -2552,6 +2552,8 @@ export function registerTools(server) {
     }, async ({ eventId, targetWorkspaceId }) => {
         const { uid } = await authed(["events:write"]);
         const source = await readEvent(eventId, uid, "read");
+        if (source.nmoMode === true)
+            await authed(["nmo:write"]);
         const workspaceId = targetWorkspaceId ?? safeString(source.workspaceId, uid);
         await assertCanCreateInWorkspace(uid, workspaceId);
         const newRef = await addEventWithRtdbMirror(uid, workspaceId, {
@@ -3191,7 +3193,13 @@ export function registerTools(server) {
         requireConfirm(confirm, "oko_send_chat_message", { eventId, name, text });
         const role = await getChatRole(eventId, uid);
         const msgRef = push(ref(chatRtdb, `messages/${eventId}`));
-        await set(msgRef, { text, uid, name, role, ts: rtdbServerTimestamp() });
+        if (!msgRef.key)
+            throw new Error("Could not allocate chat message id");
+        const timestamp = rtdbServerTimestamp();
+        await update(ref(chatRtdb), {
+            [`messages/${eventId}/${msgRef.key}`]: { text, uid, name, role, ts: timestamp },
+            [`rate_limits/${eventId}/${uid}`]: { ts: timestamp, messageId: msgRef.key },
+        });
         await runTransaction(ref(rtdb, `events/${eventId}/agg/chatMessages`), (n) => (n ?? 0) + 1);
         return textResult({ eventId, messageId: msgRef.key, sent: true });
     });
@@ -3656,20 +3664,48 @@ export function registerTools(server) {
         await Promise.all(ids.map((id) => updateDoc(doc(firestore, "userNotifications", uid, "items", id), { read: true })));
         return textResult({ markedRead: ids.length, notificationIds: ids });
     });
+    server.registerTool("oko_create_telegram_link", {
+        title: "Link personal Telegram",
+        description: toolDescription({
+            summary: "Create a short-lived Telegram deep link that binds the organizer's personal Telegram identity to OKO.",
+            args: [],
+            returns: "@OKOStreamBot link and expiry in seconds.",
+            examples: ["Open the returned link in the organizer's Telegram account before claiming a channel."],
+            notes: ["The link expires in 15 minutes and can be used only once. Opening it is a user action outside MCP."],
+        }),
+        inputSchema: {},
+        outputSchema: z.object({ url: z.string().url(), expiresIn: z.number().int().positive() }).passthrough(),
+        annotations: writeTool,
+    }, async () => {
+        await authed(["telegram:write"]);
+        const createLink = httpsCallable(functions, "createTelegramLink");
+        return textResult((await createLink({})).data);
+    });
     server.registerTool("oko_list_telegram_channels", {
         title: "List Telegram channels",
         description: toolDescription({
             summary: "List Telegram channels available to the authenticated organizer.",
-            args: ["includeWorkspaceChannels: include channels exposed through visible workspaces, default true."],
-            returns: "channels with chatId, title, username, source, and visible workspace metadata.",
+            args: [
+                "eventId: optional event; when provided, include channels explicitly shared to that event's workspace.",
+                "includeWorkspaceChannels: deprecated compatibility field; eventId is required to resolve workspace sharing safely.",
+            ],
+            returns: "canonical channels with chatId, title, username, workspaceIds, and owned flag.",
             examples: ["Use before oko_publish_telegram_post so the user can choose a channel by title instead of numeric id."],
         }),
-        inputSchema: { includeWorkspaceChannels: z.boolean().default(true).describe("Include workspace-level channels visible to this organizer.") },
+        inputSchema: {
+            eventId: eventIdField.optional().describe("Optional event used to include channels shared to its workspace."),
+            includeWorkspaceChannels: z.boolean().optional().describe("Deprecated; retained for client compatibility."),
+        },
         outputSchema: telegramChannelsOutputSchema,
         annotations: readOnlyTool,
-    }, async ({ includeWorkspaceChannels }) => {
-        const { uid } = await authed(["telegram:write"]);
-        const channels = await readTelegramChannels(uid, includeWorkspaceChannels);
+    }, async ({ eventId }) => {
+        await authed(["telegram:write"]);
+        const listChannels = httpsCallable(functions, "listTelegramChannels");
+        const result = await listChannels(eventId ? { eventId } : {});
+        const parsed = z.array(canonicalTelegramChannelSchema).safeParse(result.data.channels);
+        if (!parsed.success)
+            throw new Error("OKO listTelegramChannels returned an invalid channel payload.");
+        const channels = parsed.data.sort((a, b) => (a.title ?? "").localeCompare(b.title ?? ""));
         return textResult({ channels, count: channels.length });
     });
     server.registerTool("oko_claim_telegram_channel", {
@@ -3678,12 +3714,12 @@ export function registerTools(server) {
             summary: "Claim a pending Telegram channel using the code sent by OKO bot.",
             args: [
                 "claimCode: code posted by the bot after it was added to a channel.",
-                "workspaceIds: optional workspaces to expose this channel to after claim.",
+                "workspaceIds: optional owned workspaces to expose this channel to after claim.",
                 "confirm: must be true.",
             ],
             returns: "claimed channel and workspace ids updated.",
-            examples: ["Add @OKOStreamBot to a Telegram channel, copy the claim code, then call this tool."],
-            notes: ["Workspace sync requires the authenticated organizer to own each workspace."],
+            examples: ["Link personal Telegram first, add @OKOStreamBot as channel administrator, copy the claim code, then call this tool."],
+            notes: ["The linked personal Telegram user must be a channel administrator. Workspace sharing is server-validated."],
         }),
         inputSchema: {
             claimCode: z.string().min(4).max(32).describe("Telegram channel claim code."),
@@ -3693,7 +3729,7 @@ export function registerTools(server) {
         outputSchema: z.object({ channel: unknownRecordSchema, workspaceIdsUpdated: z.array(z.string()) }).passthrough(),
         annotations: writeTool,
     }, async ({ claimCode, workspaceIds, confirm }) => {
-        const { uid } = await authed(["telegram:write"]);
+        await authed(["telegram:write"]);
         requireConfirm(confirm, "oko_claim_telegram_channel", { workspaceIds: workspaceIds.join(",") });
         const claimChannel = httpsCallable(functions, "claimTelegramChannel");
         const result = await claimChannel({ code: claimCode.trim().toUpperCase() });
@@ -3702,8 +3738,54 @@ export function registerTools(server) {
         const parsed = telegramChannelSchema.safeParse(channelRaw);
         if (!parsed.success)
             throw new Error("OKO claimTelegramChannel returned an invalid channel payload.");
-        const workspaceIdsUpdated = await syncTelegramChannelToWorkspaces(uid, parsed.data, workspaceIds);
-        return textResult({ ...data, channel: parsed.data, workspaceIdsUpdated });
+        if (workspaceIds.length > 0) {
+            const setWorkspaces = httpsCallable(functions, "setTelegramChannelWorkspaces");
+            await setWorkspaces({ channelId: parsed.data.chatId, workspaceIds });
+        }
+        return textResult({ ...data, channel: parsed.data, workspaceIdsUpdated: workspaceIds });
+    });
+    server.registerTool("oko_set_telegram_channel_workspaces", {
+        title: "Share Telegram channel to workspaces",
+        description: toolDescription({
+            summary: "Replace the owned Telegram channel's explicit OKO workspace sharing list.",
+            args: ["channelId: owned Telegram channel id.", "workspaceIds: complete replacement list, up to 50.", "confirm: must be true."],
+            returns: "channel id and the applied workspace ids.",
+            examples: ["Use an empty workspaceIds list to make the channel private to its owner again."],
+            notes: ["This replaces, rather than appends to, the current sharing list. Every workspace must be owned by the organizer."],
+        }),
+        inputSchema: {
+            channelId: z.number().int().describe("Owned Telegram channel id."),
+            workspaceIds: z.array(z.string().min(1).max(128)).max(50).describe("Complete replacement workspace sharing list."),
+            confirm: z.boolean().optional().describe("Required true to change workspace sharing."),
+        },
+        outputSchema: z.object({ success: z.boolean(), channelId: z.number().int(), workspaceIds: z.array(z.string()) }).passthrough(),
+        annotations: writeTool,
+    }, async ({ channelId, workspaceIds, confirm }) => {
+        await authed(["telegram:write"]);
+        requireConfirm(confirm, "oko_set_telegram_channel_workspaces", { channelId, workspaceIds: workspaceIds.join(",") });
+        const setWorkspaces = httpsCallable(functions, "setTelegramChannelWorkspaces");
+        return textResult((await setWorkspaces({ channelId, workspaceIds })).data);
+    });
+    server.registerTool("oko_disconnect_telegram_channel", {
+        title: "Disconnect Telegram channel",
+        description: toolDescription({
+            summary: "Disconnect an owned Telegram channel from OKO and clear all workspace sharing.",
+            args: ["channelId: owned Telegram channel id.", "confirm: must be true."],
+            returns: "disconnected channel id.",
+            examples: ["Use only after showing the exact channel selected from oko_list_telegram_channels."],
+            notes: ["Existing sent Telegram messages are not deleted. The channel must be claimed again before future publication."],
+        }),
+        inputSchema: {
+            channelId: z.number().int().describe("Owned Telegram channel id."),
+            confirm: z.boolean().optional().describe("Required true to disconnect the channel."),
+        },
+        outputSchema: z.object({ success: z.boolean(), channelId: z.number().int() }).passthrough(),
+        annotations: destructiveTool,
+    }, async ({ channelId, confirm }) => {
+        await authed(["telegram:write"]);
+        requireConfirm(confirm, "oko_disconnect_telegram_channel", { channelId });
+        const disconnect = httpsCallable(functions, "disconnectTelegramChannel");
+        return textResult((await disconnect({ channelId })).data);
     });
     server.registerTool("oko_list_telegram_posts", {
         title: "List Telegram posts",
@@ -3757,14 +3839,18 @@ export function registerTools(server) {
         outputSchema: z.object({ postId: z.string(), canceled: z.boolean() }).passthrough(),
         annotations: destructiveTool,
     }, async ({ postId, confirm }) => {
-        await authed(["telegram:write"]);
+        const { uid } = await authed(["telegram:write"]);
         const postRef = doc(firestore, "telegramPosts", postId);
         const postSnap = await getDoc(postRef);
         if (!postSnap.exists())
             throw new Error("Telegram post not found.");
         const post = postSnap.data();
-        if (post.status === "sent")
-            throw new Error("Telegram post was already sent and cannot be canceled through OKO.");
+        if (typeof post.eventId !== "string")
+            throw new Error("Telegram post has no valid event.");
+        await readEvent(post.eventId, uid, "notify");
+        if (!["draft", "pending", "scheduled", "failed"].includes(safeString(post.status))) {
+            throw new Error("Only draft, pending, scheduled, or failed Telegram posts can be canceled. A sent or delivery-unknown post must be reviewed manually.");
+        }
         requireConfirm(confirm, "oko_cancel_telegram_post", { postId, eventId: post.eventId, status: post.status, caption: post.caption });
         await deleteDoc(postRef);
         return textResult({ postId, eventId: post.eventId, status: post.status, canceled: true });
@@ -3799,10 +3885,19 @@ export function registerTools(server) {
     }, async (args) => {
         const { uid } = await authed(["telegram:write"]);
         await readEvent(args.eventId, uid, "notify");
+        const listChannels = httpsCallable(functions, "listTelegramChannels");
+        const availableResult = await listChannels({ eventId: args.eventId });
+        const available = z.array(canonicalTelegramChannelSchema).safeParse(availableResult.data.channels);
+        if (!available.success)
+            throw new Error("OKO listTelegramChannels returned an invalid channel payload.");
+        const channel = available.data.find((item) => item.chatId === args.channelId);
+        if (!channel)
+            throw new Error("Telegram channel is not available for this event. List channels with this eventId and choose a returned channel.");
         const scheduled = !!args.scheduleAt;
         requireConfirm(args.confirm, "oko_publish_telegram_post", {
             eventId: args.eventId,
             channelId: args.channelId,
+            channelTitle: channel.title ?? "",
             caption: args.caption,
             scheduleAt: args.scheduleAt ?? null,
         });
@@ -3811,6 +3906,7 @@ export function registerTools(server) {
             ownerId: uid,
             ownerEmail: "",
             channelId: args.channelId,
+            channelKey: String(args.channelId),
             caption: args.caption.trim(),
             imageUrl: args.imageUrl?.trim() || null,
             buttons: args.buttonLabel?.trim() ? [{ label: args.buttonLabel.trim(), url: args.buttonUrl?.trim() || eventUrl(args.eventId) }] : [],

package/package.json

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