@overpod/mcp-telegram 1.1.0

package/dist/telegram-client.js

@@ -0,0 +1,508 @@
+import { existsSync } from "node:fs";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import bigInt from "big-integer";
+import QRCode from "qrcode";
+import { TelegramClient } from "telegram";
+import { StringSession } from "telegram/sessions/index.js";
+import { Api } from "telegram/tl/index.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SESSION_FILE = join(__dirname, "..", ".telegram-session");
+export class TelegramService {
+    client = null;
+    apiId;
+    apiHash;
+    sessionString = "";
+    connected = false;
+    lastError = "";
+    constructor(apiId, apiHash) {
+        this.apiId = apiId;
+        this.apiHash = apiHash;
+    }
+    async loadSession() {
+        if (existsSync(SESSION_FILE)) {
+            this.sessionString = (await readFile(SESSION_FILE, "utf-8")).trim();
+            return true;
+        }
+        return false;
+    }
+    async saveSession(session) {
+        this.sessionString = session;
+        await writeFile(SESSION_FILE, session, "utf-8");
+    }
+    async connect() {
+        if (this.connected && this.client)
+            return true;
+        if (!this.sessionString) {
+            const loaded = await this.loadSession();
+            if (!loaded)
+                return false;
+        }
+        const session = new StringSession(this.sessionString);
+        this.client = new TelegramClient(session, this.apiId, this.apiHash, {
+            connectionRetries: 5,
+        });
+        try {
+            await this.client.connect();
+            // Verify session is still valid
+            await this.client.getMe();
+            this.connected = true;
+            return true;
+        }
+        catch (err) {
+            const error = err;
+            const msg = error.errorMessage || error.message || "";
+            // Auth revoked — delete invalid session
+            if (msg === "AUTH_KEY_UNREGISTERED" || msg === "SESSION_REVOKED" || msg === "USER_DEACTIVATED") {
+                await this.clearSession();
+                this.lastError = "Session revoked. Re-login required.";
+            }
+            // Network error — keep session, just report
+            else if (msg.includes("TIMEOUT") ||
+                msg.includes("ECONNREFUSED") ||
+                msg.includes("ENETUNREACH") ||
+                msg.includes("ENOTFOUND") ||
+                msg.includes("network")) {
+                this.lastError = `Network error: ${msg}. Session preserved, will retry on next call.`;
+            }
+            // Unknown error
+            else {
+                this.lastError = `Connection error: ${msg}`;
+            }
+            try {
+                await this.client.disconnect();
+            }
+            catch { }
+            this.client = null;
+            return false;
+        }
+    }
+    async clearSession() {
+        this.connected = false;
+        this.sessionString = "";
+        this.client = null;
+        if (existsSync(SESSION_FILE)) {
+            await unlink(SESSION_FILE);
+        }
+    }
+    /** Ensure connection is active, auto-reconnect if session exists */
+    async ensureConnected() {
+        if (this.connected && this.client) {
+            return true;
+        }
+        // Try to reconnect with saved session
+        return this.connect();
+    }
+    async disconnect() {
+        if (this.client && this.connected) {
+            await this.client.disconnect();
+            this.connected = false;
+            this.client = null;
+        }
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async startQrLogin(onQrDataUrl, onQrUrl) {
+        const session = new StringSession("");
+        const client = new TelegramClient(session, this.apiId, this.apiHash, {
+            connectionRetries: 5,
+        });
+        try {
+            await client.connect();
+            let loginAccepted = false;
+            let resolved = false;
+            let lastQrUrl = "";
+            client.addEventHandler((update) => {
+                if (update instanceof Api.UpdateLoginToken) {
+                    loginAccepted = true;
+                }
+            });
+            const maxAttempts = 30; // 5 minutes
+            for (let i = 0; i < maxAttempts && !resolved; i++) {
+                try {
+                    const result = await client.invoke(new Api.auth.ExportLoginToken({
+                        apiId: this.apiId,
+                        apiHash: this.apiHash,
+                        exceptIds: [],
+                    }));
+                    if (result instanceof Api.auth.LoginToken) {
+                        const base64url = Buffer.from(result.token).toString("base64url");
+                        const url = `tg://login?token=${base64url}`;
+                        if (url !== lastQrUrl) {
+                            lastQrUrl = url;
+                            const dataUrl = await QRCode.toDataURL(url, {
+                                width: 256,
+                                margin: 2,
+                            });
+                            onQrDataUrl(dataUrl);
+                            onQrUrl?.(url);
+                        }
+                    }
+                    else if (result instanceof Api.auth.LoginTokenMigrateTo) {
+                        await client._switchDC(result.dcId);
+                        const imported = await client.invoke(new Api.auth.ImportLoginToken({ token: result.token }));
+                        if (imported instanceof Api.auth.LoginTokenSuccess) {
+                            resolved = true;
+                            break;
+                        }
+                    }
+                    else if (result instanceof Api.auth.LoginTokenSuccess) {
+                        resolved = true;
+                        break;
+                    }
+                }
+                catch (err) {
+                    const error = err;
+                    if (error.errorMessage === "SESSION_PASSWORD_NEEDED") {
+                        await client.disconnect();
+                        return { success: false, message: "2FA enabled — QR login not supported with 2FA" };
+                    }
+                }
+                if (!resolved) {
+                    await new Promise((r) => setTimeout(r, loginAccepted ? 1500 : 10000));
+                }
+            }
+            if (resolved) {
+                const newSession = client.session.save();
+                await client.disconnect();
+                await this.saveSession(newSession);
+                // Reconnect with new session
+                this.sessionString = newSession;
+                await this.connect();
+                return { success: true, message: "Telegram login successful" };
+            }
+            await client.disconnect();
+            return { success: false, message: "QR login timeout" };
+        }
+        catch (err) {
+            try {
+                await client.disconnect();
+            }
+            catch { }
+            return { success: false, message: `Login failed: ${err.message}` };
+        }
+    }
+    async getMe() {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const me = await this.client.getMe();
+        const user = me;
+        return {
+            id: user.id.toString(),
+            username: user.username ?? undefined,
+            firstName: user.firstName ?? undefined,
+        };
+    }
+    async sendMessage(chatId, text, replyTo, parseMode) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.sendMessage(chatId, {
+            message: text,
+            ...(replyTo ? { replyTo } : {}),
+            ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
+        });
+    }
+    async sendFile(chatId, filePath, caption) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.sendFile(chatId, { file: filePath, caption });
+    }
+    async downloadMedia(chatId, messageId, downloadPath) {
+        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");
+        await writeFile(downloadPath, buffer);
+        return downloadPath;
+    }
+    async pinMessage(chatId, messageId, silent = false) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.pinMessage(chatId, messageId, { notify: !silent });
+    }
+    async unpinMessage(chatId, messageId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.unpinMessage(chatId, messageId);
+    }
+    async getDialogs(limit = 20, offsetDate, filterType) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const fetchLimit = filterType ? limit * 3 : limit;
+        const dialogs = await this.client.getDialogs({ limit: fetchLimit, ...(offsetDate ? { offsetDate } : {}) });
+        const mapped = dialogs.map((d) => ({
+            id: d.id?.toString() ?? "",
+            name: d.title ?? d.name ?? "Unknown",
+            type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
+            unreadCount: d.unreadCount,
+        }));
+        return filterType ? mapped.filter((d) => d.type === filterType).slice(0, limit) : mapped;
+    }
+    async getUnreadDialogs(limit = 20) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const dialogs = await this.client.getDialogs({ limit: limit * 3 });
+        return dialogs
+            .filter((d) => d.unreadCount > 0)
+            .slice(0, limit)
+            .map((d) => ({
+            id: d.id?.toString() ?? "",
+            name: d.title ?? d.name ?? "Unknown",
+            type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
+            unreadCount: d.unreadCount,
+        }));
+    }
+    async markAsRead(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.markAsRead(chatId);
+    }
+    async forwardMessage(fromChatId, toChatId, messageIds) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.forwardMessages(toChatId, { messages: messageIds, fromPeer: fromChatId });
+    }
+    async editMessage(chatId, messageId, newText) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.editMessage(chatId, { message: messageId, text: newText });
+    }
+    async deleteMessages(chatId, messageIds) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.deleteMessages(chatId, messageIds, { revoke: true });
+    }
+    async getChatInfo(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (entity instanceof Api.User) {
+            const parts = [entity.firstName, entity.lastName].filter(Boolean);
+            return {
+                id: entity.id.toString(),
+                name: parts.join(" ") || "Unknown",
+                type: "private",
+                username: entity.username ?? undefined,
+            };
+        }
+        if (entity instanceof Api.Channel) {
+            return {
+                id: entity.id.toString(),
+                name: entity.title,
+                type: entity.megagroup ? "group" : "channel",
+                username: entity.username ?? undefined,
+                membersCount: entity.participantsCount ?? undefined,
+            };
+        }
+        if (entity instanceof Api.Chat) {
+            return {
+                id: entity.id.toString(),
+                name: entity.title,
+                type: "group",
+                membersCount: entity.participantsCount ?? undefined,
+            };
+        }
+        return { id: chatId, name: "Unknown", type: "unknown" };
+    }
+    /** Extract media info from a message */
+    extractMediaInfo(media) {
+        if (!media)
+            return undefined;
+        if (media instanceof Api.MessageMediaPhoto) {
+            return { type: "photo" };
+        }
+        if (media instanceof Api.MessageMediaDocument && media.document instanceof Api.Document) {
+            const doc = media.document;
+            let type = "document";
+            let fileName;
+            for (const attr of doc.attributes) {
+                if (attr instanceof Api.DocumentAttributeVideo)
+                    type = "video";
+                else if (attr instanceof Api.DocumentAttributeAudio)
+                    type = "audio";
+                else if (attr instanceof Api.DocumentAttributeSticker)
+                    type = "sticker";
+                else if (attr instanceof Api.DocumentAttributeFilename)
+                    fileName = attr.fileName;
+            }
+            return { type, fileName, size: doc.size?.toJSNumber?.() ?? Number(doc.size) };
+        }
+        return undefined;
+    }
+    /** Resolve sender ID to a display name */
+    async resolveSenderName(senderId) {
+        if (!senderId || !this.client)
+            return "unknown";
+        try {
+            const entity = await this.client.getEntity(senderId);
+            if (entity instanceof Api.User) {
+                const parts = [entity.firstName, entity.lastName].filter(Boolean);
+                const name = parts.join(" ") || "Unknown";
+                return entity.username ? `${name} (@${entity.username})` : name;
+            }
+            if (entity instanceof Api.Channel || entity instanceof Api.Chat) {
+                return entity.title ?? "Group";
+            }
+            return senderId.toString();
+        }
+        catch {
+            return senderId.toString();
+        }
+    }
+    async getMessages(chatId, limit = 10, offsetId, minDate, maxDate) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const opts = {
+            limit,
+            ...(offsetId ? { offsetId } : {}),
+            ...(maxDate ? { offsetDate: maxDate } : {}),
+        };
+        const messages = await this.client.getMessages(chatId, opts);
+        let filtered = messages;
+        if (minDate) {
+            filtered = filtered.filter((m) => (m.date ?? 0) >= minDate);
+        }
+        const results = await Promise.all(filtered.map(async (m) => ({
+            id: m.id,
+            text: m.message ?? "",
+            sender: await this.resolveSenderName(m.senderId),
+            date: new Date((m.date ?? 0) * 1000).toISOString(),
+            media: this.extractMediaInfo(m.media),
+        })));
+        return results;
+    }
+    async searchChats(query, limit = 10) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const result = await this.client.invoke(new Api.contacts.Search({ q: query, limit }));
+        const chats = [];
+        for (const user of result.users) {
+            if (user instanceof Api.User) {
+                const parts = [user.firstName, user.lastName].filter(Boolean);
+                chats.push({
+                    id: user.id.toString(),
+                    name: parts.join(" ") || "Unknown",
+                    type: "private",
+                    username: user.username ?? undefined,
+                });
+            }
+        }
+        for (const chat of result.chats) {
+            if (chat instanceof Api.Chat) {
+                chats.push({ id: chat.id.toString(), name: chat.title, type: "group" });
+            }
+            else if (chat instanceof Api.Channel) {
+                chats.push({
+                    id: chat.id.toString(),
+                    name: chat.title,
+                    type: chat.megagroup ? "group" : "channel",
+                    username: chat.username ?? undefined,
+                });
+            }
+        }
+        return chats;
+    }
+    async searchMessages(chatId, query, limit = 20, minDate, maxDate) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const messages = await this.client.getMessages(chatId, {
+            search: query,
+            limit,
+            ...(maxDate ? { offsetDate: maxDate } : {}),
+        });
+        let filtered = messages;
+        if (minDate) {
+            filtered = filtered.filter((m) => (m.date ?? 0) >= minDate);
+        }
+        const results = await Promise.all(filtered.map(async (m) => ({
+            id: m.id,
+            text: m.message ?? "",
+            sender: await this.resolveSenderName(m.senderId),
+            date: new Date((m.date ?? 0) * 1000).toISOString(),
+            media: this.extractMediaInfo(m.media),
+        })));
+        return results;
+    }
+    async getContacts(limit = 50) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const result = await this.client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
+        if (!(result instanceof Api.contacts.Contacts))
+            return [];
+        const contacts = [];
+        for (const user of result.users) {
+            if (user instanceof Api.User) {
+                const parts = [user.firstName, user.lastName].filter(Boolean);
+                contacts.push({
+                    id: user.id.toString(),
+                    name: parts.join(" ") || "Unknown",
+                    username: user.username ?? undefined,
+                    phone: user.phone ?? undefined,
+                });
+            }
+        }
+        return contacts.slice(0, limit);
+    }
+    async getChatMembers(chatId, limit = 50) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const participants = await this.client.getParticipants(chatId, { limit });
+        const members = [];
+        for (const p of participants) {
+            if (p instanceof Api.User) {
+                const parts = [p.firstName, p.lastName].filter(Boolean);
+                members.push({
+                    id: p.id.toString(),
+                    name: parts.join(" ") || "Unknown",
+                    username: p.username ?? undefined,
+                });
+            }
+        }
+        return members;
+    }
+    async getProfile(userId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(userId);
+        if (!(entity instanceof Api.User))
+            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 parts = [entity.firstName, entity.lastName].filter(Boolean);
+        let lastSeen;
+        if (entity.status instanceof Api.UserStatusOnline) {
+            lastSeen = "online";
+        }
+        else if (entity.status instanceof Api.UserStatusOffline) {
+            lastSeen = new Date(entity.status.wasOnline * 1000).toISOString();
+        }
+        else if (entity.status instanceof Api.UserStatusRecently) {
+            lastSeen = "recently";
+        }
+        else if (entity.status instanceof Api.UserStatusLastWeek) {
+            lastSeen = "last week";
+        }
+        else if (entity.status instanceof Api.UserStatusLastMonth) {
+            lastSeen = "last month";
+        }
+        return {
+            id: entity.id.toString(),
+            name: parts.join(" ") || "Unknown",
+            username: entity.username ?? undefined,
+            phone: entity.phone ?? undefined,
+            bio,
+            photo: !!entity.photo,
+            lastSeen,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@overpod/mcp-telegram",
+  "version": "1.1.0",
+  "description": "MCP server for Telegram userbot — 20 tools for messages, media, contacts & more. Built on GramJS/MTProto.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-telegram": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "login": "node dist/qr-login-cli.js",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --fix src/",
+    "format": "biome format --write src/"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "telegram",
+    "gramjs",
+    "mtproto",
+    "userbot",
+    "claude",
+    "ai-tools"
+  ],
+  "author": "overpod",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/overpod/mcp-telegram.git"
+  },
+  "homepage": "https://github.com/overpod/mcp-telegram#readme",
+  "bugs": {
+    "url": "https://github.com/overpod/mcp-telegram/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "qrcode": "^1.5.4",
+    "telegram": "^2.26.22",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^25.4.0",
+    "@types/qrcode": "^1.5.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}