@overpod/mcp-telegram 1.12.0 → 1.14.0

package/dist/telegram-client.js

@@ -17,6 +17,24 @@ const MIN_SESSION_LENGTH = 100;
 function resolveSessionPath(sessionPath) {
     return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
 }
+function resolveProxy() {
+    const ip = process.env.TELEGRAM_PROXY_IP;
+    const port = process.env.TELEGRAM_PROXY_PORT;
+    if (!ip || !port)
+        return undefined;
+    const secret = process.env.TELEGRAM_PROXY_SECRET;
+    if (secret) {
+        return { ip, port: Number(port), secret, MTProxy: true };
+    }
+    const socksType = Number(process.env.TELEGRAM_PROXY_SOCKS_TYPE || "5");
+    return {
+        ip,
+        port: Number(port),
+        socksType: socksType,
+        ...(process.env.TELEGRAM_PROXY_USERNAME && { username: process.env.TELEGRAM_PROXY_USERNAME }),
+        ...(process.env.TELEGRAM_PROXY_PASSWORD && { password: process.env.TELEGRAM_PROXY_PASSWORD }),
+    };
+}
 function ensureSessionDir(filePath) {
     const dir = dirname(filePath);
     if (!existsSync(dir)) {
@@ -96,8 +114,10 @@ export class TelegramService {
                 return false;
         }
         const session = new StringSession(this.sessionString);
+        const proxy = resolveProxy();
         this.client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            ...(proxy && { proxy }),
         });
         try {
             await this.client.connect();
@@ -183,8 +203,10 @@ export class TelegramService {
     }
     async startQrLogin(onQrDataUrl, onQrUrl) {
         const session = new StringSession("");
+        const proxy = resolveProxy();
         const client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            ...(proxy && { proxy }),
         });
         try {
             await client.connect();
@@ -1003,7 +1025,7 @@ export class TelegramService {
                         for (const r of list.reactions) {
                             const userId = r.peerId instanceof Api.PeerUser ? r.peerId.userId.toString() : "";
                             if (userId) {
-                                const name = await this.resolveSenderName(bigInt(Number.parseInt(userId)));
+                                const name = await this.resolveSenderName(bigInt(Number.parseInt(userId, 10)));
                                 users.push({ id: userId, name });
                             }
                         }

package/dist/tools/auth.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerAuthTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/auth.js

@@ -0,0 +1,72 @@
+import { fail, ok, READ_ONLY, WRITE } from "./shared.js";
+export function registerAuthTools(server, telegram) {
+    server.registerTool("telegram-status", { description: "Check Telegram connection status", annotations: READ_ONLY }, async () => {
+        if (await telegram.ensureConnected()) {
+            try {
+                const me = await telegram.getMe();
+                return ok(`Connected as ${me.firstName ?? ""} (@${me.username ?? "unknown"}, id: ${me.id})`);
+            }
+            catch {
+                return ok("Connected, but failed to get user info");
+            }
+        }
+        const reason = telegram.lastError ? ` Reason: ${telegram.lastError}` : "";
+        return ok(`Not connected.${reason} Use telegram-login to authenticate via QR code.`);
+    });
+    server.registerTool("telegram-login", {
+        description: "Login to Telegram via QR code. Returns QR image. IMPORTANT: pass the entire result to user without modifications.",
+        annotations: WRITE,
+    }, 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();
+        while (!qrDataUrl && Date.now() - startTime < 15000) {
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        if (!qrDataUrl) {
+            return fail(new Error("Failed to generate QR code"));
+        }
+        // Login continues in background
+        loginPromise.then((result) => {
+            if (result.success) {
+                console.error("[mcp-telegram] Login successful");
+            }
+            else {
+                console.error(`[mcp-telegram] Login failed: ${result.message}`);
+            }
+        });
+        // 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: [
+                {
+                    type: "image",
+                    data: base64,
+                    mimeType: "image/png",
+                },
+                {
+                    type: "text",
+                    text: instructions,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/chats.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerChatTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/chats.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+export function registerChatTools(server, telegram) {
+    server.registerTool("telegram-list-chats", {
+        description: "List Telegram chats with unread counts, type indicators, and contact status",
+        inputSchema: {
+            limit: z.number().default(20).describe("Number of chats to return"),
+            offsetDate: z.number().optional().describe("Unix timestamp offset for pagination"),
+            filterType: z
+                .enum(["private", "group", "channel", "contact_requests"])
+                .optional()
+                .describe("Filter by chat type. 'contact_requests' shows only private chats from non-contacts"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ limit, offsetDate, filterType }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const dialogs = await telegram.getDialogs(limit, offsetDate, filterType);
+            const text = dialogs
+                .map((d) => {
+                const prefix = d.type === "group" ? "G" : d.type === "channel" ? "C" : "P";
+                const botTag = d.isBot ? " [bot]" : "";
+                const contactTag = d.type === "private" && d.isContact === false ? " [not in contacts]" : "";
+                const unread = d.unreadCount > 0 ? ` [${d.unreadCount} unread]` : "";
+                return `${prefix} ${d.name} (${d.id})${botTag}${contactTag}${unread}`;
+            })
+                .join("\n");
+            return ok(sanitize(text) || "No chats");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-search-chats", {
+        description: "Search for Telegram chats, users, or channels by name or username. Returns description and member count",
+        inputSchema: {
+            query: z.string().describe("Search query (name or username)"),
+            limit: z.number().default(10).describe("Max results"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ query, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        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})${c.membersCount ? ` [${c.membersCount} members]` : ""}${c.description ? ` — ${c.description.split("\n")[0].slice(0, 100)}` : ""}`)
+                .join("\n");
+            return ok(sanitize(text) || "No results");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-chat-info", {
+        description: "Get detailed info about a Telegram chat including name, type, members, description, and forum status",
+        inputSchema: { chatId: z.string().describe("Chat ID or username") },
+        annotations: READ_ONLY,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const info = await telegram.getChatInfo(chatId);
+            const lines = [
+                `Name: ${info.name}`,
+                `ID: ${info.id}`,
+                `Type: ${info.type}`,
+                ...(info.forum ? ["Forum: yes"] : []),
+                ...(info.username ? [`Username: @${info.username}`] : []),
+                ...(info.description ? [`Description: ${info.description}`] : []),
+                ...(info.membersCount != null ? [`Members: ${info.membersCount}`] : []),
+            ];
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-chat-members", {
+        description: "Get members of a Telegram group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            limit: z.number().default(50).describe("Number of members to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const members = await telegram.getChatMembers(chatId, limit);
+            const text = members.map((m) => `${m.name}${m.username ? ` (@${m.username})` : ""} (${m.id})`).join("\n");
+            return ok(sanitize(text) || "No members found");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-join-chat", {
+        description: "Join a Telegram group or channel by username or invite link",
+        inputSchema: {
+            target: z.string().describe("Username (@group), link (t.me/group), or invite link (t.me/+xxx)"),
+        },
+        annotations: WRITE,
+    }, async ({ target }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.joinChat(target);
+            return ok(`Joined ${result.type}: ${result.title} (ID: ${result.id})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/contacts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerContactTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/contacts.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+export function registerContactTools(server, telegram) {
+    server.registerTool("telegram-get-contacts", {
+        description: "Get your Telegram contacts list with phone numbers",
+        inputSchema: { limit: z.number().default(50).describe("Number of contacts to return") },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const contacts = await telegram.getContacts(limit);
+            const text = contacts
+                .map((c) => `P ${c.name}${c.username ? ` (@${c.username})` : ""} (${c.id})${c.phone ? ` +${c.phone}` : ""}`)
+                .join("\n");
+            return ok(sanitize(text) || "No contacts");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-profile", {
+        description: "Get detailed profile info of a Telegram user including bio, birthday, premium status, business info and more",
+        inputSchema: { userId: z.string().describe("User ID or username") },
+        annotations: READ_ONLY,
+    }, async ({ userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const profile = await telegram.getProfile(userId);
+            const lines = [
+                `Name: ${profile.name}`,
+                `ID: ${profile.id}`,
+                ...(profile.username ? [`Username: @${profile.username}`] : []),
+                ...(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 ok(lines.join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-contact-requests", {
+        description: "Get incoming messages from non-contacts (contact requests). Shows who messaged you without being in your contacts, with message preview",
+        inputSchema: { limit: z.number().default(20).describe("Number of contact requests to return") },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const requests = await telegram.getContactRequests(limit);
+            if (requests.length === 0) {
+                return ok("No contact requests");
+            }
+            const text = requests
+                .map((r) => {
+                const tag = r.isBot ? "[bot]" : "[user]";
+                const username = r.username ? ` @${r.username}` : "";
+                const unread = r.unreadCount > 0 ? ` [${r.unreadCount} unread]` : "";
+                const preview = r.lastMessage ? `\n  > ${r.lastMessage.slice(0, 100)}` : "";
+                return `${tag} ${r.name}${username} (${r.id})${unread}${preview}`;
+            })
+                .join("\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-add-contact", {
+        description: "Add a user to your Telegram contacts. Use this to accept contact requests from non-contacts",
+        inputSchema: {
+            userId: z.string().describe("User ID or username to add"),
+            firstName: z.string().describe("First name for the contact"),
+            lastName: z.string().optional().describe("Last name for the contact"),
+            phone: z.string().optional().describe("Phone number for the contact"),
+        },
+        annotations: WRITE,
+    }, async ({ userId, firstName, lastName, phone }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.addContact(userId, firstName, lastName, phone);
+            return ok(`Contact added: ${firstName}${lastName ? ` ${lastName}` : ""} (${userId})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-block-user", {
+        description: "Block a Telegram user. Blocked users cannot send you messages",
+        inputSchema: { userId: z.string().describe("User ID or username to block") },
+        annotations: WRITE,
+    }, async ({ userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.blockUser(userId);
+            return ok(`User blocked: ${userId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-report-spam", {
+        description: "Report a chat as spam to Telegram",
+        inputSchema: { chatId: z.string().describe("Chat ID or username to report") },
+        annotations: WRITE,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.reportSpam(chatId);
+            return ok(`Reported as spam: ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/extras.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerExtraTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/extras.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { fail, formatReactions, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+export function registerExtraTools(server, telegram) {
+    server.registerTool("telegram-pin-message", {
+        description: "Pin a message in a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("Message ID to pin"),
+            silent: z.boolean().default(false).describe("Pin without notification"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, silent }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.pinMessage(chatId, messageId, silent);
+            return ok(`Message ${messageId} pinned in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-unpin-message", {
+        description: "Unpin a message in a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("Message ID to unpin"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.unpinMessage(chatId, messageId);
+            return ok(`Message ${messageId} unpinned in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-scheduled", {
+        description: "Send a scheduled message to a Telegram chat. The message will be delivered at the specified time by Telegram servers",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (use 'me' or 'self' for Saved Messages)"),
+            text: z.string().describe("Message text"),
+            scheduleDate: z.number().describe("Unix timestamp when to send the message (must be in the future)"),
+            replyTo: z.number().optional().describe("Message ID to reply to"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Message format: md (Markdown) or html"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, text, scheduleDate, replyTo, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        // Resolve 'me'/'self' to Saved Messages
+        let target = chatId;
+        if (target === "me" || target === "self") {
+            try {
+                const me = await telegram.getMe();
+                target = me.id;
+            }
+            catch {
+                return fail(new Error("Failed to resolve Saved Messages"));
+            }
+        }
+        try {
+            await telegram.sendScheduledMessage(target, text, scheduleDate, replyTo, parseMode);
+            const date = new Date(scheduleDate * 1000).toISOString();
+            return ok(`Message scheduled for ${date} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-create-poll", {
+        description: "Create a poll in a Telegram chat (multiple choice or quiz mode)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            question: z.string().describe("Poll question"),
+            answers: z.array(z.string()).min(2).max(10).describe("Answer options (2-10)"),
+            multipleChoice: z.boolean().default(false).describe("Allow multiple answers"),
+            quiz: z.boolean().default(false).describe("Quiz mode (one correct answer)"),
+            correctAnswer: z.number().optional().describe("Index of correct answer (0-based, required for quiz mode)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, question, answers, multipleChoice, quiz, correctAnswer }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const msgId = await telegram.createPoll(chatId, question, answers, {
+                multipleChoice,
+                quiz,
+                correctAnswer,
+            });
+            return ok(`Poll created in ${chatId}${msgId ? ` (message #${msgId})` : ""}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-list-topics", {
+        description: "List forum topics in a Telegram group with Topics enabled. Shows topic names, unread counts, and status",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username of a group with Topics enabled"),
+            limit: z.number().default(100).describe("Max topics to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const topics = await telegram.getForumTopics(chatId, limit);
+            const text = topics
+                .map((t) => {
+                const flags = [t.pinned ? "pinned" : "", t.closed ? "closed" : ""].filter(Boolean).join(", ");
+                const flagStr = flags ? ` [${flags}]` : "";
+                const unread = t.unreadCount > 0 ? ` [${t.unreadCount} unread]` : "";
+                return `# ${t.title} (id: ${t.id})${flagStr}${unread}`;
+            })
+                .join("\n");
+            return ok(sanitize(text) || "No topics found");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-read-topic-messages", {
+        description: "Read messages from a specific forum topic in a Telegram group",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            topicId: z.number().describe("Topic ID (get from telegram-list-topics)"),
+            limit: z.number().default(20).describe("Number of messages to return"),
+            offsetId: z.number().optional().describe("Message ID to start from (for pagination)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, topicId, limit, offsetId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getTopicMessages(chatId, topicId, limit, offsetId);
+            const text = messages
+                .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
+                .join("\n\n");
+            return ok(sanitize(text) || "No messages in this topic");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/index.js

@@ -0,0 +1,16 @@
+import { registerAuthTools } from "./auth.js";
+import { registerChatTools } from "./chats.js";
+import { registerContactTools } from "./contacts.js";
+import { registerExtraTools } from "./extras.js";
+import { registerMediaTools } from "./media.js";
+import { registerMessageTools } from "./messages.js";
+import { registerReactionTools } from "./reactions.js";
+export function registerTools(server, telegram) {
+    registerAuthTools(server, telegram);
+    registerMessageTools(server, telegram);
+    registerChatTools(server, telegram);
+    registerMediaTools(server, telegram);
+    registerContactTools(server, telegram);
+    registerReactionTools(server, telegram);
+    registerExtraTools(server, telegram);
+}

package/dist/tools/media.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerMediaTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/media.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+export function registerMediaTools(server, telegram) {
+    server.registerTool("telegram-send-file", {
+        description: "Send a file (photo, document, video, etc.) to a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            filePath: z.string().describe("Absolute path to file"),
+            caption: z.string().optional().describe("File caption"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, caption }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendFile(chatId, filePath, caption);
+            return ok(`File sent to ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-download-media", {
+        description: "Download media from a Telegram message to a local file",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("Message ID containing media"),
+            downloadPath: z.string().describe("Absolute path to save file"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId, downloadPath }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const path = await telegram.downloadMedia(chatId, messageId, downloadPath);
+            return ok(`Media downloaded to ${path}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-profile-photo", {
+        description: "Download profile photo of a Telegram user, group, or channel. Returns inline image or saves to file",
+        inputSchema: {
+            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"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ entityId, savePath, size }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.downloadProfilePhoto(entityId, {
+                isBig: size !== "small",
+                savePath,
+            });
+            if (!result) {
+                return ok("No profile photo found");
+            }
+            if ("filePath" in result) {
+                return ok(`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 fail(e);
+        }
+    });
+}