@overpod/mcp-telegram 1.1.0 → 1.3.1

package/README.md

@@ -83,9 +83,13 @@ claude mcp add telegram -s user \
   -- npx @overpod/mcp-telegram
 ```
 
-### Claude Desktop / Cursor / VS Code
+### Claude Desktop
 
-Add to your MCP configuration file:
+1. Open your config file:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add the Telegram server:
 
 ```json
 {
@@ -102,6 +106,18 @@ Add to your MCP configuration file:
 }
 ```
 
+3. Restart Claude Desktop.
+
+4. Ask Claude: **"Run telegram-login"** -- a QR code will appear. If the image is not visible, Claude will provide a browser link to view the QR code. Scan it in Telegram (**Settings > Devices > Link Desktop Device**).
+
+5. Ask Claude: **"Run telegram-status"** to verify the connection.
+
+> **Note**: No terminal required! Login works entirely through Claude Desktop.
+
+### Cursor / VS Code
+
+Add the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).
+
 ### Mastra
 
 ```typescript

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -48,8 +48,11 @@ server.tool("telegram-status", "Check Telegram connection status", {}, async ()
 });
 server.tool("telegram-login", "Login to Telegram via QR code. Returns QR image. IMPORTANT: pass the entire result to user without modifications.", {}, async () => {
     let qrDataUrl = "";
+    let qrRawUrl = "";
     const loginPromise = telegram.startQrLogin((dataUrl) => {
         qrDataUrl = dataUrl;
+    }, (url) => {
+        qrRawUrl = url;
     });
     // Wait for first QR to be generated
     const startTime = Date.now();
@@ -68,8 +71,20 @@ server.tool("telegram-login", "Login to Telegram via QR code. Returns QR image.
             console.error(`[mcp-telegram] Login failed: ${result.message}`);
         }
     });
-    // Return as MCP image content + markdown image as fallback
+    // Return as MCP image content + text with fallback options
     const base64 = qrDataUrl.replace(/^data:image\/png;base64,/, "");
+    const qrApiUrl = qrRawUrl
+        ? `https://api.qrserver.com/v1/create-qr-code/?size=256x256&data=${encodeURIComponent(qrRawUrl)}`
+        : "";
+    const instructions = [
+        "Scan this QR code in Telegram: **Settings → Devices → Link Desktop Device**.",
+        "",
+        qrApiUrl ? `If the QR image is not visible, open this link in your browser:\n${qrApiUrl}` : "",
+        "",
+        "After scanning, run **telegram-status** to verify the connection.",
+    ]
+        .filter(Boolean)
+        .join("\n");
     return {
         content: [
             {
@@ -79,7 +94,7 @@ server.tool("telegram-login", "Login to Telegram via QR code. Returns QR image.
             },
             {
                 type: "text",
-                text: `Scan QR in Telegram: Settings → Devices → Link Desktop Device.\n\nIf image not visible: ![QR](${qrDataUrl})\n\nAfter scanning, check with telegram-status.`,
+                text: instructions,
             },
         ],
     };

package/dist/qr-login-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/telegram-client.d.ts

@@ -0,0 +1,122 @@
+export declare class TelegramService {
+    private client;
+    private apiId;
+    private apiHash;
+    private sessionString;
+    private connected;
+    lastError: string;
+    constructor(apiId: number, apiHash: string);
+    loadSession(): Promise<boolean>;
+    /** Set session string in memory (for programmatic / hosted use) */
+    setSessionString(session: string): void;
+    /** Get the current session string (for external persistence) */
+    getSessionString(): string;
+    private saveSession;
+    connect(): Promise<boolean>;
+    clearSession(): Promise<void>;
+    /** Ensure connection is active, auto-reconnect if session exists */
+    ensureConnected(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    /**
+     * Log out from Telegram completely — terminates the session on Telegram servers.
+     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     */
+    logOut(): Promise<boolean>;
+    isConnected(): boolean;
+    startQrLogin(onQrDataUrl: (dataUrl: string) => void, onQrUrl?: (url: string) => void): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getMe(): Promise<{
+        id: string;
+        username?: string;
+        firstName?: string;
+    }>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
+    sendFile(chatId: string, filePath: string, caption?: string): Promise<void>;
+    downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
+    downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
+        buffer: Buffer;
+        mimeType: string;
+    }>;
+    /** Detect MIME type from buffer magic bytes, falling back to media metadata */
+    private detectMimeType;
+    pinMessage(chatId: string, messageId: number, silent?: boolean): Promise<void>;
+    unpinMessage(chatId: string, messageId: number): Promise<void>;
+    getDialogs(limit?: number, offsetDate?: number, filterType?: "private" | "group" | "channel"): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        unreadCount: number;
+    }>>;
+    getUnreadDialogs(limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        unreadCount: number;
+    }>>;
+    markAsRead(chatId: string): Promise<void>;
+    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>;
+    getChatInfo(chatId: string): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        username?: string;
+        description?: string;
+        membersCount?: number;
+    }>;
+    /** Extract media info from a message */
+    private extractMediaInfo;
+    /** Resolve sender ID to a display name */
+    private resolveSenderName;
+    getMessages(chatId: string, limit?: number, offsetId?: number, minDate?: number, maxDate?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    searchChats(query: string, limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        username?: string;
+    }>>;
+    searchMessages(chatId: string, query: string, limit?: number, minDate?: number, maxDate?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    getContacts(limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        username?: string;
+        phone?: string;
+    }>>;
+    getChatMembers(chatId: string, limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        username?: string;
+    }>>;
+    getProfile(userId: string): Promise<{
+        id: string;
+        name: string;
+        username?: string;
+        phone?: string;
+        bio?: string;
+        photo: boolean;
+        lastSeen?: string;
+    }>;
+}

package/dist/telegram-client.js

@@ -27,9 +27,22 @@ export class TelegramService {
         }
         return false;
     }
