@overpod/mcp-telegram 1.28.1 → 1.32.0

package/dist/tools/business.js

@@ -0,0 +1,333 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+const AUDIENCE = z.enum(["all_new", "contacts_only", "non_contacts", "existing_only"]).default("all_new");
+export function registerBusinessTools(server, telegram) {
+    server.registerTool("telegram-get-business-chat-links", {
+        description: "List Telegram Business chat links configured for the account. Each entry includes the t.me/... link, the prefilled message, optional title (admin-facing label), views count, and entityCount. Requires Telegram Business — returns empty list when none configured.",
+        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);
+        }
+    });
+    server.registerTool("telegram-create-business-chat-link", {
+        description: "Create a Telegram Business chat link (t.me/m/... deep-link that opens a chat with you pre-filled with a message). Returns JSON with link, slug, message, title, and views. Requires Telegram Business subscription.",
+        inputSchema: {
+            message: z.string().min(1).max(4096).describe("Pre-filled message text shown to users who click the link"),
+            title: z.string().max(32).optional().describe("Admin-facing label (not visible to visitors, max 32 chars)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Format message as Markdown or HTML"),
+        },
+        annotations: WRITE,
+    }, async ({ message, title, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.createBusinessChatLink({ message, title, parseMode });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-business-chat-link", {
+        description: "Edit an existing Telegram Business chat link by its slug (the trailing segment after t.me/m/). Returns JSON with updated fields. Requires Telegram Business subscription.",
+        inputSchema: {
+            slug: z.string().min(1).describe("Link slug — the last path segment of t.me/m/<slug>"),
+            message: z.string().min(1).max(4096).describe("New pre-filled message text"),
+            title: z.string().max(32).optional().describe("New admin-facing label (max 32 chars)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Format message as Markdown or HTML"),
+        },
+        annotations: WRITE,
+    }, async ({ slug, message, title, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.editBusinessChatLink({ slug, message, title, parseMode });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-business-chat-link", {
+        description: "Delete a Telegram Business chat link by its slug. Requires Telegram Business subscription.",
+        inputSchema: {
+            slug: z.string().min(1).describe("Link slug to delete (from t.me/m/<slug>)"),
+        },
+        annotations: WRITE,
+    }, async ({ slug }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteBusinessChatLink(slug);
+            return ok(`Business chat link '${slug}' deleted`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-resolve-business-chat-link", {
+        description: "Resolve a Telegram Business chat link by slug to see whose chat it opens and the pre-filled message. Returns JSON with peerId, peerType, message, and entityCount.",
+        inputSchema: {
+            slug: z.string().min(1).describe("Link slug to resolve (from t.me/m/<slug>)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ slug }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.resolveBusinessChatLink(slug);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-business-hours", {
+        description: "Set Telegram Business work hours — days and time ranges when your business is open. Requires Telegram Business subscription. Pass clear=true to disable the work hours display entirely.",
+        inputSchema: {
+            timezone: z
+                .string()
+                .optional()
+                .describe("IANA timezone ID (e.g. 'Europe/Moscow', 'America/New_York'). Required when setting schedule."),
+            openNow: z
+                .boolean()
+                .optional()
+                .describe("Manually override current open/closed status. Omit to derive from schedule."),
+            schedule: z
+                .array(z.object({
+                day: z.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"]).describe("Day of week"),
+                openFrom: z
+                    .string()
+                    .regex(/^\d{2}:\d{2}$/)
+                    .describe("Opening time in 24h HH:MM format"),
+                openTo: z
+                    .string()
+                    .regex(/^\d{2}:\d{2}$/)
+                    .describe("Closing time in 24h HH:MM. Use '24:00' for end of day."),
+            }))
+                .optional()
+                .describe("Weekly schedule. Multiple ranges per day are allowed."),
+            clear: z.boolean().optional().describe("Pass true to remove business hours entirely"),
+        },
+        annotations: WRITE,
+    }, async ({ timezone, openNow, schedule, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && (!timezone || !schedule?.length)) {
+            return fail(new Error("timezone and schedule are required when not clearing"));
+        }
+        try {
+            await telegram.setBusinessWorkHours({ timezone, openNow, schedule, clear });
+            if (clear)
+                return ok("Business hours cleared");
+            return ok(`Business hours set: ${schedule?.length} range(s) in ${timezone}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-business-location", {
+        description: "Set Telegram Business physical location (address + optional geo coordinates). Requires Telegram Business subscription. Pass clear=true to remove.",
+        inputSchema: {
+            address: z.string().min(1).max(512).optional().describe("Street address text"),
+            latitude: z.number().min(-90).max(90).optional().describe("Geo latitude (-90 to 90)"),
+            longitude: z.number().min(-180).max(180).optional().describe("Geo longitude (-180 to 180)"),
+            clear: z.boolean().optional().describe("Pass true to remove business location"),
+        },
+        annotations: WRITE,
+    }, async ({ address, latitude, longitude, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && !address) {
+            return fail(new Error("address is required when not clearing"));
+        }
+        if ((latitude === undefined) !== (longitude === undefined)) {
+            return fail(new Error("latitude and longitude must both be set or both omitted"));
+        }
+        try {
+            await telegram.setBusinessLocation({ address, latitude, longitude, clear });
+            if (clear)
+                return ok("Business location cleared");
+            const geo = latitude !== undefined ? ` @ ${latitude},${longitude}` : "";
+            return ok(`Business location set: ${address}${geo}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-business-greeting", {
+        description: "Set Telegram Business greeting message — auto-reply sent to new conversations using a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.",
+        inputSchema: {
+            shortcutId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Quick reply shortcut ID (from telegram-get-quick-replies) used as the greeting template"),
+            audience: AUDIENCE.describe("Who receives the greeting: all_new (new contacts+non-contacts), contacts_only, non_contacts, existing_only"),
+            includeUsers: z.array(z.string()).optional().describe("Additional usernames/IDs to always include"),
+            excludeUsers: z
+                .array(z.string())
+                .optional()
+                .describe("Usernames/IDs to exclude — overrides audience. Cannot be combined with includeUsers."),
+            noActivityDays: z
+                .number()
+                .int()
+                .min(1)
+                .max(365)
+                .default(7)
+                .describe("Send greeting if user has been inactive for N days"),
+            clear: z.boolean().optional().describe("Pass true to disable greeting message"),
+        },
+        annotations: WRITE,
+    }, async ({ shortcutId, audience, includeUsers, excludeUsers, noActivityDays, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && shortcutId === undefined) {
+            return fail(new Error("shortcutId is required when not clearing"));
+        }
+        if (includeUsers?.length && excludeUsers?.length) {
+            return fail(new Error("includeUsers and excludeUsers cannot both be set"));
+        }
+        try {
+            await telegram.setBusinessGreeting({
+                shortcutId,
+                audience,
+                includeUsers,
+                excludeUsers,
+                noActivityDays,
+                clear,
+            });
+            if (clear)
+                return ok("Business greeting cleared");
+            return ok(`Business greeting set: shortcut=${shortcutId} audience=${audience} noActivityDays=${noActivityDays}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-business-away", {
+        description: "Set Telegram Business away message — auto-reply when you are offline or outside work hours. Uses a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.",
+        inputSchema: {
+            shortcutId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Quick reply shortcut ID used as the away message template"),
+            schedule: z
+                .enum(["always", "outside_hours", "custom"])
+                .default("outside_hours")
+                .describe("When to send: always (any time offline), outside_hours (based on business hours), custom (time range)"),
+            customFrom: z.number().int().positive().optional().describe("For schedule=custom: Unix timestamp range start"),
+            customTo: z.number().int().positive().optional().describe("For schedule=custom: Unix timestamp range end"),
+            offlineOnly: z
+                .boolean()
+                .default(true)
+                .describe("Send only when you appear offline (true) or regardless of online status (false)"),
+            audience: AUDIENCE.describe("Who receives the away message"),
+            includeUsers: z.array(z.string()).optional(),
+            excludeUsers: z.array(z.string()).optional(),
+            clear: z.boolean().optional().describe("Pass true to disable away message"),
+        },
+        annotations: WRITE,
+    }, async ({ shortcutId, schedule, customFrom, customTo, offlineOnly, audience, includeUsers, excludeUsers, clear, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && shortcutId === undefined) {
+            return fail(new Error("shortcutId is required when not clearing"));
+        }
+        if (schedule === "custom" && (customFrom === undefined || customTo === undefined)) {
+            return fail(new Error("customFrom and customTo are required when schedule=custom"));
+        }
+        if (includeUsers?.length && excludeUsers?.length) {
+            return fail(new Error("includeUsers and excludeUsers cannot both be set"));
+        }
+        try {
+            await telegram.setBusinessAway({
+                shortcutId,
+                schedule,
+                customFrom,
+                customTo,
+                offlineOnly,
+                audience,
+                includeUsers,
+                excludeUsers,
+                clear,
+            });
+            if (clear)
+                return ok("Business away message cleared");
+            return ok(`Business away message set: shortcut=${shortcutId} schedule=${schedule}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-business-intro", {
+        description: "Set Telegram Business intro card — title and description shown to new users opening your chat, with an optional sticker. Requires Telegram Business subscription. Pass clear=true to remove.",
+        inputSchema: {
+            title: z.string().min(1).max(32).optional().describe("Intro title (max 32 chars)"),
+            description: z.string().min(1).max(70).optional().describe("Intro description (max 70 chars)"),
+            stickerId: z
+                .string()
+                .optional()
+                .describe("Sticker document ID (stringified long) — optional illustrative sticker. Requires stickerAccessHash and stickerFileReference."),
+            stickerAccessHash: z
+                .string()
+                .optional()
+                .describe("Access hash of the sticker document (required with stickerId)"),
+            stickerFileReference: z
+                .string()
+                .regex(/^[\da-fA-F]{2,}$/)
+                .refine((v) => v.length % 2 === 0, "must be even-length hex")
+                .optional()
+                .describe("Hex-encoded file_reference bytes (required with stickerId)"),
+            clear: z.boolean().optional().describe("Pass true to remove the intro card"),
+        },
+        annotations: WRITE,
+    }, async ({ title, description, stickerId, stickerAccessHash, stickerFileReference, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && (!title || !description)) {
+            return fail(new Error("title and description are required when not clearing"));
+        }
+        const stickerFields = [stickerId, stickerAccessHash, stickerFileReference].filter(Boolean);
+        if (stickerFields.length > 0 && stickerFields.length < 3) {
+            return fail(new Error("stickerId, stickerAccessHash, and stickerFileReference must all be set together"));
+        }
+        try {
+            await telegram.setBusinessIntro({
+                title,
+                description,
+                stickerId,
+                stickerAccessHash,
+                stickerFileReference,
+                clear,
+            });
+            if (clear)
+                return ok("Business intro cleared");
+            return ok(`Business intro set: "${title}"`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/fact-check.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 registerFactCheckTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/fact-check.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, sanitizeInputText, WRITE } from "./shared.js";
+export function registerFactCheckTools(server, telegram) {
+    server.registerTool("telegram-get-fact-check", {
+        description: "Get fact-check annotations on channel messages. Fact-checks are added by independent fact-checkers in supported countries. Most messages will show no fact-check.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageIds: z
+                .array(z.number().int().positive())
+                .min(1)
+                .max(100)
+                .describe("Message IDs to get fact-checks for (1-100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getFactCheck(chatId, messageIds);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-fact-check", {
+        description: "Add or update a fact-check annotation. Requires fact-checker privileges (limited to independent verifiers in supported countries).",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID to annotate"),
+            text: z
+                .string()
+                .transform(sanitizeInputText)
+                .pipe(z.string().min(1).max(1024))
+                .describe("Fact-check annotation text (1-1024 chars)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Text format (currently ignored — plain text only)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, text, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editFactCheck(chatId, messageId, text, { parseMode });
+            const preview = `${text.slice(0, 80)}${text.length > 80 ? "..." : ""}`;
+            return ok(`Fact-check set on message #${messageId} in ${chatId}: "${preview}"`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-fact-check", {
+        description: "Remove a fact-check annotation. Requires fact-checker privileges.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID whose fact-check to remove"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteFactCheck(chatId, messageId);
+            return ok(`Removed fact-check from message #${messageId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/index.js

@@ -1,26 +1,34 @@
 import { registerAccountTools } from "./account.js";
 import { registerAuthTools } from "./auth.js";
 import { registerBoostTools } from "./boosts.js";
+import { registerBusinessTools } from "./business.js";
 import { registerChatTools } from "./chats.js";
 import { registerContactTools } from "./contacts.js";
 import { registerExtraTools } from "./extras.js";
+import { registerFactCheckTools } from "./fact-check.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 { registerSendMediaTools } from "./send-media.js";
 import { registerStarsTools } from "./stars.js";
 import { registerStickerTools } from "./stickers.js";
 import { registerStoryTools } from "./stories.js";
+import { registerTranscribeTools } from "./transcribe.js";
 export function registerTools(server, telegram) {
     registerAuthTools(server, telegram);
     registerMessageTools(server, telegram);
     registerChatTools(server, telegram);
     registerMediaTools(server, telegram);
+    registerSendMediaTools(server, telegram);
     registerContactTools(server, telegram);
     registerReactionTools(server, telegram);
+    registerTranscribeTools(server, telegram);
+    registerFactCheckTools(server, telegram);
     registerExtraTools(server, telegram);
     registerAccountTools(server, telegram);
+    registerBusinessTools(server, telegram);
     registerStickerTools(server, telegram);
     registerStoryTools(server, telegram);
     registerBoostTools(server, telegram);

package/dist/tools/messages.js

@@ -1,22 +1,34 @@
 import { z } from "zod";
-import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, sanitizeInputText, WRITE, } from "./shared.js";
 export function registerMessageTools(server, telegram) {
     server.registerTool("telegram-send-message", {
         description: "Send a message to a Telegram chat",
         inputSchema: {
             chatId: z.string().describe("Chat ID or username (e.g. @username or numeric ID)"),
-            text: z.string().describe("Message text"),
+            text: z.string().transform(sanitizeInputText).describe("Message text"),
             replyTo: z.number().optional().describe("Message ID to reply to"),
             parseMode: z.enum(["md", "html"]).optional().describe("Message format: md (Markdown) or html"),
             topicId: z.number().optional().describe("Forum topic ID to send message into (for groups with Topics enabled)"),
+            quoteText: z
+                .string()
+                .transform(sanitizeInputText)
+                .optional()
+                .describe("Optional excerpt from the replied-to message to show as a quote above your reply. " +
+                "Requires `replyTo` to be set. Must be a verbatim substring of the original message text."),
+            effect: z
+                .string()
+                .regex(/^\d{1,19}$/)
+                .optional()
+                .describe("Optional message effect ID (numeric string, up to 19 digits). Premium animated effect attached to the message."),
         },
         annotations: WRITE,
-    }, async ({ chatId, text, replyTo, parseMode, topicId }) => {
+    }, async ({ chatId, text, replyTo, parseMode, topicId, quoteText, effect }) => {
         const err = await requireConnection(telegram);
         if (err)
             return fail(new Error(err));
         try {
-            const result = await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+            const extra = quoteText || effect ? { quoteText, effect } : undefined;
+            const result = await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId, extra);
             const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
             const messageId = result?.id;
             const idInfo = messageId ? ` [#${messageId}]` : "";
@@ -586,4 +598,171 @@ export function registerMessageTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-discussion-message", {
+        description: "For a channel post with comments enabled, returns the linked discussion-group info: discussionGroupId, discussionMsgId, unreadCount, readInboxMaxId, readOutboxMaxId, topMessage. Use discussionGroupId + discussionMsgId with telegram-send-message (replyTo=discussionMsgId) to post a comment.",
+        inputSchema: {
+            chatId: z.string().describe("Channel ID or @username that contains the post"),
+            messageId: z.number().int().positive().describe("ID of the channel post to get discussion info for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getDiscussionMessage(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-groups-for-discussion", {
+        description: "List groups that can be linked as a discussion group to a channel you admin. Helper for channel admins setting up comment threads.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getGroupsForDiscussion();
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-message-read-participants", {
+        description: "List who has read a message in a small group (≤100 members, ≤7 days old). Returns readers with userId, readAt timestamp. Does NOT work for channels or groups over 100 members (CHAT_TOO_BIG).",
+        inputSchema: {
+            chatId: z.string().describe("Group chat ID or @username"),
+            messageId: z.number().int().positive().describe("ID of the message to check read status for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMessageReadParticipants(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    // ─── Poll interaction ──────────────────────────────────────────────────────
+    server.registerTool("telegram-vote-poll", {
+        description: "Vote in a poll by option index (single or multi-choice). Empty array retracts vote.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+            optionIndexes: z
+                .array(z.number().int().min(0).max(9))
+                .min(0)
+                .max(10)
+                .describe("Zero-based option indexes. Empty [] retracts vote."),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, optionIndexes }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.sendPollVote(chatId, messageId, optionIndexes);
+            if (optionIndexes.length === 0) {
+                return ok(`Retracted vote from poll #${messageId}`);
+            }
+            return ok(`Voted in poll #${messageId}: option(s) ${result.chosenLabels.join(", ")} | Total: ${result.totalVoters} voters`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-poll-results", {
+        description: "Get aggregated poll results: vote counts, percentages, quiz answer status",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPollResults(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-poll-voters", {
+        description: "List users who voted for specific poll options (public polls only, paginated)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+            optionIndex: z
+                .number()
+                .int()
+                .min(0)
+                .max(9)
+                .optional()
+                .describe("Zero-based option index to filter by. Omit to get all voters"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max voters to return"),
+            offset: z.string().optional().describe("Pagination offset from previous call"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId, optionIndex, limit, offset }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPollVoters(chatId, messageId, { optionIndex, limit, offset });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-close-poll", {
+        description: "Close a poll permanently. This is a one-way operation — closed polls cannot be reopened.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll to close"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.closePoll(chatId, messageId);
+            return ok(`Closed poll #${messageId} (final: ${result.totalVoters} voters)`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-outbox-read-date", {
+        description: "Get when your recipient read your outgoing message in a private chat. Returns null/Not read yet if unread. Errors if the other side disabled read receipts (YOUR_PRIVACY_RESTRICTED / USER_PRIVACY_RESTRICTED).",
+        inputSchema: {
+            chatId: z.string().describe("Private chat ID or @username of the recipient"),
+            messageId: z.number().int().positive().describe("ID of your outgoing message"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getOutboxReadDate(chatId, messageId);
+            return ok(result.readAt ? `Read at ${result.readAt}` : "Not read yet");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }