@overpod/mcp-telegram 1.24.1 → 1.26.0

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/media.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
 export function registerMediaTools(server, telegram) {
     server.registerTool("telegram-send-file", {
         description: "Send a file (photo, document, video, etc.) to a Telegram chat",
@@ -81,4 +81,123 @@ export function registerMediaTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-web-preview", {
+        description: "Fetch Telegram's web-page preview metadata (type, title, description, site name) for a URL",
+        inputSchema: {
+            url: z
+                .string()
+                .url()
+                .refine((u) => {
+                try {
+                    const p = new URL(u);
+                    if (p.protocol !== "http:" && p.protocol !== "https:")
+                        return false;
+                    const host = p.hostname
+                        .toLowerCase()
+                        .replace(/^\[|\]$/g, "")
+                        .replace(/\.$/, "");
+                    if (host === "localhost" ||
+                        // Trailing-dot and subdomain forms of localhost (e.g. "localhost.", "foo.localhost")
+                        host.endsWith(".localhost") ||
+                        // Unspecified: 0.0.0.0/8
+                        /^0\./.test(host) ||
+                        // IPv4 loopback
+                        /^127\./.test(host) ||
+                        // IPv6 loopback and unspecified address
+                        host === "::1" ||
+                        host === "::" ||
+                        // Link-local (AWS metadata, etc.)
+                        /^169\.254\./.test(host) ||
+                        // RFC1918 private ranges
+                        /^10\./.test(host) ||
+                        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+                        /^192\.168\./.test(host) ||
+                        // IETF Protocol Assignments: 192.0.0.0/24
+                        /^192\.0\.0\./.test(host) ||
+                        // Documentation ranges (TEST-NET-1/2/3, RFC 5737): 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24
+                        /^192\.0\.2\./.test(host) ||
+                        /^198\.51\.100\./.test(host) ||
+                        /^203\.0\.113\./.test(host) ||
+                        // CGNAT (RFC 6598): 100.64.0.0/10
+                        /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host) ||
+                        // Benchmark testing (RFC 2544): 198.18.0.0/15
+                        /^198\.1[89]\./.test(host) ||
+                        // IPv4 multicast: 224.0.0.0/4
+                        /^2(2[4-9]|3\d)\./.test(host) ||
+                        // Reserved (future use): 240.0.0.0/4 and broadcast
+                        /^(24[0-9]|25[0-5])\./.test(host)) {
+                        return false;
+                    }
+                    // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1 or Node-normalized ::ffff:7f00:1)
+                    if (/^::ffff:/i.test(host)) {
+                        let v4 = host.replace(/^::ffff:/i, "");
+                        // Node.js normalizes ::ffff:a.b.c.d to ::ffff:XXYY:ZZWW (hex pairs).
+                        // Convert hex-pair form back to dotted decimal before range checks.
+                        const hexPair = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(v4);
+                        if (hexPair) {
+                            const hi = hexPair[1].padStart(4, "0");
+                            const lo = hexPair[2].padStart(4, "0");
+                            v4 = [
+                                parseInt(hi.slice(0, 2), 16),
+                                parseInt(hi.slice(2, 4), 16),
+                                parseInt(lo.slice(0, 2), 16),
+                                parseInt(lo.slice(2, 4), 16),
+                            ].join(".");
+                        }
+                        if (/^0\./.test(v4) ||
+                            /^127\./.test(v4) ||
+                            /^10\./.test(v4) ||
+                            /^172\.(1[6-9]|2\d|3[01])\./.test(v4) ||
+                            /^192\.168\./.test(v4) ||
+                            /^192\.0\.0\./.test(v4) ||
+                            /^192\.0\.2\./.test(v4) ||
+                            /^198\.51\.100\./.test(v4) ||
+                            /^203\.0\.113\./.test(v4) ||
+                            /^169\.254\./.test(v4) ||
+                            /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(v4) ||
+                            /^198\.1[89]\./.test(v4) ||
+                            /^2(2[4-9]|3\d)\./.test(v4) ||
+                            /^(24[0-9]|25[0-5])\./.test(v4)) {
+                            return false;
+                        }
+                    }
+                    // Private IPv6: ULA fc00::/7, link-local fe80::/10, multicast ff00::/8, documentation 2001:db8::/32
+                    if (/^f[cd][0-9a-f]/i.test(host) ||
+                        /^fe[89ab][0-9a-f]/i.test(host) ||
+                        /^ff[0-9a-f]{2}/i.test(host) ||
+                        /^2001:0?db8:/i.test(host)) {
+                        return false;
+                    }
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }, "Only http:// and https:// URLs are allowed; literal loopback, private, link-local, and reserved IP addresses are blocked (DNS-backed hostnames that resolve to private ranges are not checked)")
+                .describe("URL to preview (http:// or https://; literal private/loopback/reserved IPs rejected)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ url }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const preview = await telegram.getWebPreview(url);
+            if (!preview)
+                return ok("No preview available");
+            const lines = [`type: ${preview.type}`];
+            if (preview.url)
+                lines.push(`url: ${preview.url}`);
+            if (preview.siteName)
+                lines.push(`site: ${sanitize(preview.siteName)}`);
+            if (preview.title)
+                lines.push(`title: ${sanitize(preview.title)}`);
+            if (preview.description)
+                lines.push(`description: ${sanitize(preview.description)}`);
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/messages.js

@@ -191,6 +191,193 @@ export function registerMessageTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-scheduled", {
+        description: "List scheduled messages in a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getScheduledMessages(chatId);
+            const text = messages
+                .map((m) => `[#${m.id}] [${m.date}] ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+                .join("\n\n");
+            return ok(sanitize(text) || "No scheduled messages");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-scheduled", {
+        description: "Delete scheduled messages in a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageIds: z
+                .array(z.number().int().positive())
+                .min(1)
+                .max(100)
+                .describe("Array of scheduled message IDs to delete (1-100)"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, messageIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteScheduledMessages(chatId, messageIds);
+            return ok(`Deleted ${messageIds.length} scheduled message(s) in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-replies", {
+        description: "Get replies/comments under a Telegram channel post or discussion message",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel or linked discussion group)"),
+            messageId: z.number().describe("ID of the message whose replies to fetch"),
+            limit: z.number().default(20).describe("Number of replies to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getReplies(chatId, messageId, limit);
+            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 replies");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-message-link", {
+        description: "Get a t.me link to a specific message in a Telegram channel or supergroup",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel or supergroup)"),
+            messageId: z.number().describe("ID of the message to link to"),
+            thread: z.boolean().default(false).describe("Link to the message thread instead of the message itself"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId, thread }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const link = await telegram.getMessageLink(chatId, messageId, thread);
+            return ok(sanitize(link));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-unread-mentions", {
+        description: "Get unread @mentions addressed to you in a Telegram chat. Marks all mentions as read on the server when all unread mentions fit within the requested limit.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            limit: z.number().default(20).describe("Max number of mentions to return"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getUnreadMentions(chatId, limit);
+            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 unread mentions");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-unread-reactions", {
+        description: "Get messages with unread reactions on your posts in a Telegram chat. Marks all reactions as read on the server when all unread reactions fit within the requested limit.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            limit: z.number().default(20).describe("Max number of messages to return"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getUnreadReactions(chatId, limit);
+            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 unread reactions");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-translate-message", {
+        description: "Translate one or more Telegram messages to a target language (requires Telegram Premium). Consumes account translation quota.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageIds: z
+                .array(z.number().int().positive())
+                .min(1)
+                .max(100)
+                .describe("Array of message IDs to translate (1-100)"),
+            toLang: z
+                .string()
+                .regex(/^[a-z]{2,3}(-[A-Z]{2})?$/)
+                .describe("ISO 639-1 (e.g. 'en', 'ru') or locale (e.g. 'en-US')"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageIds, toLang }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const translations = await telegram.translateText(chatId, messageIds, toLang);
+            const text = translations.length === messageIds.length
+                ? translations.map((t, i) => `[#${messageIds[i]}] ${t}`).join("\n\n")
+                : translations.join("\n\n");
+            return ok(sanitize(text) || "No translations");
+        }
+        catch (e) {
+            const msg = e.message ?? "";
+            if (/PREMIUM|PAYMENT_REQUIRED|TRANSLATE_REQ/i.test(msg)) {
+                return fail(new Error("Message translation requires Telegram Premium on this account"));
+            }
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-typing", {
+        description: "Send a typing/upload indicator to a Telegram chat (or cancel it)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            action: z
+                .enum(["typing", "upload_photo", "upload_document", "cancel"])
+                .default("typing")
+                .describe("Typing action to broadcast"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, action }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendTyping(chatId, action);
+            return ok(`Typing indicator (${action}) sent to ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-mark-as-read", {
         description: "Mark a Telegram chat as read",
         inputSchema: { chatId: z.string().describe("Chat ID or username") },
@@ -207,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);
+        }
+    });
+}