@overpod/mcp-telegram 1.25.0 → 1.26.0

package/dist/tools/account.js

@@ -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(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

@@ -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: {
@@ -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(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: {

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);
+        }
+    });
+}

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);
 }

package/dist/tools/messages.js

@@ -394,4 +394,196 @@ export function registerMessageTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-inline-query", {
+        description: "Query an inline bot (like @gif, @bing) in a chat context and return the compact result list. Returns queryId, cacheTime, and results[{id,type,title?,description?,url?}]. The queryId is typically valid for ~60s and can be passed to telegram-inline-query-send to deliver a chosen result. Bot must be a real bot account",
+        inputSchema: {
+            bot: z.string().describe("Inline bot username (e.g. @gif) or numeric user ID"),
+            chatId: z.string().describe("Chat ID or username providing context for the inline query"),
+            query: z.string().describe("Query text the bot should resolve (may be empty string)"),
+            offset: z
+                .string()
+                .optional()
+                .describe("Pagination offset returned by a previous call as nextOffset (empty string on first call)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ bot, chatId, query, offset }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const res = await telegram.getInlineBotResults(bot, chatId, query, offset);
+            return ok(sanitize(JSON.stringify(res)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-inline-query-send", {
+        description: "Send an inline bot result to a chat by queryId + resultId (as returned by telegram-inline-query). The queryId is valid for ~60s after the original query, so call this soon after telegram-inline-query. Returns the sent messageId (0 if not extractable from the update).",
+        inputSchema: {
+            chatId: z.string().describe("Target chat ID or username to send the result into"),
+            queryId: z
+                .string()
+                .regex(/^\d+$/, "queryId must be a numeric string")
+                .describe("queryId from a prior telegram-inline-query call (valid ~60s)"),
+            resultId: z.string().describe("id of the chosen result from telegram-inline-query results[]"),
+            replyTo: z.number().optional().describe("Message ID to reply to"),
+            silent: z.boolean().optional().describe("Send without notification"),
+            hideVia: z.boolean().optional().describe("Hide the 'via @bot' label on the sent message"),
+            clearDraft: z.boolean().optional().describe("Clear the chat draft after sending"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, queryId, resultId, replyTo, silent, hideVia, clearDraft }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { messageId } = await telegram.sendInlineBotResult(chatId, queryId, resultId, {
+                replyTo,
+                silent,
+                hideVia,
+                clearDraft,
+            });
+            const idInfo = messageId ? ` [#${messageId}]` : "";
+            return ok(`Inline result ${resultId} sent to ${chatId}${idInfo}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-message-buttons", {
+        description: "List the inline/reply keyboard buttons on a Telegram message with their (row, col) indices, type (e.g. KeyboardButtonCallback, KeyboardButtonUrl), label and type-specific fields (callback data as base64, url, switchQuery, userId, copyText, etc). Helper for telegram-press-button — call this first to discover indices and filter by type before pressing. Returns markupType='none' and empty buttons when the message has no keyboard",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username where the message lives"),
+            messageId: z.number().describe("Message ID whose keyboard to inspect"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMessageButtons(chatId, messageId);
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-press-button", {
+        description: "Press an inline keyboard callback button on a message. Identify the button by (row, column) from its replyMarkup, or pass raw callback_data as base64. URL, switch-inline, game and 2FA-password buttons are rejected with a clear error. Returns the bot's callback answer: {alert?, hasUrl?, nativeUi?, message?, url?, cacheTime}",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username where the message lives"),
+            messageId: z.number().describe("Message ID whose inline button to press"),
+            row: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Button row index (0-based) — required unless data is provided"),
+            column: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Button column index (0-based) — required unless data is provided"),
+            data: z.string().optional().describe("Raw callback_data as base64 string (escape hatch — prefer row/column)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, row, column, data }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        const hasIndex = row !== undefined && column !== undefined;
+        if (!hasIndex && data === undefined) {
+            return fail(new Error("Provide either both row+column, or data (base64 callback_data)"));
+        }
+        if (hasIndex && data !== undefined) {
+            return fail(new Error("Provide either row+column OR data, not both"));
+        }
+        try {
+            const answer = await telegram.pressButton(chatId, messageId, {
+                buttonIndex: hasIndex ? { row: row, column: column } : undefined,
+                data,
+            });
+            return ok(sanitize(JSON.stringify(answer)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-state", {
+        description: "Initialize the polling cursor by fetching the current Telegram updates state {pts, qts, date, seq, unreadCount}. Call once before telegram-get-updates; then persist {pts, qts, date} in your agent state and feed them into telegram-get-updates. The MCP server does NOT store the cursor — you do.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const state = await telegram.getUpdatesState();
+            return ok(sanitize(JSON.stringify(state)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-updates", {
+        description: "Fetch new messages, deleted messages, and other updates since a previously-known {pts, qts, date} cursor (from telegram-get-state or a prior call). Returns compact newMessages[], deletedMessageIds[], otherUpdates[] (className only), and the new cursor state. isFinal=false means more updates are queued — call again with the returned state. If Telegram reports the gap is too long, a fallback hint is returned suggesting to resync via telegram-read-messages per chat. Cursor is stateless — the agent must persist {pts, qts, date} between calls.",
+        inputSchema: {
+            pts: z.number().int().describe("Last known pts (from telegram-get-state or prior telegram-get-updates)"),
+            qts: z.number().int().describe("Last known qts (secret-chat / encrypted stream cursor; 0 if unknown)"),
+            date: z.number().int().describe("Last known date (unix seconds from prior state)"),
+            ptsLimit: z
+                .number()
+                .int()
+                .positive()
+                .max(1000)
+                .optional()
+                .describe("Max updates per batch (default 100, capped at 1000)"),
+            ptsTotalLimit: z
+                .number()
+                .int()
+                .positive()
+                .max(1000)
+                .optional()
+                .describe("Max total updates across paginated slices (default 1000, capped at 1000)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ pts, qts, date, ptsLimit, ptsTotalLimit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const diff = await telegram.getUpdates({ pts, qts, date, ptsLimit, ptsTotalLimit });
+            return ok(sanitize(JSON.stringify(diff)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-channel-updates", {
+        description: "Fetch new messages and updates for a single channel/supergroup since a known per-channel pts cursor. Separate from the global cursor used by telegram-get-updates. Returns compact newMessages[], otherUpdates[], and new {pts, isFinal, timeout?}. If the channel gap is too long, Telegram returns a dialog snapshot — this tool forwards it and hints to resync via telegram-read-messages. Cursor is stateless — the agent stores pts.",
+        inputSchema: {
+            chatId: z.string().describe("Channel or supergroup ID or username"),
+            pts: z.number().int().describe("Last known per-channel pts"),
+            limit: z.number().int().positive().optional().describe("Max updates per batch (default 100)"),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Force request updates even if the client hasn't processed previous ones (rarely needed)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, pts, limit, force }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const diff = await telegram.getChannelUpdates(chatId, { pts, limit, force });
+            return ok(sanitize(JSON.stringify(diff)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/quick-replies.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 isQuickRepliesEnabled(): boolean;
+export declare function registerQuickRepliesTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/quick-replies.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize } from "./shared.js";
+export function isQuickRepliesEnabled() {
+    return process.env.MCP_TELEGRAM_ENABLE_QUICK_REPLIES === "1";
+}
+export function registerQuickRepliesTools(server, telegram) {
+    if (!isQuickRepliesEnabled())
+        return;
+    server.registerTool("telegram-get-quick-replies", {
+        description: "Fetch the list of quick-reply shortcuts configured for the user account (messages.GetQuickReplies). Each entry has {shortcutId, shortcut, topMessage, count} — use the shortcutId with telegram-get-quick-reply-messages to inspect the stored messages. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string and the server may respond with {notModified:true} if nothing changed. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.",
+        inputSchema: {
+            hash: z
+                .string()
+                .regex(/^\d+$/)
+                .optional()
+                .describe("Aggregate hash from a previous response (decimal string); omit for a fresh fetch"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ hash }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getQuickReplies(hash);
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-quick-reply-messages", {
+        description: "Fetch messages stored under a quick-reply shortcut (messages.GetQuickReplyMessages). Use `shortcutId` from telegram-get-quick-replies. Optional `ids` narrows to specific message ids within the shortcut. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string — the server may respond with {notModified:true, count} if nothing changed. Returns compact {count, messages[{id, date, text, isService, fromId?, replyToMsgId?}]}. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.",
+        inputSchema: {
+            shortcutId: z.number().int().nonnegative().describe("Shortcut id from telegram-get-quick-replies"),
+            ids: z
+                .array(z.number().int().nonnegative())
+                .optional()
+                .describe("Optional list of message ids to fetch within the shortcut"),
+            hash: z
+                .string()
+                .regex(/^\d+$/)
+                .optional()
+                .describe("Aggregate hash from a previous response (decimal string); omit for a fresh fetch"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ shortcutId, ids, hash }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getQuickReplyMessages(shortcutId, { ids, hash });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}