@overpod/mcp-telegram 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [1.40.0](https://github.com/mcp-telegram/mcp-telegram/compare/v1.39.1...v1.40.0) (2026-06-23)
+
+
+### Added
+
+* **media:** add thumbnail option to downloadMediaAsBuffer ([#64](https://github.com/mcp-telegram/mcp-telegram/issues/64)) ([d9f302c](https://github.com/mcp-telegram/mcp-telegram/commit/d9f302c8efde73a8d86467b23d05b8a12650662f))
+
+## [1.39.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.39.0...v1.39.1) (2026-06-21)
+
+
+### Fixed
+
+* **resolve:** recover bare numeric peer IDs that lack access_hash ([#62](https://github.com/mcp-telegram/mcp-telegram/issues/62)) ([678077a](https://github.com/mcp-telegram/mcp-telegram/commit/678077a78ce3a5852e07d5d831f664c3e08a81e3))
+
 ## [1.39.0](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.2...v1.39.0) (2026-06-21)
 
 

package/dist/telegram-client.d.ts

@@ -142,9 +142,30 @@ export declare class TelegramService {
         ids: number[];
     }>;
     downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
-    downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
+    /**
+     * Download a message's media into memory.
+     *
+     * When `options.thumb` is given, GramJS fetches that thumbnail size instead of
+     * the full file (`0` = smallest, larger indexes = bigger previews). This keeps
+     * payloads tiny — useful for callers that inline the bytes and pay per byte
+     * (e.g. base64 in an LLM context). If the message has no thumbnail at that
+     * index, GramJS returns an empty/`undefined` buffer; we transparently fall
+     * back to the full file so the caller always gets bytes. `isThumb` reports
+     * which one was served.
+     *
+     * Note: GramJS signals "no bytes" inconsistently — `undefined` for a missing
+     * thumbnail, but `Buffer.alloc(0)` for undownloadable media (geo/poll/dice,
+     * documents without a file, and several failure paths). An empty Buffer is
+     * truthy, so we guard on `.length`, not truthiness, in both the fallback and
+     * the final failure check — otherwise a 0-byte buffer would be returned as a
+     * "successful" (but garbage) download.
+     */
+    downloadMediaAsBuffer(chatId: string, messageId: number, options?: {
+        thumb?: number;
+    }): Promise<{
         buffer: Buffer;
         mimeType: string;
+        isThumb: boolean;
     }>;
     /** Detect MIME type from buffer magic bytes, falling back to media metadata */
     private detectMimeType;
@@ -276,6 +297,13 @@ export declare class TelegramService {
      * Handles display names by searching dialogs.
      */
     private resolvePeer;
+    /**
+     * Resolve a bare numeric ID to a cached/dialog entity so GramJS can build a
+     * valid InputPeer. Falls back to the raw ID string if no dialog matches —
+     * GramJS may still resolve it (e.g. a contact or a peer it has messaged),
+     * and we must not regress that path.
+     */
+    private resolveNumericPeer;
     getChatInfo(chatId: string): Promise<{
         id: string;
         name: string;

package/dist/telegram-client.js

@@ -708,7 +708,25 @@ export class TelegramService {
         await writeFile(downloadPath, buffer);
         return downloadPath;
     }
-    async downloadMediaAsBuffer(chatId, messageId) {
+    /**
+     * Download a message's media into memory.
+     *
+     * When `options.thumb` is given, GramJS fetches that thumbnail size instead of
+     * the full file (`0` = smallest, larger indexes = bigger previews). This keeps
+     * payloads tiny — useful for callers that inline the bytes and pay per byte
+     * (e.g. base64 in an LLM context). If the message has no thumbnail at that
+     * index, GramJS returns an empty/`undefined` buffer; we transparently fall
+     * back to the full file so the caller always gets bytes. `isThumb` reports
+     * which one was served.
+     *
+     * Note: GramJS signals "no bytes" inconsistently — `undefined` for a missing
+     * thumbnail, but `Buffer.alloc(0)` for undownloadable media (geo/poll/dice,
+     * documents without a file, and several failure paths). An empty Buffer is
+     * truthy, so we guard on `.length`, not truthiness, in both the fallback and
+     * the final failure check — otherwise a 0-byte buffer would be returned as a
+     * "successful" (but garbage) download.
+     */
+    async downloadMediaAsBuffer(chatId, messageId, options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
@@ -718,11 +736,19 @@ export class TelegramService {
             throw new Error(`Message ${messageId} not found`);
         if (!message.media)
             throw new Error(`Message ${messageId} has no media`);
-        const buffer = (await this.client.downloadMedia(message));
-        if (!buffer)
+        let isThumb = false;
+        let buffer;
+        if (options?.thumb !== undefined) {
+            buffer = (await this.client.downloadMedia(message, { thumb: options.thumb }));
+            isThumb = !!buffer?.length;
+        }
+        // No thumb requested, or this media has no thumbnail at that size → full file.
+        if (!buffer?.length)
+            buffer = (await this.client.downloadMedia(message));
+        if (!buffer?.length)
             throw new Error("Failed to download media");
         const mimeType = this.detectMimeType(buffer, message.media);
-        return { buffer, mimeType };
+        return { buffer, mimeType, isThumb };
     }
     /** Detect MIME type from buffer magic bytes, falling back to media metadata */
     detectMimeType(buffer, media) {
@@ -1191,12 +1217,78 @@ export class TelegramService {
         // Normalize '@me' — GramJS only intercepts the plain 'me' string as InputPeerSelf
         if (chatId === "@me")
             return "me";
-        // Numeric IDs and @usernames work directly
-        if (/^-?\d+$/.test(chatId) || chatId.startsWith("@"))
+        // @usernames resolve directly via contacts.ResolveUsername
+        if (chatId.startsWith("@"))
             return chatId;
-        // Everything else — resolve via dialogs
+        // Bare numeric IDs need an entity with access_hash. GramJS can build an
+        // InputPeer from a raw number only if it's already cached or the account
+        // is a contact / has messaged us — otherwise getInputEntity throws
+        // "Could not find the input entity". A bare positive number is also
+        // ambiguous (GramJS assumes PeerUser, so channel IDs fail outright).
+        // Recover by looking the ID up among dialogs, which yields a full entity
+        // (with access_hash) for both users and channels.
+        if (/^-?\d+$/.test(chatId))
+            return this.resolveNumericPeer(chatId);
+        // Everything else — resolve display name via dialogs
         return this.resolveChat(chatId);
     }
+    /**
+     * Resolve a bare numeric ID to a cached/dialog entity so GramJS can build a
+     * valid InputPeer. Falls back to the raw ID string if no dialog matches —
+     * GramJS may still resolve it (e.g. a contact or a peer it has messaged),
+     * and we must not regress that path.
+     */
+    async resolveNumericPeer(chatId) {
+        if (!this.client)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const cached = this.entityCache.get(chatId);
+        if (cached)
+            return cached;
+        // Direct resolve first — succeeds when GramJS already knows the peer.
+        try {
+            const entity = await this.client.getEntity(chatId);
+            this.entityCache.set(chatId, entity);
+            return entity;
+        }
+        catch {
+            // Fall through to dialog scan.
+        }
+        // Scan dialogs for a matching entity. IDs reach us in two shapes:
+        //   • bare positive  (e.g. 1004294063929 for a channel, 8959122940 for a
+        //     user) — this is what list-chats/search emit and what GramJS can't
+        //     disambiguate; match it against any entity's bare id.
+        //   • marked         (-100<id> for channels, -<id> for basic groups) — the
+        //     sign/-100 prefix carries the type, so require the entity to match that
+        //     exact marked form, otherwise a group "-123" could wrongly match a user
+        //     with bare id 123.
+        const isMarked = chatId.startsWith("-");
+        try {
+            const dialogs = await this.client.getDialogs({ limit: 100 });
+            const match = dialogs.find((d) => {
+                const entity = d.entity;
+                if (!entity?.id)
+                    return false;
+                const bare = entity.id.toString();
+                if (!isMarked)
+                    return chatId === bare;
+                // Marked input must match the entity's marked form.
+                if (entity instanceof Api.Channel)
+                    return chatId === `-100${bare}`;
+                if (entity instanceof Api.Chat)
+                    return chatId === `-${bare}`;
+                return false;
+            });
+            if (match?.entity) {
+                this.entityCache.set(chatId, match.entity);
+                return match.entity;
+            }
+        }
+        catch {
+            // Dialog fetch failed — fall back to the raw ID below.
+        }
+        // Last resort: hand the raw ID to GramJS and let it try GetUsers/GetChannels.
+        return chatId;
+    }
     async getChatInfo(chatId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -72,7 +72,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",
     "tsx": "^4.22.4",