@overpod/mcp-telegram 1.9.0 → 1.10.1

package/dist/index.js

@@ -165,7 +165,7 @@ server.tool("telegram-read-messages", "Read recent messages from a Telegram chat
     try {
         const messages = await telegram.getMessages(chatId, limit, offsetId, minDate, maxDate);
         const text = messages
-            .map((m) => `[${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+            .map((m) => `[#${m.id}] [${m.date}] ${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" }] };
     }
@@ -203,7 +203,7 @@ server.tool("telegram-search-global", "Search messages globally across all publi
     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}` : ""}]` : ""}`)
+            .map((m) => `[#${m.id}] [${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" }] };
     }
@@ -224,7 +224,7 @@ server.tool("telegram-search-messages", "Search messages in a Telegram chat by t
     try {
         const messages = await telegram.searchMessages(chatId, query, limit, minDate, maxDate);
         const text = messages
-            .map((m) => `[${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+            .map((m) => `[#${m.id}] [${m.date}] ${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" }] };
     }
@@ -444,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();
@@ -459,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") }] };
     }
@@ -467,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 }) => {
@@ -664,7 +703,7 @@ server.tool("telegram-read-topic-messages", "Read messages from a specific forum
     try {
         const messages = await telegram.getTopicMessages(chatId, topicId, limit, offsetId);
         const text = messages
-            .map((m) => `[${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+            .map((m) => `[#${m.id}] [${m.date}] ${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 in this topic" }] };
     }

package/dist/telegram-client.d.ts

@@ -166,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

@@ -819,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) {
@@ -837,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",
@@ -845,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.9.0",
+  "version": "1.10.1",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",