+    /** Set session string in memory (for programmatic / hosted use) */
+    setSessionString(session) {
+        this.sessionString = session;
+    }
+    /** Get the current session string (for external persistence) */
+    getSessionString() {
+        return this.sessionString;
+    }
     async saveSession(session) {
         this.sessionString = session;
-        await writeFile(SESSION_FILE, session, "utf-8");
+        try {
+            await writeFile(SESSION_FILE, session, "utf-8");
+        }
+        catch {
+            // File write may fail in containerized environments — session string is still in memory
+        }
     }
     async connect() {
         if (this.connected && this.client)
@@ -96,9 +109,29 @@ export class TelegramService {
     }
     async disconnect() {
         if (this.client && this.connected) {
-            await this.client.disconnect();
+            await this.client.destroy();
+            this.connected = false;
+            this.client = null;
+        }
+    }
+    /**
+     * Log out from Telegram completely — terminates the session on Telegram servers.
+     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     */
+    async logOut() {
+        if (!this.client || !this.connected)
+            return false;
+        try {
+            await this.client.invoke(new Api.auth.LogOut());
             this.connected = false;
+            this.sessionString = "";
             this.client = null;
+            return true;
+        }
+        catch (error) {
+            console.error("[telegram] logOut error:", error);
+            await this.disconnect();
+            return false;
         }
     }
     isConnected() {
@@ -224,6 +257,41 @@ export class TelegramService {
         await writeFile(downloadPath, buffer);
         return downloadPath;
     }
+    async downloadMediaAsBuffer(chatId, messageId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const messages = await this.client.getMessages(chatId, { ids: [messageId] });
+        const message = messages[0];
+        if (!message)
+            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)
+            throw new Error("Failed to download media");
+        const mimeType = this.detectMimeType(buffer, message.media);
+        return { buffer, mimeType };
+    }
+    /** Detect MIME type from buffer magic bytes, falling back to media metadata */
+    detectMimeType(buffer, media) {
+        // Check magic bytes first
+        if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF)
+            return "image/jpeg";
+        if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47)
+            return "image/png";
+        if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46)
+            return "image/gif";
+        if (buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46)
+            return "image/webp";
+        // Fall back to document mimeType
+        const m = media;
+        const doc = m.document;
+        if (doc?.mimeType)
+            return doc.mimeType;
+        if (m.photo)
+            return "image/jpeg";
+        return "application/octet-stream";
+    }
     async pinMessage(chatId, messageId, silent = false) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
@@ -295,20 +363,48 @@ export class TelegramService {
             };
         }
         if (entity instanceof Api.Channel) {
+            let membersCount = entity.participantsCount ?? undefined;
+            let description;
+            try {
+                const full = await this.client.invoke(new Api.channels.GetFullChannel({ channel: entity }));
+                if (full.fullChat instanceof Api.ChannelFull) {
+                    membersCount = membersCount ?? full.fullChat.participantsCount ?? undefined;
+                    description = full.fullChat.about || undefined;
+                }
+            }
+            catch {
+                // May fail for some channels — fall back to basic info
+            }
             return {
                 id: entity.id.toString(),
                 name: entity.title,
                 type: entity.megagroup ? "group" : "channel",
                 username: entity.username ?? undefined,
-                membersCount: entity.participantsCount ?? undefined,
+                description,
+                membersCount,
             };
         }
         if (entity instanceof Api.Chat) {
+            let membersCount = entity.participantsCount ?? undefined;
+            let description;
+            try {
+                const full = await this.client.invoke(new Api.messages.GetFullChat({ chatId: entity.id }));
+                if (full.fullChat instanceof Api.ChatFull) {
+                    if (!membersCount && full.fullChat.participants instanceof Api.ChatParticipants) {
+                        membersCount = full.fullChat.participants.participants.length;
+                    }
+                    description = full.fullChat.about || undefined;
+                }
+            }
+            catch {
+                // Fall back to basic info
+            }
             return {
                 id: entity.id.toString(),
                 name: entity.title,
                 type: "group",
-                membersCount: entity.participantsCount ?? undefined,
+                description,
+                membersCount,
             };
         }
         return { id: chatId, name: "Unknown", type: "unknown" };

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "description": "MCP server for Telegram userbot — 20 tools for messages, media, contacts & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./service": "./dist/telegram-client.js"
+  },
   "bin": {
     "mcp-telegram": "dist/cli.js"
   },