@overpod/mcp-telegram 1.8.1 → 1.10.0

package/dist/index.js

@@ -183,7 +183,7 @@ server.tool("telegram-search-chats", "Search for Telegram chats/users/channels b
     try {
         const results = await telegram.searchChats(query, limit);
         const text = results
-            .map((c) => `${c.type === "group" ? "G" : c.type === "channel" ? "C" : "P"} ${c.name}${c.username ? ` (@${c.username})` : ""} (${c.id})`)
+            .map((c) => `${c.type === "group" ? "G" : c.type === "channel" ? "C" : "P"} ${c.name}${c.username ? ` (@${c.username})` : ""} (${c.id})${c.membersCount ? ` [${c.membersCount} members]` : ""}${c.description ? ` — ${c.description.split("\n")[0].slice(0, 100)}` : ""}`)
             .join("\n");
         return { content: [{ type: "text", text: text || "No results" }] };
     }
@@ -191,6 +191,26 @@ server.tool("telegram-search-chats", "Search for Telegram chats/users/channels b
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
+server.tool("telegram-search-global", "Search messages globally across all public Telegram chats and channels", {
+    query: z.string().describe("Search text"),
+    limit: z.number().default(20).describe("Max results"),
+    minDate: z.number().optional().describe("Unix timestamp: only messages after this date"),
+    maxDate: z.number().optional().describe("Unix timestamp: only messages before this date"),
+}, async ({ query, limit, minDate, maxDate }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const messages = await telegram.searchGlobal(query, limit, minDate, maxDate);
+        const text = messages
+            .map((m) => `[${m.date}] [${m.chat.type === "channel" ? "C" : m.chat.type === "group" ? "G" : "P"} ${m.chat.name}${m.chat.username ? ` @${m.chat.username}` : ""}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+            .join("\n\n");
+        return { content: [{ type: "text", text: text || "No messages found" }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
 server.tool("telegram-search-messages", "Search messages in a Telegram chat by text", {
     chatId: z.string().describe("Chat ID or username"),
     query: z.string().describe("Search text"),
@@ -424,7 +444,7 @@ server.tool("telegram-get-chat-members", "Get members of a Telegram group or cha
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
-server.tool("telegram-get-profile", "Get detailed profile info of a Telegram user", {
+server.tool("telegram-get-profile", "Get detailed profile info of a Telegram user including bio, birthday, business info and more", {
     userId: z.string().describe("User ID or username"),
 }, async ({ userId }) => {
     const err = await requireConnection();
@@ -439,7 +459,13 @@ server.tool("telegram-get-profile", "Get detailed profile info of a Telegram use
             ...(profile.phone ? [`Phone: +${profile.phone}`] : []),
             ...(profile.bio ? [`Bio: ${profile.bio}`] : []),
             `Photo: ${profile.photo ? "yes" : "no"}`,
+            ...(profile.premium ? ["Premium: yes"] : []),
             ...(profile.lastSeen ? [`Last seen: ${profile.lastSeen}`] : []),
+            ...(profile.birthday ? [`Birthday: ${profile.birthday}`] : []),
+            ...(profile.commonChatsCount ? [`Common chats: ${profile.commonChatsCount}`] : []),
+            ...(profile.personalChannelId ? [`Personal channel ID: ${profile.personalChannelId}`] : []),
+            ...(profile.businessLocation ? [`Business location: ${profile.businessLocation}`] : []),
+            ...(profile.businessWorkHours ? [`Business hours timezone: ${profile.businessWorkHours}`] : []),
         ];
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -447,6 +473,39 @@ server.tool("telegram-get-profile", "Get detailed profile info of a Telegram use
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
+server.tool("telegram-get-profile-photo", "Download profile photo of a Telegram user, group, or channel. Returns inline image or saves to file", {
+    entityId: z.string().describe("User/Chat/Channel ID or username"),
+    savePath: z.string().optional().describe("Absolute path to save file. If omitted, returns inline base64 image"),
+    size: z
+        .enum(["small", "big"])
+        .optional()
+        .describe("Photo size: 'small' (160x160) or 'big' (640x640). Default: big"),
+}, async ({ entityId, savePath, size }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const result = await telegram.downloadProfilePhoto(entityId, {
+            isBig: size !== "small",
+            savePath,
+        });
+        if (!result) {
+            return { content: [{ type: "text", text: "No profile photo found" }] };
+        }
+        if ("filePath" in result) {
+            return { content: [{ type: "text", text: `Downloaded to: ${result.filePath}` }] };
+        }
+        return {
+            content: [
+                { type: "image", data: result.buffer.toString("base64"), mimeType: result.mimeType },
+                { type: "text", text: `Profile photo (${(result.buffer.length / 1024).toFixed(0)} KB, ${result.mimeType})` },
+            ],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
 server.tool("telegram-join-chat", "Join a Telegram group or channel by username or invite link", {
     target: z.string().describe("Username (@group), link (t.me/group), or invite link (t.me/+xxx)"),
 }, async ({ target }) => {

package/dist/telegram-client.d.ts

@@ -116,6 +116,25 @@ export declare class TelegramService {
         name: string;
         type: string;
         username?: string;
+        membersCount?: number;
+        description?: string;
+    }>>;
+    searchGlobal(query: string, limit?: number, minDate?: number, maxDate?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        chat: {
+            id: string;
+            name: string;
+            type: string;
+            username?: string;
+        };
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
     }>>;
     searchMessages(chatId: string, query: string, limit?: number, minDate?: number, maxDate?: number): Promise<Array<{
         id: number;
@@ -147,7 +166,24 @@ export declare class TelegramService {
         bio?: string;
         photo: boolean;
         lastSeen?: string;
+        premium?: boolean;
+        birthday?: string;
+        commonChatsCount?: number;
+        personalChannelId?: string;
+        businessWorkHours?: string;
+        businessLocation?: string;
     }>;
+    downloadProfilePhoto(entityId: string, options?: {
+        isBig?: boolean;
+        savePath?: string;
+    }): Promise<{
+        buffer: Buffer;
+        mimeType: string;
+    } | {
+        filePath: string;
+    } | null>;
+    /** Detect MIME type from buffer magic bytes */
+    private detectMimeFromBuffer;
     sendReaction(chatId: string, messageId: number, emoji?: string): Promise<void>;
     sendScheduledMessage(chatId: string, text: string, scheduleDate: number, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
     createPoll(chatId: string, question: string, answers: string[], options?: {

package/dist/telegram-client.js

@@ -642,7 +642,12 @@ export class TelegramService {
         }
         for (const chat of result.chats) {
             if (chat instanceof Api.Chat) {
-                chats.push({ id: chat.id.toString(), name: chat.title, type: "group" });
+                chats.push({
+                    id: chat.id.toString(),
+                    name: chat.title,
+                    type: "group",
+                    membersCount: chat.participantsCount ?? undefined,
+                });
             }
             else if (chat instanceof Api.Channel) {
                 chats.push({
@@ -650,11 +655,104 @@ export class TelegramService {
                     name: chat.title,
                     type: chat.megagroup ? "group" : "channel",
                     username: chat.username ?? undefined,
+                    membersCount: chat.participantsCount ?? undefined,
                 });
             }
         }
+        // Enrich channels/groups with description and accurate members count
+        for (const chat of chats) {
+            if (chat.type === "private")
+                continue;
+            try {
+                const entity = await this.client.getEntity(chat.id);
+                if (entity instanceof Api.Channel) {
+                    const full = await this.client.invoke(new Api.channels.GetFullChannel({ channel: entity }));
+                    if (full.fullChat instanceof Api.ChannelFull) {
+                        chat.description = full.fullChat.about || undefined;
+                        chat.membersCount = full.fullChat.participantsCount ?? chat.membersCount;
+                    }
+                }
+                else if (entity instanceof Api.Chat) {
+                    const full = await this.client.invoke(new Api.messages.GetFullChat({ chatId: entity.id }));
+                    if (full.fullChat instanceof Api.ChatFull) {
+                        chat.description = full.fullChat.about || undefined;
+                    }
+                }
+            }
+            catch {
+                // Skip enrichment on error (private channels, etc.)
+            }
+        }
         return chats;
     }
+    async searchGlobal(query, limit = 20, minDate, maxDate) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const result = await this.client.invoke(new Api.messages.SearchGlobal({
+            q: query,
+            filter: new Api.InputMessagesFilterEmpty(),
+            minDate: minDate || 0,
+            maxDate: maxDate || 0,
+            offsetRate: 0,
+            offsetPeer: new Api.InputPeerEmpty(),
+            offsetId: 0,
+            limit,
+        }));
+        const chatsMap = new Map();
+        if ("chats" in result) {
+            for (const chat of result.chats) {
+                if (chat instanceof Api.Channel) {
+                    chatsMap.set(chat.id.toString(), {
+                        id: chat.id.toString(),
+                        name: chat.title,
+                        type: chat.megagroup ? "group" : "channel",
+                        username: chat.username ?? undefined,
+                    });
+                }
+                else if (chat instanceof Api.Chat) {
+                    chatsMap.set(chat.id.toString(), {
+                        id: chat.id.toString(),
+                        name: chat.title,
+                        type: "group",
+                    });
+                }
+            }
+        }
+        if ("users" in result) {
+            for (const user of result.users) {
+                if (user instanceof Api.User) {
+                    const parts = [user.firstName, user.lastName].filter(Boolean);
+                    chatsMap.set(user.id.toString(), {
+                        id: user.id.toString(),
+                        name: parts.join(" ") || "Unknown",
+                        type: "private",
+                        username: user.username ?? undefined,
+                    });
+                }
+            }
+        }
+        const rawMessages = "messages" in result ? result.messages : [];
+        const messages = rawMessages.filter((m) => m instanceof Api.Message);
+        const results = await Promise.all(messages.map(async (m) => {
+            const peerId = m.peerId;
+            let chatId = "";
+            if (peerId instanceof Api.PeerChannel)
+                chatId = peerId.channelId.toString();
+            else if (peerId instanceof Api.PeerChat)
+                chatId = peerId.chatId.toString();
+            else if (peerId instanceof Api.PeerUser)
+                chatId = peerId.userId.toString();
+            return {
+                id: m.id,
+                text: m.message ?? "",
+                sender: await this.resolveSenderName(m.senderId),
+                date: new Date((m.date ?? 0) * 1000).toISOString(),
+                chat: chatsMap.get(chatId) || { id: chatId, name: "Unknown", type: "unknown" },
+                media: this.extractMediaInfo(m.media),
+            };
+        }));
+        return results;
+    }
     async searchMessages(chatId, query, limit = 20, minDate, maxDate) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
@@ -721,7 +819,8 @@ export class TelegramService {
             throw new Error("Entity is not a user");
         const inputEntity = await this.client.getInputEntity(userId);
         const fullResult = await this.client.invoke(new Api.users.GetFullUser({ id: inputEntity }));
-        const bio = fullResult.fullUser.about ?? undefined;
+        const full = fullResult.fullUser;
+        const bio = full.about ?? undefined;
         const parts = [entity.firstName, entity.lastName].filter(Boolean);
         let lastSeen;
         if (entity.status instanceof Api.UserStatusOnline) {
@@ -739,6 +838,23 @@ export class TelegramService {
         else if (entity.status instanceof Api.UserStatusLastMonth) {
             lastSeen = "last month";
         }
+        let birthday;
+        if (full.birthday) {
+            const b = full.birthday;
+            birthday = b.year
+                ? `${b.year}-${String(b.month).padStart(2, "0")}-${String(b.day).padStart(2, "0")}`
+                : `${String(b.month).padStart(2, "0")}-${String(b.day).padStart(2, "0")}`;
+        }
+        let businessWorkHours;
+        if (full.businessWorkHours) {
+            const wh = full.businessWorkHours;
+            businessWorkHours = wh.timezoneId ?? "configured";
+        }
+        let businessLocation;
+        if (full.businessLocation) {
+            const loc = full.businessLocation;
+            businessLocation = loc.address ?? "configured";
+        }
         return {
             id: entity.id.toString(),
             name: parts.join(" ") || "Unknown",
@@ -747,8 +863,42 @@ export class TelegramService {
             bio,
             photo: !!entity.photo,
             lastSeen,
+            premium: entity.premium || undefined,
+            birthday,
+            commonChatsCount: full.commonChatsCount || undefined,
+            personalChannelId: full.personalChannelId ? full.personalChannelId.toString() : undefined,
+            businessWorkHours,
+            businessLocation,
         };
     }
+    async downloadProfilePhoto(entityId, options) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(entityId);
+        const buffer = (await this.client.downloadProfilePhoto(entity, {
+            isBig: options?.isBig !== false,
+        }));
+        if (!buffer || buffer.length === 0)
+            return null;
+        const mimeType = this.detectMimeFromBuffer(buffer);
+        if (options?.savePath) {
+            await writeFile(options.savePath, buffer);
+            return { filePath: options.savePath };
+        }
+        return { buffer, mimeType };
+    }
+    /** Detect MIME type from buffer magic bytes */
+    detectMimeFromBuffer(buffer) {
+        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";
+        return "image/jpeg"; // Telegram profile photos are almost always JPEG
+    }
     async sendReaction(chatId, messageId, emoji) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",