@overpod/mcp-telegram 1.12.0 → 1.13.0

package/dist/tools/messages.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+export function registerMessageTools(server, telegram) {
+    server.registerTool("telegram-send-message", {
+        description: "Send a message to a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (e.g. @username or numeric ID)"),
+            text: z.string().describe("Message text"),
+            replyTo: z.number().optional().describe("Message ID to reply to"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Message format: md (Markdown) or html"),
+            topicId: z.number().optional().describe("Forum topic ID to send message into (for groups with Topics enabled)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, text, replyTo, parseMode, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+            const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
+            return ok(`Message sent to ${dest}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-read-messages", {
+        description: "Read recent messages from a Telegram chat with sender names, dates, media info, and reactions",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            limit: z.number().default(10).describe("Number of messages to return"),
+            offsetId: z.number().optional().describe("Message ID to start from (for pagination)"),
+            minDate: z.number().optional().describe("Unix timestamp: only messages after this date"),
+            maxDate: z.number().optional().describe("Unix timestamp: only messages before this date"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit, offsetId, minDate, maxDate }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.getMessages(chatId, limit, offsetId, minDate, maxDate);
+            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");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-search-messages", {
+        description: "Search messages in a specific Telegram chat by text",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            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"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, query, limit, minDate, maxDate }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.searchMessages(chatId, query, limit, minDate, maxDate);
+            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 found");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-search-global", {
+        description: "Search messages globally across all public Telegram chats and channels",
+        inputSchema: {
+            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"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ query, limit, minDate, maxDate }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const messages = await telegram.searchGlobal(query, limit, minDate, maxDate);
+            const text = messages
+                .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}` : ""}]` : ""}${formatReactions(m.reactions)}`)
+                .join("\n\n");
+            return ok(sanitize(text) || "No messages found");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-message", {
+        description: "Edit a previously sent message in Telegram",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("ID of the message to edit"),
+            text: z.string().describe("New message text"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, text }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editMessage(chatId, messageId, text);
+            return ok(`Message ${messageId} edited in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-message", {
+        description: "Delete messages in a Telegram chat",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageIds: z.array(z.number()).describe("Array of message IDs to delete"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, messageIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteMessages(chatId, messageIds);
+            return ok(`Deleted ${messageIds.length} message(s) in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-forward-message", {
+        description: "Forward messages between Telegram chats",
+        inputSchema: {
+            fromChatId: z.string().describe("Source chat ID or username"),
+            toChatId: z.string().describe("Destination chat ID or username"),
+            messageIds: z.array(z.number()).describe("Array of message IDs to forward"),
+        },
+        annotations: WRITE,
+    }, async ({ fromChatId, toChatId, messageIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.forwardMessage(fromChatId, toChatId, messageIds);
+            return ok(`Forwarded ${messageIds.length} message(s) from ${fromChatId} to ${toChatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-unread", {
+        description: "Get chats with unread messages. Forums show per-topic unread breakdown",
+        inputSchema: {
+            limit: z.number().default(20).describe("Number of unread chats to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const dialogs = await telegram.getUnreadDialogs(limit);
+            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 forumTag = d.forum ? " [forum]" : "";
+                let line = `${prefix} ${d.name} (${d.id})${botTag}${contactTag}${forumTag} [${d.unreadCount} unread]`;
+                if (d.topics && d.topics.length > 0) {
+                    const topicLines = d.topics.map((t) => `  # ${t.title} [${t.unreadCount} unread]`);
+                    line += `\n${topicLines.join("\n")}`;
+                }
+                return line;
+            })
+                .join("\n");
+            return ok(sanitize(text) || "No unread chats");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-mark-as-read", {
+        description: "Mark a Telegram chat as read",
+        inputSchema: { chatId: z.string().describe("Chat ID or username") },
+        annotations: WRITE,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.markAsRead(chatId);
+            return ok(`Marked ${chatId} as read`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/reactions.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 registerReactionTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/reactions.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+export function registerReactionTools(server, telegram) {
+    server.registerTool("telegram-send-reaction", {
+        description: "Send emoji reaction(s) to a message. Supports multiple reactions and adding to existing ones. Omit emoji to remove all reactions",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("Message ID to react to"),
+            emoji: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe("Reaction emoji(s): single '👍' or array ['👍','🔥']. Omit to remove all reactions"),
+            addToExisting: z
+                .boolean()
+                .default(false)
+                .describe("If true, add reaction(s) to existing ones instead of replacing"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, emoji, addToExisting }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const updated = await telegram.sendReaction(chatId, messageId, emoji, addToExisting);
+            const emojiStr = Array.isArray(emoji) ? emoji.join("") : emoji;
+            const action = emoji ? `Reacted ${emojiStr} to` : "Removed reactions from";
+            const reactionsInfo = updated
+                ? ` | Reactions: ${updated.map((r) => `${r.emoji}×${r.count}${r.me ? "(me)" : ""}`).join(" ")}`
+                : "";
+            return ok(`${action} message ${messageId} in ${chatId}${reactionsInfo}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-reactions", {
+        description: "Get detailed reaction info for a message: which reactions, counts, and who reacted (when visible)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().describe("Message ID to get reactions for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMessageReactions(chatId, messageId);
+            if (result.reactions.length === 0) {
+                return ok(`No reactions on message ${messageId}`);
+            }
+            const lines = result.reactions.map((r) => {
+                const usersStr = r.users.length > 0 ? `: ${r.users.map((u) => u.name).join(", ")}` : "";
+                return `${r.emoji} × ${r.count}${usersStr}`;
+            });
+            lines.push(`\nTotal: ${result.total} reactions`);
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,40 @@
+import type { TelegramService } from "../telegram-client.js";
+/** MCP tool annotation presets */
+export declare const READ_ONLY: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: true;
+};
+export declare const WRITE: {
+    readonly readOnlyHint: false;
+    readonly openWorldHint: true;
+};
+export declare const DESTRUCTIVE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly openWorldHint: true;
+};
+/** Helper: success response */
+export declare function ok(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Helper: error response with isError flag */
+export declare function fail(e: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/** Remove unpaired UTF-16 surrogates that break JSON serialization */
+export declare function sanitize(text: string): string;
+/** Format reactions array into compact text like: [👍×5 ❤️×3(me) 🔥×1] */
+export declare function formatReactions(reactions?: {
+    emoji: string;
+    count: number;
+    me: boolean;
+}[]): string;
+/** Try to connect, return error text if failed */
+export declare function requireConnection(telegram: TelegramService): Promise<string | null>;

package/dist/tools/shared.js

@@ -0,0 +1,30 @@
+/** MCP tool annotation presets */
+export const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export const WRITE = { readOnlyHint: false, openWorldHint: true };
+export const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+/** Helper: success response */
+export function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** Helper: error response with isError flag */
+export function fail(e) {
+    return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+}
+/** Remove unpaired UTF-16 surrogates that break JSON serialization */
+export function sanitize(text) {
+    return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+}
+/** Format reactions array into compact text like: [👍×5 ❤️×3(me) 🔥×1] */
+export function formatReactions(reactions) {
+    if (!reactions?.length)
+        return "";
+    const parts = reactions.map((r) => `${r.emoji}×${r.count}${r.me ? "(me)" : ""}`);
+    return ` [${parts.join(" ")}]`;
+}
+/** Try to connect, return error text if failed */
+export async function requireConnection(telegram) {
+    if (await telegram.ensureConnected())
+        return null;
+    const reason = telegram.lastError ? ` ${telegram.lastError}` : "";
+    return `Not connected to Telegram.${reason} Run telegram-login first.`;
+}

package/package.json

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