@overpod/mcp-telegram 1.24.1 → 1.25.0

package/CHANGELOG.md

@@ -5,7 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.25.0] - 2026-04-20
+
+### Added
+- **Scheduled messages** — `telegram-get-scheduled`, `telegram-delete-scheduled`
+- **Threads & replies** — `telegram-get-replies` for channel post comments
+- **Message links** — `telegram-get-message-link` returns public t.me URL for a message
+- **Mentions & unread reactions** — `telegram-get-unread-mentions`, `telegram-get-unread-reactions`
+- **Translate** — `telegram-translate-message` (requires Telegram Premium)
+- **Typing indicator** — `telegram-send-typing` with configurable action
+- **Dialog management** — `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread`
+- **Drafts** — `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts`
+- **Saved Messages dialogs** — `telegram-get-saved-dialogs` for the new per-peer Saved Messages folders
+- **Admin log** — `telegram-get-admin-log` for channel/supergroup moderation history
+- **Reactions catalog** — `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions`
+- **Chat permissions** — `telegram-set-chat-permissions` for default banned rights
+- **Slow mode** — `telegram-set-slow-mode` for supergroups
+- **Forum topics CRUD** — `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic`
+- **Web page preview** — `telegram-get-web-preview` to inspect link previews before sending
+
+### Fixed
+- `telegram-set-chat-permissions` now merges with the chat's current `defaultBannedRights` — omitted flags keep their current state instead of being silently cleared
+- `telegram-clear-drafts` requires `chatId` (single-chat) or `confirmAllChats: true` to wipe drafts account-wide, preventing accidental loss of all drafts in one call
+- `telegram-get-unread-mentions` and `telegram-get-unread-reactions` are now annotated as `WRITE` — they mark the listed items as read on the server
+- `telegram-translate-message` is now annotated as `WRITE` (consumes Premium translate quota); `toLang` is validated against an ISO-639 / locale pattern and `messageIds` is capped at 1–100 positive integers
+- `telegram-delete-scheduled` caps `messageIds` at 1–100 positive integers
+- `telegram-set-default-reaction` validates `emoji` length (1–8 characters)
+- `telegram-get-web-preview` rejects non-`http(s)` URLs, preventing use as an SSRF proxy
+- `telegram-send-typing` throttles non-`cancel` actions to once per 10 seconds per chat
+- `telegram-get-saved-dialogs` no longer returns a hard-coded `unreadCount: 0`
+- `telegram-create-topic` now reads the new topic ID from `UpdateNewChannelMessage` (authoritative) and fails loudly if neither source is available
+- `telegram-save-draft` drops `replyTo` when the draft text is empty, avoiding `MESSAGE_EMPTY` errors when clearing drafts
+- Removed unused `chatMap` build in `getAdminLog`
 
 ## [1.24.1] - 2026-04-20
 

package/README.md

@@ -18,7 +18,7 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 
 ## Features
 
-- **59 tools** -- the most comprehensive Telegram MCP server available
+- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
@@ -304,21 +304,23 @@ const telegramMcp = new MCPClient({
 });
 ```
 
-## Tools (59)
+## Tools
 
 All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.
 
 | Category | Tools |
 |----------|-------|
 | **Auth** | `telegram-status`, `telegram-login` |
-| **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled` |
-| **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read` |
-| **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages` |
+| **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |
+| **Scheduled** | `telegram-get-scheduled`, `telegram-delete-scheduled` |
+| **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs` |
+| **Drafts** | `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts` |
+| **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic` |
 | **Polls** | `telegram-create-poll` |
-| **Reactions** | `telegram-send-reaction`, `telegram-get-reactions` |
+| **Reactions** | `telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions` |
 | **Stickers** | `telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets` |
