@okostream/mcp 0.2.0 → 0.3.0

package/README.md

@@ -54,8 +54,9 @@ Every tool returns JSON text plus MCP `structuredContent`. List-like tools use b
 
 - `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_workspace_access`, `oko_list_workspace_invites`, and `oko_list_telegram_posts` support pagination.
+- `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.
 - 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.
@@ -92,7 +93,8 @@ 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_get_live_state`, `oko_get_analytics`, `oko_list_recent_chat`, `oko_list_participants`, `oko_list_leads`
+- `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:
 
@@ -128,7 +130,9 @@ Dangerous or external side-effect tools require `confirm: true`.
 6. `oko_start_session` -> `oko_fix_orphan_session` -> `oko_delete_session` should leave no active session pointers on a disposable test event.
 7. `oko_duplicate_event`, workspace tools, and `oko_move_event` should preserve Firestore access rules and RTDB owner/workspace mirrors.
 8. `oko_import_nmo_participants` should call CF24 and return per-row results; clean up test participants after import.
-9. `oko_get_analytics` should read an existing event with analytics sessions.
+9. `oko_get_session_report` should return markdown and structured session data for a completed session.
+10. `oko_list_notifications` -> `oko_mark_notifications_read` should read and clear an own disposable notification.
+11. `oko_get_analytics` should read an existing event with analytics sessions.
 
 CLI help:
 

package/dist/server.js

@@ -22,7 +22,7 @@ if (process.argv.includes("--help")) {
 }
 const server = new McpServer({
     name: "oko-mcp-server",
-    version: "0.2.0",
+    version: "0.3.0",
 });
 registerTools(server);
 const transport = new StdioServerTransport();

package/dist/tools.js

@@ -163,6 +163,32 @@ const nmoImportOutputSchema = z.object({
     summary: unknownRecordSchema,
     results: z.array(unknownRecordSchema),
 }).passthrough();
+const sessionReportOutputSchema = z.object({
+    eventId: z.string(),
+    sessionId: z.string(),
+    reportUrl: z.string().url(),
+    markdown: z.string(),
+    session: unknownRecordSchema,
+}).passthrough();
+const profileOutputSchema = z.object({
+    uid: z.string(),
+    profile: unknownRecordSchema,
+    updated: z.array(z.string()),
+}).passthrough();
+const deleteLeadOutputSchema = z.object({
+    eventId: z.string(),
+    leadId: z.string(),
+    deleted: z.boolean(),
+}).passthrough();
+const notificationsOutputSchema = z.object({
+    notifications: z.array(unknownRecordSchema),
+    unreadCountOnPage: z.number().int().nonnegative(),
+    ...cursorMetaSchema,
+}).passthrough();
+const notificationsMarkOutputSchema = z.object({
+    markedRead: z.number().int().nonnegative(),
+    notificationIds: z.array(z.string()),
+}).passthrough();
 const formFieldSchema = z.object({
     id: z.string().min(1).optional(),
     label: z.string().max(120),
@@ -209,6 +235,11 @@ const telegramChannelSchema = z.object({
     title: z.string().max(200).optional(),
     username: z.string().max(120).nullable().optional(),
 }).strict();
+const profileDisplayNameSchema = z.string().max(40).nullable();
+const timezoneSchema = z.string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9_+./-]+$/, "Use an IANA timezone such as Europe/Moscow or UTC.");
 const cardsConfigOutputSchema = z.object({
     eventId: z.string(),
     updated: z.array(z.string()),
@@ -685,6 +716,9 @@ function setupUrl(eventId) {
 function analyticsUrl(eventId) {
     return `https://okostream.app/analytics/${eventId}`;
 }
+function sessionReportUrl(eventId, sessionId) {
+    return `${analyticsUrl(eventId)}/report/${sessionId}`;
+}
 function nmoRegisterUrl(eventId) {
     return `${eventUrl(eventId)}/register`;
 }
@@ -1200,6 +1234,70 @@ function compactAnalyticsSession(raw, options) {
     }
     return session;
 }
