@overpod/mcp-telegram 1.24.1 → 1.26.0

package/dist/tools/account.js

@@ -258,6 +258,98 @@ export function registerAccountTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-save-draft", {
+        description: "Save or clear a message draft for a chat. Pass empty text to clear the draft. Optional replyTo sets the message being replied to",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            text: z.string().describe("Draft text. Empty string clears the draft"),
+            replyTo: z.number().int().positive().optional().describe("Message ID this draft replies to"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, text, replyTo }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.saveDraft(chatId, text, replyTo);
+            return ok(text === "" ? `Draft cleared for ${chatId}` : `Draft saved for ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-drafts", {
+        description: "Get all saved message drafts across chats",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const drafts = await telegram.getAllDrafts();
+            if (drafts.length === 0)
+                return ok("No drafts");
+            const text = drafts.map((d) => `[${d.chatId}] ${d.chatTitle} (${d.date})\n  ${d.text}`).join("\n\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-clear-drafts", {
+        description: "Delete saved message drafts. Pass chatId to clear the draft for a single chat. Without chatId, clears drafts in ALL chats — requires confirmAllChats: true",
+        inputSchema: {
+            chatId: z.string().optional().describe("Chat ID or username. If provided, clears draft only for this chat"),
+            confirmAllChats: z
+                .boolean()
+                .optional()
+                .describe("Must be true to wipe drafts across ALL chats when chatId is omitted"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, confirmAllChats }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            if (chatId !== undefined) {
+                if (confirmAllChats) {
+                    return fail(new Error("Pass either chatId or confirmAllChats=true, not both"));
+                }
+                await telegram.saveDraft(chatId, "");
+                return ok(`Draft cleared for ${chatId}`);
+            }
+            if (!confirmAllChats) {
+                return fail(new Error("Refusing to clear drafts in ALL chats without explicit confirmation. Pass chatId for a single chat, or confirmAllChats=true to wipe all drafts"));
+            }
+            await telegram.clearAllDrafts();
+            return ok("All drafts cleared");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-saved-dialogs", {
+        description: "Get Saved Messages dialogs (Telegram's per-sender grouping of messages forwarded to your Saved Messages)",
+        inputSchema: {
+            limit: z.number().int().positive().default(20).describe("Max dialogs to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const dialogs = await telegram.getSavedDialogs(limit);
+            if (dialogs.length === 0)
+                return ok("No saved dialogs");
+            const text = dialogs.map((d) => `[${d.peerId}] ${d.peerTitle} — last msg #${d.lastMsgId}`).join("\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-revoke-invite-link", {
         description: "Revoke an invite link for a group or channel",
         inputSchema: {
@@ -277,4 +369,20 @@ export function registerAccountTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-business-chat-links", {
+        description: "List Telegram Business chat links configured for the account (account.GetBusinessChatLinks). Each entry includes the t.me/... link, the prefilled message, optional title (admin-facing label), views count, and entityCount (number of formatting entities in the message). Requires a Telegram Business-enabled account — returns an empty list when the account has none configured. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getBusinessChatLinks();
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/boosts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerBoostTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/boosts.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize } from "./shared.js";
+export function registerBoostTools(server, telegram) {
+    server.registerTool("telegram-get-my-boosts", {
+        description: "List the user's premium boost slots (premium.GetMyBoosts). Each entry includes slot index, the peer it currently boosts (if any), the date the boost was applied, expiration timestamp, and cooldownUntilDate (when a slot can be reassigned). Premium users have multiple slots; non-Premium users typically have a single slot. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMyBoosts();
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-boosts-status", {
+        description: "Fetch the boost status of a channel/supergroup (premium.GetBoostsStatus). Returns current boost level, total boosts, progress to next level (currentLevelBoosts/nextLevelBoosts), giftBoosts, premiumAudience ratio, public boostUrl, and whether the current user is boosting (myBoost + myBoostSlots). Also includes any prepaidGiveaways attached to the chat. Read-only.",
+        inputSchema: {
+            chat: z.string().describe("Channel or supergroup to query — id, @username, or display name fragment"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getBoostsStatus(chat);
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-boosts-list", {
+        description: "List the boosts applied to a channel/supergroup (premium.GetBoostsList). Returns paginated boost entries with id, userId (or undefined for anonymous gift boosts), date, expires, flags (gift, giveaway, unclaimed), optional giveawayMsgId, usedGiftSlug, multiplier, and stars. Requires channel admin permissions. Supports pagination via nextOffset and an optional gifts filter to show only gift boosts. Read-only.",
+        inputSchema: {
+            chat: z.string().describe("Channel or supergroup to query — id, @username, or display name fragment"),
+            gifts: z.boolean().optional().describe("If true, return only gift boosts"),
+            offset: z.string().optional().describe("Pagination cursor returned as nextOffset from the previous call"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Max boosts to return per page (default 50, max 100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, gifts, offset, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getBoostsList(chat, { gifts, offset, limit });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/chats.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
 export function registerChatTools(server, telegram) {
     server.registerTool("telegram-list-chats", {
         description: "List Telegram chats with unread counts, type indicators, and contact status",
@@ -309,6 +309,89 @@ export function registerChatTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-archive-chat", {
+        description: "Archive or unarchive a Telegram dialog (moves to/from the Archive folder)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            archive: z.boolean().describe("true to archive, false to unarchive"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, archive }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.archiveChat(chatId, archive);
+            return ok(`${archive ? "Archived" : "Unarchived"} ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-pin-chat", {
+        description: "Pin or unpin a Telegram dialog in the dialog list",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            pin: z.boolean().describe("true to pin, false to unpin"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, pin }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.pinDialog(chatId, pin);
+            return ok(`${pin ? "Pinned" : "Unpinned"} ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-mark-dialog-unread", {
+        description: "Mark a Telegram dialog as unread (or clear the unread mark)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            unread: z.boolean().describe("true to mark as unread, false to clear the mark"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, unread }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.markDialogUnread(chatId, unread);
+            return ok(`Marked ${chatId} as ${unread ? "unread" : "read"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-admin-log", {
+        description: "Get the admin action log (recent event history) of a supergroup or channel. Includes bans, edits, pins, and role changes",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (supergroup or channel)"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Number of events to return (1-100)"),
+            q: z.string().optional().describe("Optional text filter for events"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit, q }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const events = await telegram.getAdminLog(chatId, limit, q);
+            const text = events
+                .map((e) => {
+                const details = e.details ? ` — ${e.details}` : "";
+                return `[#${e.id}] [${e.date}] ${e.userName}: ${e.action}${details}`;
+            })
+                .join("\n");
+            return ok(sanitize(text) || "No admin log events");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-remove-admin", {
         description: "Remove admin rights from a user in a supergroup or channel",
         inputSchema: {
@@ -328,4 +411,308 @@ export function registerChatTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-set-chat-permissions", {
+        description: "Set the default permissions for all non-admin members of a group, supergroup, or channel. Omitted flags keep their current state; true = allowed, false = denied",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            sendMessages: z.boolean().optional().describe("Allow sending text messages"),
+            sendMedia: z.boolean().optional().describe("Allow sending photos/videos/documents"),
+            sendStickers: z.boolean().optional().describe("Allow sending stickers"),
+            sendGifs: z.boolean().optional().describe("Allow sending GIFs"),
+            sendPolls: z.boolean().optional().describe("Allow sending polls"),
+            sendInline: z.boolean().optional().describe("Allow inline bot usage"),
+            embedLinks: z.boolean().optional().describe("Allow link previews"),
+            changeInfo: z.boolean().optional().describe("Allow changing chat info (title, photo, description)"),
+            inviteUsers: z.boolean().optional().describe("Allow inviting new members"),
+            pinMessages: z.boolean().optional().describe("Allow pinning messages"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, ...permissions }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setChatPermissions(chatId, permissions);
+            const changed = Object.entries(permissions)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${k}=${v ? "allow" : "deny"}`);
+            return ok(changed.length > 0
+                ? `Updated default permissions for ${chatId}: ${changed.join(", ")}`
+                : `No permission changes for ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-slow-mode", {
+        description: "Set slow mode for a supergroup (minimum interval between messages per user). Allowed values: 0, 10, 30, 60, 300, 900, 3600 seconds (0 disables slow mode)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (supergroup)"),
+            seconds: z
+                .union([
+                z.literal(0),
+                z.literal(10),
+                z.literal(30),
+                z.literal(60),
+                z.literal(300),
+                z.literal(900),
+                z.literal(3600),
+            ])
+                .describe("Interval in seconds: 0 (off), 10, 30, 60, 300, 900, or 3600"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, seconds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setSlowMode(chatId, seconds);
+            return ok(seconds === 0 ? `Disabled slow mode in ${chatId}` : `Set slow mode to ${seconds}s in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-channel-signatures", {
+        description: "Enable or disable author signatures on broadcast channel posts. Channel admin required; not supported for supergroups",
+        inputSchema: {
+            chatId: z.string().describe("Channel ID or username"),
+            enabled: z.boolean().describe("true to enable author signatures, false to disable"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, enabled }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.toggleChannelSignatures(chatId, enabled);
+            return ok(JSON.stringify({ ok: true, signaturesEnabled: enabled }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-anti-spam", {
+        description: "Enable or disable aggressive anti-spam filtering in a supergroup. Supergroup only (not broadcast channels); requires admin with ban_users permission",
+        inputSchema: {
+            chatId: z.string().describe("Supergroup ID or username"),
+            enabled: z.boolean().describe("true to enable aggressive anti-spam, false to disable"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, enabled }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.toggleAntiSpam(chatId, enabled);
+            return ok(`${enabled ? "Enabled" : "Disabled"} aggressive anti-spam in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-forum-mode", {
+        description: "Enable or disable forum/topics mode in a supergroup. Supergroup only; requires creator or admin. " +
+            "WARNING: disabling removes ALL existing topics — pass confirm=true to proceed with disable",
+        inputSchema: {
+            chatId: z.string().describe("Supergroup ID or username"),
+            enabled: z.boolean().describe("true to enable forum mode, false to disable"),
+            confirm: z
+                .boolean()
+                .optional()
+                .describe("Must be true when disabling (enabled=false) — disabling deletes all existing topics"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, enabled, confirm }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!enabled && confirm !== true) {
+            return fail(new Error("Disabling forum mode deletes all existing topics. Pass confirm=true to proceed with this destructive action."));
+        }
+        try {
+            await telegram.toggleForumMode(chatId, enabled);
+            return ok(`${enabled ? "Enabled" : "Disabled"} forum mode in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-prehistory-hidden", {
+        description: "Toggle pre-history visibility for new members in a supergroup. When hidden=true, new joiners cannot see messages posted before they joined. Supergroup only; requires admin",
+        inputSchema: {
+            chatId: z.string().describe("Supergroup ID or username"),
+            hidden: z.boolean().describe("true to hide prior history from new members, false to make it visible"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, hidden }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.togglePrehistoryHidden(chatId, hidden);
+            return ok(`${hidden ? "Hid" : "Revealed"} prehistory for new members in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-approve-join-request", {
+        description: "Approve or deny a pending join request for a supergroup or channel (basic groups are not supported). Admin with invite_users permission required",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username where the join request is pending"),
+            userId: z.string().describe("User ID or username of the requesting user"),
+            approved: z.boolean().describe("true to approve the join request, false to deny"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId, approved }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.approveChatJoinRequest(chatId, userId, approved);
+            return ok(`${approved ? "Approved" : "Denied"} join request from ${userId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-create-topic", {
+        description: "Create a new forum topic in a forum-enabled supergroup",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username of the forum supergroup"),
+            title: z.string().describe("Topic title"),
+            iconColor: z
+                .union([
+                z.literal(7322096),
+                z.literal(16766590),
+                z.literal(13338331),
+                z.literal(9367192),
+                z.literal(16749490),
+                z.literal(16225862),
+            ])
+                .optional()
+                .describe("Optional icon color (one of 7322096, 16766590, 13338331, 9367192, 16749490, 16225862)"),
+            iconEmojiId: z
+                .string()
+                .regex(/^\d+$/, "iconEmojiId must be a numeric string")
+                .optional()
+                .describe("Optional custom emoji document ID for the icon (numeric string)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, title, iconColor, iconEmojiId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const topic = await telegram.createForumTopic(chatId, title, iconColor, iconEmojiId);
+            return ok(sanitize(`Created topic "${topic.title}" (id=${topic.id}) in ${chatId}`));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-topic", {
+        description: "Edit a forum topic — rename, change icon emoji, open/close, or show/hide",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username of the forum supergroup"),
+            topicId: z.number().describe("Topic ID (get from telegram-list-topics)"),
+            title: z.string().optional().describe("New topic title"),
+            iconEmojiId: z
+                .string()
+                .regex(/^\d+$/, "iconEmojiId must be a numeric string")
+                .optional()
+                .describe("New custom emoji document ID for the icon (numeric string)"),
+            closed: z.boolean().optional().describe("Close (true) or reopen (false) the topic"),
+            hidden: z.boolean().optional().describe("Hide (true) or show (false) the General topic"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, topicId, title, iconEmojiId, closed, hidden }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editForumTopic(chatId, topicId, { title, iconEmojiId, closed, hidden });
+            const changes = [];
+            if (title !== undefined)
+                changes.push(`title="${title}"`);
+            if (iconEmojiId !== undefined)
+                changes.push(`iconEmojiId=${iconEmojiId}`);
+            if (closed !== undefined)
+                changes.push(closed ? "closed" : "reopened");
+            if (hidden !== undefined)
+                changes.push(hidden ? "hidden" : "shown");
+            return ok(sanitize(changes.length > 0
+                ? `Updated topic ${topicId} in ${chatId}: ${changes.join(", ")}`
+                : `No changes for topic ${topicId} in ${chatId}`));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-broadcast-stats", {
+        description: "Get broadcast channel statistics: followers, views/shares/reactions per post & story, notification percent, recent post interactions. Broadcast channels only (use telegram-get-megagroup-stats for supergroups). Admin rights required; some channels may require Telegram Premium to expose stats",
+        inputSchema: {
+            chatId: z.string().describe("Broadcast channel ID or username"),
+            includeGraphs: z
+                .boolean()
+                .default(false)
+                .describe("Include raw graph data for each series (growth, followers, interactions, etc.). Default false — returns only aggregate numbers + metadata"),
+            dark: z.boolean().default(false).describe("Prefer dark-theme palette when Telegram renders graphs"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, includeGraphs, dark }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const stats = await telegram.getBroadcastStats(chatId, { dark, includeGraphs });
+            return ok(sanitize(JSON.stringify(stats)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-megagroup-stats", {
+        description: "Get supergroup statistics: members, messages, viewers, posters (current vs previous period), top posters/admins/inviters. Supergroups only (use telegram-get-broadcast-stats for broadcast channels). Admin rights required. Telegram rate-limits this endpoint to roughly 1 request per 30 minutes per channel — expect FLOOD_WAIT on rapid repeat calls",
+        inputSchema: {
+            chatId: z.string().describe("Supergroup ID or username"),
+            includeGraphs: z
+                .boolean()
+                .default(false)
+                .describe("Include raw graph data for each series (growth, members, messages, actions, top hours, weekdays, etc.). Default false — returns only aggregate numbers + top lists"),
+            dark: z.boolean().default(false).describe("Prefer dark-theme palette when Telegram renders graphs"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, includeGraphs, dark }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const stats = await telegram.getMegagroupStats(chatId, { dark, includeGraphs });
+            return ok(sanitize(JSON.stringify(stats)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-topic", {
+        description: "Delete a forum topic and all its message history",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username of the forum supergroup"),
+            topicId: z.number().describe("Topic ID to delete"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteForumTopic(chatId, topicId);
+            return ok(`Deleted topic ${topicId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/group-calls.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function isGroupCallsEnabled(): boolean;
+export declare function registerGroupCallTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/group-calls.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize } from "./shared.js";
+export function isGroupCallsEnabled() {
+    return process.env.MCP_TELEGRAM_ENABLE_GROUP_CALLS === "1";
+}
+export function registerGroupCallTools(server, telegram) {
+    if (!isGroupCallsEnabled())
+        return;
+    server.registerTool("telegram-get-group-call", {
+        description: "Fetch metadata + an optional initial slice of participants for the active group call (voice/video chat) attached to a chat (phone.GetGroupCall). Returns call info (id, accessHash, participantsCount, title, scheduleDate, recordStartDate, streamDcId, flags) plus a participant slice (peer, date, muted/left/self flags, source, volume, video/presentation indicators) and participantsNextOffset. Pass limit:0 (default) for metadata only. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1. Read-only.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Group/supergroup/channel that currently has an active group call — id, @username, or display name fragment"),
+            limit: z
+                .number()
+                .int()
+                .min(0)
+                .max(500)
+                .optional()
+                .describe("Max participants to include (default 0 — metadata only; use telegram-get-group-call-participants for pagination)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getGroupCall(chat, { limit });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-group-call-participants", {
+        description: "List participants of the active group call (voice/video chat) attached to a chat with pagination (phone.GetGroupParticipants). Looks up the chat's current InputGroupCall automatically, then returns {count, participants[], nextOffset?, version}. Each participant includes peer, date, source, volume, muted/self/left/videoJoined flags, raise-hand rating, about text, and hasVideo/hasPresentation indicators. Pass offset from a prior call's nextOffset to paginate; pass ids (user/channel peers) or sources to filter to specific participants. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1. Read-only.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Group/supergroup/channel that currently has an active group call — id, @username, or display name fragment"),
+            ids: z
+                .array(z.string())
+                .max(100)
+                .optional()
+                .describe("Optional list of participant peer ids/@usernames to filter (max 100)"),
+            sources: z
+                .array(z.number().int())
+                .max(100)
+                .optional()
+                .describe("Optional list of numeric source ids (audio SSRC) to filter participants"),
+            offset: z
+                .string()
+                .optional()
+                .describe("Pagination cursor from a previous response's nextOffset; omit for the first page"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("Max participants to return in this page (default 100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, ids, sources, offset, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getGroupCallParticipants(chat, { ids, sources, offset, limit });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}