@overpod/mcp-telegram 1.25.0 → 1.26.1

package/dist/tools/account.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 const MUTE_FOREVER_UNTIL = 2147483647; // max 32-bit signed int
 export function registerAccountTools(server, telegram) {
     server.registerTool("telegram-mute-chat", {
@@ -58,7 +58,7 @@ export function registerAccountTools(server, telegram) {
             const text = folders
                 .map((f) => `[${f.id}] ${f.emoticon ? `${f.emoticon} ` : ""}${f.title} (${f.includeCount} chats, ${f.pinnedCount} pinned)`)
                 .join("\n");
-            return ok(sanitize(text));
+            return ok(text);
         }
         catch (e) {
             return fail(e);
@@ -103,7 +103,7 @@ export function registerAccountTools(server, telegram) {
             const text = sessions
                 .map((s) => `${s.current ? "→ " : "  "}${s.device} (${s.platform}) — ${s.appName} ${s.appVersion}\n    IP: ${s.ip} (${s.country}) | Last active: ${s.dateActive}${s.current ? " [CURRENT]" : ""}\n    Hash: ${s.hash}`)
                 .join("\n\n");
-            return ok(sanitize(text));
+            return ok(text);
         }
         catch (e) {
             return fail(e);
@@ -252,7 +252,7 @@ export function registerAccountTools(server, telegram) {
             const text = links
                 .map((l) => `${l.link}${l.title ? ` (${l.title})` : ""} — ${l.usageCount} uses${l.expired ? " [EXPIRED]" : ""}${l.revoked ? " [REVOKED]" : ""}`)
                 .join("\n");
-            return ok(sanitize(text));
+            return ok(text);
         }
         catch (e) {
             return fail(e);
@@ -291,7 +291,7 @@ export function registerAccountTools(server, telegram) {
             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));
+            return ok(text);
         }
         catch (e) {
             return fail(e);
@@ -344,7 +344,7 @@ export function registerAccountTools(server, telegram) {
             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));
+            return ok(text);
         }
         catch (e) {
             return fail(e);
@@ -369,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(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 } 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(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(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(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/chats.js

@@ -27,7 +27,7 @@ export function registerChatTools(server, telegram) {
                 return `${prefix} ${d.name} (${d.id})${botTag}${contactTag}${unread}`;
             })
                 .join("\n");
-            return ok(sanitize(text) || "No chats");
+            return ok(text || "No chats");
         }
         catch (e) {
             return fail(e);
@@ -49,7 +49,7 @@ export function registerChatTools(server, telegram) {
             const text = results
                 .map((c) => `${c.type === "group" ? "G" : c.type === "channel" ? "C" : "P"} ${c.name}${c.username ? ` (@${c.username})` : ""} (${c.id})${c.membersCount ? ` [${c.membersCount} members]` : ""}${c.description ? ` — ${c.description.split("\n")[0].slice(0, 100)}` : ""}`)
                 .join("\n");
-            return ok(sanitize(text) || "No results");
+            return ok(text || "No results");
         }
         catch (e) {
             return fail(e);
@@ -99,7 +99,7 @@ export function registerChatTools(server, telegram) {
                 return `${m.name}${m.username ? ` (@${m.username})` : ""} (${m.id})${role}`;
             })
                 .join("\n");
-            return ok(sanitize(text) || "No members found");
+            return ok(text || "No members found");
         }
         catch (e) {
             return fail(e);
@@ -386,7 +386,7 @@ export function registerChatTools(server, telegram) {
                 return `[#${e.id}] [${e.date}] ${e.userName}: ${e.action}${details}`;
             })
                 .join("\n");
-            return ok(sanitize(text) || "No admin log events");
+            return ok(text || "No admin log events");
         }
         catch (e) {
             return fail(e);
@@ -473,6 +473,110 @@ export function registerChatTools(server, telegram) {
             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: {
@@ -502,7 +606,7 @@ export function registerChatTools(server, telegram) {
             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}`));
+            return ok(`Created topic "${topic.title}" (id=${topic.id}) in ${chatId}`);
         }
         catch (e) {
             return fail(e);
@@ -546,6 +650,52 @@ export function registerChatTools(server, telegram) {
             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(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(JSON.stringify(stats));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-delete-topic", {
         description: "Delete a forum topic and all its message history",
         inputSchema: {

package/dist/tools/contacts.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function registerContactTools(server, telegram) {
     server.registerTool("telegram-get-contacts", {
         description: "Get your Telegram contacts list with phone numbers",
@@ -14,7 +14,7 @@ export function registerContactTools(server, telegram) {
             const text = contacts
                 .map((c) => `P ${c.name}${c.username ? ` (@${c.username})` : ""} (${c.id})${c.phone ? ` +${c.phone}` : ""}`)
                 .join("\n");
-            return ok(sanitize(text) || "No contacts");
+            return ok(text || "No contacts");
         }
         catch (e) {
             return fail(e);
@@ -73,7 +73,7 @@ export function registerContactTools(server, telegram) {
                 return `${tag} ${r.name}${username} (${r.id})${unread}${preview}`;
             })
                 .join("\n");
-            return ok(sanitize(text));
+            return ok(text);
         }
         catch (e) {
             return fail(e);

package/dist/tools/extras.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, formatReactions, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { fail, formatReactions, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function registerExtraTools(server, telegram) {
     server.registerTool("telegram-pin-message", {
         description: "Pin a message in a Telegram chat",
@@ -122,7 +122,7 @@ export function registerExtraTools(server, telegram) {
                 return `# ${t.title} (id: ${t.id})${flagStr}${unread}`;
             })
                 .join("\n");
-            return ok(sanitize(text) || "No topics found");
+            return ok(text || "No topics found");
         }
         catch (e) {
             return fail(e);
@@ -146,7 +146,7 @@ export function registerExtraTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No messages in this topic");
+            return ok(text || "No messages in this topic");
         }
         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 } 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(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(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/index.js

@@ -1,12 +1,17 @@
 import { registerAccountTools } from "./account.js";
 import { registerAuthTools } from "./auth.js";
+import { registerBoostTools } from "./boosts.js";
 import { registerChatTools } from "./chats.js";
 import { registerContactTools } from "./contacts.js";
 import { registerExtraTools } from "./extras.js";
+import { registerGroupCallTools } from "./group-calls.js";
 import { registerMediaTools } from "./media.js";
 import { registerMessageTools } from "./messages.js";
+import { registerQuickRepliesTools } from "./quick-replies.js";
 import { registerReactionTools } from "./reactions.js";
+import { registerStarsTools } from "./stars.js";
 import { registerStickerTools } from "./stickers.js";
+import { registerStoryTools } from "./stories.js";
 export function registerTools(server, telegram) {
     registerAuthTools(server, telegram);
     registerMessageTools(server, telegram);
@@ -17,4 +22,9 @@ export function registerTools(server, telegram) {
     registerExtraTools(server, telegram);
     registerAccountTools(server, telegram);
     registerStickerTools(server, telegram);
+    registerStoryTools(server, telegram);
+    registerBoostTools(server, telegram);
+    registerGroupCallTools(server, telegram);
+    registerStarsTools(server, telegram);
+    registerQuickRepliesTools(server, telegram);
 }