+function numberMetric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function formatSeconds(value) {
+    const seconds = numberMetric(value);
+    if (seconds == null)
+        return "n/a";
+    const total = Math.max(0, Math.round(seconds));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${String(m).padStart(2, "0")}m ${String(s).padStart(2, "0")}s`;
+    return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+function formatDateTime(value) {
+    const millis = toMillis(value);
+    if (millis == null)
+        return "n/a";
+    return new Date(millis).toISOString();
+}
+function markdownMetric(label, value, suffix = "") {
+    const metric = value === null || value === undefined || value === "" ? "n/a" : String(value);
+    return `- ${label}: ${metric}${suffix}`;
+}
+function sessionReportMarkdown({ eventId, event, sessionId, session, }) {
+    const lines = [
+        `# OKO session report`,
+        "",
+        `Event: ${safeString(event.title, eventId)}`,
+        `Event URL: ${eventUrl(eventId)}`,
+        `Report URL: ${sessionReportUrl(eventId, sessionId)}`,
+        `Session: ${sessionId}`,
+        "",
+        "## Timing",
+        markdownMetric("Started", formatDateTime(session.startedAt)),
+        markdownMetric("Ended", formatDateTime(session.endedAt)),
+        markdownMetric("Duration", formatSeconds(session.durationSec)),
+        "",
+        "## Audience",
+        markdownMetric("Peak viewers", session.peakViewers),
+        markdownMetric("Unique visitors", session.uniqueVisitors),
+        markdownMetric("Views", session.viewCount),
+        markdownMetric("Average watch time", formatSeconds(session.avgTimeSec)),
+        markdownMetric("Median watch time", formatSeconds(session.medianTimeSec)),
+        "",
+        "## Engagement",
+        markdownMetric("Chat messages", session.chatMessages),
+        markdownMetric("Banner impressions", session.bannerImpressions),
+        markdownMetric("Banner clicks", session.bannerClicks),
+        markdownMetric("Banner CTR", session.bannerCtr, session.bannerCtr == null ? "" : "%"),
+        markdownMetric("CTA clicks", session.ctaClicks),
+        markdownMetric("Cards clicks", session.cardsClicks),
+    ];
+    const nmo = session.nmoEvaluation;
+    if (nmo && typeof nmo === "object" && !Array.isArray(nmo)) {
+        const summary = nmo.summary;
+        if (summary && typeof summary === "object" && !Array.isArray(summary)) {
+            const s = summary;
+            lines.push("", "## NMO", markdownMetric("Passed", s.passed), markdownMetric("Failed", s.failed), markdownMetric("No-show", s.noShow), markdownMetric("Total", s.total));
+        }
+    }
+    return lines.join("\n");
+}
 export function registerTools(server) {
     server.registerTool("oko_whoami", {
         title: "Who am I",
@@ -1217,6 +1315,39 @@ export function registerTools(server) {
         const auth = await authed([]);
         return textResult({ uid: auth.uid, scopes: currentScopes() });
     });
+    server.registerTool("oko_update_profile", {
+        title: "Update profile",
+        description: toolDescription({
+            summary: "Update the authenticated organizer profile fields used by OKO UI.",
+            args: [
+                "displayName: optional display name, max 40 chars; null clears it.",
+                "timezone: optional IANA timezone such as Europe/Moscow or UTC.",
+            ],
+            returns: "uid, updated field names, and the resulting profile snapshot.",
+            examples: ["Use when the organizer asks to change their visible OKO name or timezone."],
+            notes: ["This edits only the current organizer's own userProfiles document and does not require extra workspace/event scopes."],
+        }),
+        inputSchema: {
+            displayName: profileDisplayNameSchema.optional().describe("Display name, max 40 chars. Null clears it."),
+            timezone: timezoneSchema.optional().describe("IANA timezone, for example Europe/Moscow or UTC."),
+        },
+        outputSchema: profileOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ displayName, timezone }) => {
+        const { uid } = await authed([]);
+        const patch = { updatedAt: serverTimestamp() };
+        if (displayName !== undefined)
+            patch.displayName = displayName?.trim() || null;
+        if (timezone !== undefined)
+            patch.timezone = timezone.trim();
+        const updated = Object.keys(patch).filter((key) => key !== "updatedAt");
+        if (updated.length === 0)
+            throw new Error("Provide displayName and/or timezone.");
+        const profileRef = doc(firestore, "userProfiles", uid);
+        await setDoc(profileRef, patch, { merge: true });
+        const profileSnap = await getDoc(profileRef);
+        return textResult({ uid, updated, profile: profileSnap.exists() ? serialize(profileSnap.data()) : {} });
+    });
     server.registerTool("oko_list_workspaces", {
         title: "List workspaces",
         description: toolDescription({
@@ -2505,6 +2636,65 @@ export function registerTools(server) {
         const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().startedAt) : null;
         return textResult({ sessions, ...cursorMeta(sessions.length, max, hasMore, nextCursor) }, { truncationHint: "Use limit/cursor or keep includeTimeline/includeSnapshots/includeNmoRows disabled." });
     });
+    server.registerTool("oko_get_session_report", {
+        title: "Get session report",
+        description: toolDescription({
+            summary: "Build a ready-to-share report for one analytics session, with compact structured data and markdown.",
+            args: [
+                "eventId: event to inspect.",
+                "sessionId: optional analytics session id; omitted means latest session.",
+                "includeTimeline: include recent timeline buckets; default false.",
+                "timelineLimit: max timeline buckets when includeTimeline=true.",
+                "includeSnapshots: include baseline/final snapshots; default false.",
+                "includeNmoRows: include full NMO participant rows; default false.",
+            ],
+            returns: "event/session ids, report URL, markdown summary, event summary, and compact session object.",
+            examples: ["Use after a webinar when the user asks for the finished session report without manually opening the report page."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            sessionId: z.string().min(1).optional().describe("analyticsSessions document id. Omit to use the latest session."),
+            includeTimeline: z.boolean().default(false).describe("Include recent timeline buckets."),
+            timelineLimit: z.number().int().min(1).max(500).default(ANALYTICS_TIMELINE_DEFAULT_LIMIT).describe("Max timeline buckets when includeTimeline=true."),
+            includeSnapshots: z.boolean().default(false).describe("Include baselineSnapshot and finalSnapshot."),
+            includeNmoRows: z.boolean().default(false).describe("Include full NMO participant rows when present."),
+        },
+        outputSchema: sessionReportOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, sessionId, includeTimeline, timelineLimit, includeSnapshots, includeNmoRows }) => {
+        const { uid } = await authed(["analytics:read"]);
+        const event = await readEvent(eventId, uid, "read");
+        let resolvedSessionId = sessionId;
+        let sessionData = null;
+        if (resolvedSessionId) {
+            const sessionSnap = await getDoc(doc(firestore, "events", eventId, "analyticsSessions", resolvedSessionId));
+            if (!sessionSnap.exists())
+                throw new Error("Analytics session not found.");
+            sessionData = sessionSnap.data();
+        }
+        else {
+            const snap = await getDocs(query(collection(firestore, "events", eventId, "analyticsSessions"), orderBy("startedAt", "desc"), limit(1)));
+            const first = snap.docs[0];
+            if (!first)
+                throw new Error("No analytics sessions found for this event.");
+            resolvedSessionId = first.id;
+            sessionData = first.data();
+        }
+        const session = compactAnalyticsSession({ id: resolvedSessionId, ...sessionData }, { includeTimeline, timelineLimit, includeSnapshots, includeNmoRows });
+        const markdown = sessionReportMarkdown({ eventId, event, sessionId: resolvedSessionId, session });
+        return textResult({
+            eventId,
+            sessionId: resolvedSessionId,
+            event: {
+                id: eventId,
+                title: safeString(event.title, eventId),
+                ...eventLinks(eventId, event),
+            },
+            reportUrl: sessionReportUrl(eventId, resolvedSessionId),
+            markdown,
+            session,
+        }, { truncationHint: "Keep includeTimeline/includeSnapshots/includeNmoRows disabled or lower timelineLimit." });
+    });
     server.registerTool("oko_list_recent_chat", {
         title: "List recent chat",
         description: toolDescription({
@@ -2910,6 +3100,108 @@ export function registerTools(server) {
         }
         return textResult({ leads, ...meta });
     });
+    server.registerTool("oko_delete_lead", {
+        title: "Delete form lead",
+        description: toolDescription({
+            summary: "Delete one lead/form submission from an event.",
+            args: ["eventId: event id.", "leadId: events/{eventId}/leads document id.", "confirm: must be true."],
+            returns: "eventId, leadId, deleted=true, and a small preview of the deleted lead.",
+            examples: ["Use after listing leads and confirming the exact submission to remove."],
+            notes: ["Destructive. Requires setup:write in addition to leads:read so read-only keys cannot delete leads."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            leadId: z.string().min(1).max(160).describe("Lead document id under events/{eventId}/leads."),
+            confirm: z.boolean().optional().describe("Required true for lead deletion."),
+        },
+        outputSchema: deleteLeadOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, leadId, confirm }) => {
+        const { uid } = await authed(["leads:read", "setup:write"]);
+        await readEvent(eventId, uid, "edit");
+        const leadRef = doc(firestore, "events", eventId, "leads", leadId);
+        const leadSnap = await getDoc(leadRef);
+        if (!leadSnap.exists())
+            throw new Error("Lead not found.");
+        const lead = serialize(leadSnap.data());
+        requireConfirm(confirm, "oko_delete_lead", { eventId, leadId, formId: lead.formId, source: lead.source, submittedAt: lead.submittedAt });
+        await deleteDoc(leadRef);
+        return textResult({ eventId, leadId, deleted: true, leadPreview: lead });
+    });
+    server.registerTool("oko_list_notifications", {
+        title: "List notifications",
+        description: toolDescription({
+            summary: "List in-app notifications for the authenticated organizer.",
+            args: [
+                "unreadOnly: only unread notifications, default false.",
+                "limit: max notifications, default 20, max 100.",
+                "cursor: createdAt cursor returned as nextCursor by the previous page.",
+            ],
+            returns: "notifications plus unreadCountOnPage and cursor pagination metadata.",
+            examples: ["Use when the organizer asks what changed in OKO or what notifications are waiting."],
+        }),
+        inputSchema: {
+            unreadOnly: z.boolean().default(false).describe("Return only unread notifications."),
+            limit: limitField(100, 20),
+            cursor: cursorField,
+        },
+        outputSchema: notificationsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ unreadOnly, limit: max, cursor }) => {
+        const { uid } = await authed(["workspace:read"]);
+        const fetchLimit = unreadOnly ? Math.min(max * 5 + 1, 501) : max + 1;
+        const constraints = [
+            orderBy("createdAt", "desc"),
+            limit(fetchLimit),
+        ];
+        if (cursor)
+            constraints.splice(1, 0, startAfter(parseTimestampCursor(cursor)));
+        const snap = await getDocs(query(collection(firestore, "userNotifications", uid, "items"), ...constraints));
+        const matchingDocs = unreadOnly ? snap.docs.filter((item) => item.data().read !== true) : snap.docs;
+        const { page, hasMore: hasMoreInMatches } = pickPage(matchingDocs, max);
+        const hasMore = hasMoreInMatches || snap.docs.length >= fetchLimit;
+        const cursorSource = hasMoreInMatches ? page.at(-1) : snap.docs.at(-1);
+        const notifications = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
+        const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt) : null;
+        return textResult({
+            notifications,
+            unreadCountOnPage: notifications.filter((item) => item.read !== true).length,
+            ...cursorMeta(notifications.length, max, hasMore, nextCursor),
+        });
+    });
+    server.registerTool("oko_mark_notifications_read", {
+        title: "Mark notifications read",
+        description: toolDescription({
+            summary: "Mark own OKO in-app notifications as read.",
+            args: [
+                "notificationIds: optional explicit notification ids, max 100.",
+                "allUnread: true to mark unread notifications on the first page, max controlled by limit.",
+                "limit: when allUnread=true, max unread notifications to mark, default 100, max 200.",
+            ],
+            returns: "markedRead count and notification ids updated.",
+            examples: ["Use after oko_list_notifications when the user asks to clear the bell/unread state."],
+            notes: ["Provide either notificationIds or allUnread=true. This can update only the current organizer's own notifications."],
+        }),
+        inputSchema: {
+            notificationIds: z.array(z.string().min(1).max(160)).max(100).optional().describe("Specific notification document ids."),
+            allUnread: z.boolean().default(false).describe("Mark unread notifications as read."),
+            limit: limitField(200, 100),
+        },
+        outputSchema: notificationsMarkOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ notificationIds, allUnread, limit: max }) => {
+        const { uid } = await authed(["workspace:read"]);
+        if (Boolean(notificationIds?.length) === allUnread) {
+            throw new Error("Provide either notificationIds or allUnread=true.");
+        }
+        let ids = [...new Set(notificationIds ?? [])];
+        if (allUnread) {
+            const snap = await getDocs(query(collection(firestore, "userNotifications", uid, "items"), where("read", "==", false), limit(max)));
+            ids = snap.docs.map((item) => item.id);
+        }
+        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_list_telegram_channels", {
         title: "List Telegram channels",
         description: toolDescription({

package/package.json

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