-| **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo` |
-| **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role` |
+| **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview` |
+| **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |
 | **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |
 | **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |
 | **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |
@@ -326,7 +328,7 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Profiles** | `telegram-get-profile`, `telegram-update-profile` |
 | **Account** | `telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete` |
 | **Pinning** | `telegram-pin-message`, `telegram-unpin-message` |
-| **Chat Settings** | `telegram-mute-chat` |
+| **Chat Settings** | `telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread` |
 
 > **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the full list with parameters and descriptions.
 

package/dist/__tests__/admin-log.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/admin-log.test.js

@@ -0,0 +1,41 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { Api } from "telegram/tl/index.js";
+import { describeAdminLogAction, describeAdminLogDetails } from "../telegram-client.js";
+describe("describeAdminLogAction", () => {
+    it("converts ChangeTitle to snake_case", () => {
+        const action = new Api.ChannelAdminLogEventActionChangeTitle({ prevValue: "a", newValue: "b" });
+        assert.strictEqual(describeAdminLogAction(action), "change_title");
+    });
+    it("converts ParticipantJoin to snake_case", () => {
+        const action = new Api.ChannelAdminLogEventActionParticipantJoin();
+        assert.strictEqual(describeAdminLogAction(action), "participant_join");
+    });
+    it("handles ToggleSlowMode", () => {
+        const action = new Api.ChannelAdminLogEventActionToggleSlowMode({ prevValue: 0, newValue: 30 });
+        assert.strictEqual(describeAdminLogAction(action), "toggle_slow_mode");
+    });
+    it("handles ChangeHistoryTTL without splitting acronym", () => {
+        const action = new Api.ChannelAdminLogEventActionChangeHistoryTTL({ prevValue: 0, newValue: 86400 });
+        assert.strictEqual(describeAdminLogAction(action), "change_history_ttl");
+    });
+});
+describe("describeAdminLogDetails", () => {
+    const describeUser = (id) => `user_${id.toString()}`;
+    it("formats title change", () => {
+        const action = new Api.ChannelAdminLogEventActionChangeTitle({ prevValue: "old", newValue: "new" });
+        assert.strictEqual(describeAdminLogDetails(action, describeUser), '"old" → "new"');
+    });
+    it("formats username change", () => {
+        const action = new Api.ChannelAdminLogEventActionChangeUsername({ prevValue: "old", newValue: "new" });
+        assert.strictEqual(describeAdminLogDetails(action, describeUser), "@old → @new");
+    });
+    it("formats slow mode change", () => {
+        const action = new Api.ChannelAdminLogEventActionToggleSlowMode({ prevValue: 0, newValue: 30 });
+        assert.strictEqual(describeAdminLogDetails(action, describeUser), "0s → 30s");
+    });
+    it("returns empty string for unknown actions", () => {
+        const action = new Api.ChannelAdminLogEventActionParticipantJoin();
+        assert.strictEqual(describeAdminLogDetails(action, describeUser), "");
+    });
+});

package/dist/__tests__/reactions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/reactions.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import bigInt from "big-integer";
+import { Api } from "telegram/tl/index.js";
+import { reactionToEmoji } from "../telegram-client.js";
+describe("reactionToEmoji", () => {
+    it("returns emoticon for ReactionEmoji", () => {
+        const r = new Api.ReactionEmoji({ emoticon: "👍" });
+        assert.strictEqual(reactionToEmoji(r), "👍");
+    });
+    it("returns custom:<id> for ReactionCustomEmoji", () => {
+        const r = new Api.ReactionCustomEmoji({ documentId: bigInt(12345) });
+        assert.strictEqual(reactionToEmoji(r), "custom:12345");
+    });
+    it("returns star for ReactionPaid", () => {
+        const r = new Api.ReactionPaid();
+        assert.strictEqual(reactionToEmoji(r), "⭐");
+    });
+    it("returns null for ReactionEmpty", () => {
+        const r = new Api.ReactionEmpty();
+        assert.strictEqual(reactionToEmoji(r), null);
+    });
+});

package/dist/__tests__/set-chat-permissions-merge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/set-chat-permissions-merge.test.js

@@ -0,0 +1,107 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import bigInt from "big-integer";
+import { Api } from "telegram/tl/index.js";
+import { mergeBannedRights, TelegramService } from "../telegram-client.js";
+describe("mergeBannedRights", () => {
+    it("preserves omitted flags from current rights", () => {
+        const current = { pinMessages: true, inviteUsers: true, sendMessages: false };
+        const merged = mergeBannedRights(current, { sendMessages: false });
+        assert.strictEqual(merged.sendMessages, true, "user-specified denial applies");
+        assert.strictEqual(merged.pinMessages, true, "omitted flag stays banned");
+        assert.strictEqual(merged.inviteUsers, true, "omitted flag stays banned");
+        assert.strictEqual(merged.sendMedia, false, "omitted flag with no current stays unbanned");
+    });
+    it("user-provided value overrides current", () => {
+        const current = { pinMessages: true };
+        const merged = mergeBannedRights(current, { pinMessages: true });
+        assert.strictEqual(merged.pinMessages, false, "pinMessages:true allowed -> not banned");
+    });
+    it("fills missing flags with false when current is undefined", () => {
+        const merged = mergeBannedRights(undefined, { sendMessages: true });
+        assert.strictEqual(merged.sendMessages, false);
+        assert.strictEqual(merged.sendMedia, false);
+        assert.strictEqual(merged.pinMessages, false);
+    });
+    it("covers all nineteen flags (10 exposed + 9 extra preserved)", () => {
+        const merged = mergeBannedRights(undefined, {});
+        const keys = Object.keys(merged).sort();
+        assert.deepStrictEqual(keys, [
+            "changeInfo",
+            "embedLinks",
+            "inviteUsers",
+            "manageTopics",
+            "pinMessages",
+            "sendAudios",
+            "sendDocs",
+            "sendGames",
+            "sendGifs",
+            "sendInline",
+            "sendMedia",
+            "sendMessages",
+            "sendPhotos",
+            "sendPlain",
+            "sendPolls",
+            "sendRoundvideos",
+            "sendStickers",
+            "sendVideos",
+            "sendVoices",
+        ]);
+    });
+});
+describe("TelegramService.setChatPermissions", () => {
+    it("merges new permissions with existing defaultBannedRights", async () => {
+        const existingRights = new Api.ChatBannedRights({
+            untilDate: 0,
+            pinMessages: true,
+            inviteUsers: true,
+        });
+        const channel = new Api.Channel({
+            id: bigInt(12345),
+            title: "test",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            defaultBannedRights: existingRights,
+        });
+        const inputChannel = new Api.InputPeerChannel({ channelId: bigInt(12345), accessHash: bigInt(1) });
+        const invocations = [];
+        const fakeClient = {
+            invoke: async (req) => {
+                invocations.push(req);
+                if (req instanceof Api.channels.GetFullChannel) {
+                    return new Api.messages.ChatFull({
+                        fullChat: new Api.ChannelFull({
+                            id: bigInt(12345),
+                            about: "",
+                            readInboxMaxId: 0,
+                            readOutboxMaxId: 0,
+                            unreadCount: 0,
+                            chatPhoto: new Api.PhotoEmpty({ id: bigInt(0) }),
+                            notifySettings: new Api.PeerNotifySettings({}),
+                            pts: 0,
+                            botInfo: [],
+                        }),
+                        chats: [channel],
+                        users: [],
+                    });
+                }
+                return undefined;
+            },
+            getInputEntity: async () => inputChannel,
+        };
+        const service = new TelegramService(1, "hash");
+        const internals = service;
+        internals.client = fakeClient;
+        internals.connected = true;
+        internals.resolveChat = async () => channel;
+        await service.setChatPermissions("12345", { sendMessages: false });
+        const editCall = invocations.find((r) => r instanceof Api.messages.EditChatDefaultBannedRights);
+        assert.ok(editCall, "EditChatDefaultBannedRights was invoked");
+        const rights = editCall.bannedRights;
+        assert.strictEqual(rights.sendMessages, true, "sendMessages becomes banned");
+        assert.strictEqual(rights.pinMessages, true, "pinMessages stays banned (preserved)");
+        assert.strictEqual(rights.inviteUsers, true, "inviteUsers stays banned (preserved)");
+        assert.strictEqual(rights.sendMedia, false, "omitted flag with no prior value stays unbanned");
+    });
+});

package/dist/telegram-client.d.ts

@@ -1,5 +1,22 @@
+import bigInt from "big-integer";
 import { TelegramClient } from "telegram";
 import { Api } from "telegram/tl/index.js";
+export declare function describeAdminLogAction(action: Api.TypeChannelAdminLogEventAction): string;
+export declare function describeAdminLogDetails(action: Api.TypeChannelAdminLogEventAction, describeUser: (userId: bigInt.BigInteger) => string): string;
+export declare function reactionToEmoji(reaction: Api.TypeReaction): string | null;
+export type ChatPermissions = {
+    sendMessages?: boolean;
+    sendMedia?: boolean;
+    sendStickers?: boolean;
+    sendGifs?: boolean;
+    sendPolls?: boolean;
+    sendInline?: boolean;
+    embedLinks?: boolean;
+    changeInfo?: boolean;
+    inviteUsers?: boolean;
+    pinMessages?: boolean;
+};
+export declare function mergeBannedRights(current: Record<string, unknown> | undefined | null, permissions: ChatPermissions): Record<string, boolean>;
 export declare class TelegramService {
     private client;
     private apiId;
@@ -8,6 +25,7 @@ export declare class TelegramService {
     private connected;
     private sessionPath;
     private rateLimiter;
+    private lastTypingAt;
     lastError: string;
     get sessionDir(): string;
     getClient(): TelegramClient | null;
@@ -87,8 +105,6 @@ export declare class TelegramService {
     blockUser(userId: string): Promise<void>;
     reportSpam(chatId: string): Promise<void>;
     markAsRead(chatId: string): Promise<void>;
-    private static TYPING_ACTIONS;
-    setTyping(chatId: string, action?: keyof typeof TelegramService.TYPING_ACTIONS): Promise<void>;
     getMessageById(chatId: string, messageId: number): Promise<{
         id: number;
         text: string;
@@ -108,6 +124,68 @@ export declare class TelegramService {
     forwardMessage(fromChatId: string, toChatId: string, messageIds: number[]): Promise<void>;
     editMessage(chatId: string, messageId: number, newText: string): Promise<void>;
     deleteMessages(chatId: string, messageIds: number[]): Promise<void>;
+    getScheduledMessages(chatId: string): Promise<Array<{
+        id: number;
+        date: string;
+        text: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    deleteScheduledMessages(chatId: string, messageIds: number[]): Promise<void>;
+    getReplies(chatId: string, messageId: number, limit?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+        reactions?: {
+            emoji: string;
+            count: number;
+            me: boolean;
+        }[];
+    }>>;
+    getMessageLink(chatId: string, messageId: number, thread?: boolean): Promise<string>;
+    getUnreadMentions(chatId: string, limit?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+        reactions?: {
+            emoji: string;
+            count: number;
+            me: boolean;
+        }[];
+    }>>;
+    getUnreadReactions(chatId: string, limit?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+        reactions?: {
+            emoji: string;
+            count: number;
+            me: boolean;
+        }[];
+    }>>;
+    translateText(chatId: string, messageIds: number[], toLang: string): Promise<string[]>;
+    sendTyping(chatId: string, action?: "typing" | "upload_photo" | "upload_document" | "cancel"): Promise<void>;
     /**
      * Resolve a chat by ID, username, or display name.
      * Falls back to searching user's dialogs if getEntity() fails.
@@ -258,6 +336,13 @@ export declare class TelegramService {
         }[];
         total: number;
     }>;
+    setDefaultReaction(emoji: string): Promise<void>;
+    getTopReactions(limit: number): Promise<Array<{
+        emoji: string;
+    }>>;
+    getRecentReactions(limit: number): Promise<Array<{
+        emoji: string;
+    }>>;
     sendScheduledMessage(chatId: string, text: string, scheduleDate: number, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
     createPoll(chatId: string, question: string, answers: string[], options?: {
         multipleChoice?: boolean;
@@ -327,6 +412,30 @@ export declare class TelegramService {
     removeAdmin(chatId: string, userId: string): Promise<void>;
     unblockUser(userId: string): Promise<void>;
     muteChat(chatId: string, muteUntil: number): Promise<void>;
+    archiveChat(chatId: string, archive: boolean): Promise<void>;
+    pinDialog(chatId: string, pin: boolean): Promise<void>;
+    markDialogUnread(chatId: string, unread: boolean): Promise<void>;
+    getAdminLog(chatId: string, limit?: number, q?: string): Promise<Array<{
+        id: string;
+        date: string;
+        userId: string;
+        userName: string;
+        action: string;
+        details: string;
+    }>>;
+    setChatPermissions(chatId: string, permissions: ChatPermissions): Promise<void>;
+    setSlowMode(chatId: string, seconds: number): Promise<void>;
+    createForumTopic(chatId: string, title: string, iconColor?: number, iconEmojiId?: string): Promise<{
+        id: number;
+        title: string;
+    }>;
+    editForumTopic(chatId: string, topicId: number, options: {
+        title?: string;
+        iconEmojiId?: string;
+        closed?: boolean;
+        hidden?: boolean;
+    }): Promise<void>;
+    deleteForumTopic(chatId: string, topicId: number): Promise<void>;
     exportInviteLink(chatId: string, options?: {
         expireDate?: number;
         usageLimit?: number;
@@ -391,6 +500,26 @@ export declare class TelegramService {
         count: number;
     }>>;
     sendSticker(chatId: string, stickerSetShortName: string, stickerIndex: number, replyTo?: number): Promise<Api.Message | Api.UpdateShortSentMessage | undefined>;
+    saveDraft(chatId: string, text: string, replyTo?: number): Promise<void>;
+    getAllDrafts(): Promise<Array<{
+        chatId: string;
+        chatTitle: string;
+        text: string;
+        date: string;
+    }>>;
+    clearAllDrafts(): Promise<void>;
+    getSavedDialogs(limit: number): Promise<Array<{
+        peerId: string;
+        peerTitle: string;
+        lastMsgId: number;
+    }>>;
+    getWebPreview(url: string): Promise<{
+        type: string;
+        url?: string;
+        title?: string;
+        description?: string;
+        siteName?: string;
+    } | null>;
     getRecentStickers(): Promise<Array<{
         id: string;
         accessHash: string;