@overpod/mcp-telegram 1.6.0 → 1.8.0

package/README.md

@@ -21,6 +21,7 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, media, contacts, and more
+- **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
 - **QR code login** -- authenticate by scanning a QR code in the Telegram app
 - **Session persistence** -- login once, stay connected across restarts
 - **Human-readable output** -- sender names are resolved, not just numeric IDs
@@ -46,7 +47,9 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login
 ```
 
-A QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to `~/.telegram-session` and reused automatically.
+A QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to `~/.mcp-telegram/session` and reused automatically.
+
+> **Custom session path:** set `TELEGRAM_SESSION_PATH=/path/to/session` to store the session file elsewhere.
 
 ### 3. Add to Claude
 
@@ -59,6 +62,34 @@ claude mcp add telegram -s user \
 
 That's it! Ask Claude to run `telegram-status` to verify.
 
+### Multiple Accounts
+
+Use `TELEGRAM_SESSION_PATH` to run separate Telegram accounts side by side:
+
+```bash
+# Login each account with a unique session path
+TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
+TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login
+```
+
+Then add each as a separate MCP server:
+
+```bash
+claude mcp add telegram-work -s user \
+  -e TELEGRAM_API_ID=ID1 \
+  -e TELEGRAM_API_HASH=HASH1 \
+  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
+  -- npx @overpod/mcp-telegram
+
+claude mcp add telegram-personal -s user \
+  -e TELEGRAM_API_ID=ID2 \
+  -e TELEGRAM_API_HASH=HASH2 \
+  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
+  -- npx @overpod/mcp-telegram
+```
+
+Each account gets its own session file — no conflicts.
+
 ## Installation Options
 
 ### npx (recommended, zero install)
@@ -173,23 +204,39 @@ const telegramMcp = new MCPClient({
 
 | Tool | Description |
 |------|-------------|
-| `telegram-list-chats` | List recent dialogs with unread counts |
+| `telegram-list-chats` | List recent dialogs with unread counts, bot/contact markers |
 | `telegram-read-messages` | Read recent messages from a chat |
 | `telegram-search-chats` | Search for chats, users, or channels by name |
 | `telegram-search-messages` | Search messages in a chat by text |
-| `telegram-get-unread` | Get chats with unread messages |
+| `telegram-get-unread` | Get chats with unread messages; forums show per-topic unread breakdown |
+| `telegram-get-contact-requests` | Get incoming messages from non-contacts with preview |
+
+### Forum Topics
+
+| Tool | Description |
+|------|-------------|
+| `telegram-list-topics` | List forum topics in a group with unread counts and status |
+| `telegram-read-topic-messages` | Read messages from a specific forum topic |
 
 ### Chat Management
 
 | Tool | Description |
 |------|-------------|
 | `telegram-mark-as-read` | Mark a chat as read |
-| `telegram-get-chat-info` | Get detailed info about a chat (name, type, members count, description) |
+| `telegram-get-chat-info` | Get detailed info about a chat (name, type, members, bot/contact status) |
 | `telegram-get-chat-members` | List members of a group or channel |
 | `telegram-join-chat` | Join a group or channel by username or invite link |
 | `telegram-pin-message` | Pin a message in a chat |
 | `telegram-unpin-message` | Unpin a message in a chat |
 
+### Contacts & Moderation
+
+| Tool | Description |
+|------|-------------|
+| `telegram-add-contact` | Add a user to your contacts (accept contact request) |
+| `telegram-block-user` | Block a user from sending you messages |
+| `telegram-report-spam` | Report a chat as spam to Telegram |
+
 ### User Info
 
 | Tool | Description |
@@ -217,6 +264,23 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 | `text` | string | yes | Message text |
 | `replyTo` | number | no | Message ID to reply to |
 | `parseMode` | `"md"` / `"html"` | no | Message formatting mode |
+| `topicId` | number | no | Forum topic ID to send into (for groups with Topics) |
+
+### telegram-list-topics
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username (group with Topics enabled) |
+| `limit` | number | no | Max topics to return (default: 100) |
+
+### telegram-read-topic-messages
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username |
+| `topicId` | number | yes | Topic ID (from `telegram-list-topics`) |
+| `limit` | number | no | Number of messages (default: 20) |
+| `offsetId` | number | no | Message ID for pagination |
 
 ### telegram-list-chats
 
@@ -224,7 +288,7 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 |-----------|------|----------|-------------|
 | `limit` | number | no | Number of chats to return (default: 20) |
 | `offsetDate` | number | no | Unix timestamp for pagination |
-| `filterType` | `"private"` / `"group"` / `"channel"` | no | Filter by chat type |
+| `filterType` | `"private"` / `"group"` / `"channel"` / `"contact_requests"` | no | Filter by chat type |
 
 ### telegram-read-messages
 
@@ -356,6 +420,33 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 |-----------|------|----------|-------------|
 | `limit` | number | no | Number of unread chats (default: 20) |
 
+### telegram-get-contact-requests
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | no | Number of contact requests (default: 20) |
+
+### telegram-add-contact
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | string | yes | User ID or @username to add |
+| `firstName` | string | yes | First name for the contact |
+| `lastName` | string | no | Last name for the contact |
+| `phone` | string | no | Phone number for the contact |
+
+### telegram-block-user
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | string | yes | User ID or @username to block |
+
+### telegram-report-spam
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username to report |
+
 ## Development
 
 ```bash
@@ -390,7 +481,8 @@ src/
 ## Security
 
 - API credentials are stored in `.env` (gitignored)
-- Session is stored in `.telegram-session` (gitignored)
+- Session is stored in `~/.mcp-telegram/session` with `0600` permissions (owner-only access)
+- Session directory is created with `0700` permissions
 - Phone number is **not required** -- QR-only authentication
 - This is a **userbot** (personal account), not a bot -- respect the [Telegram Terms of Service](https://core.telegram.org/api/terms)
 

package/dist/index.js

@@ -104,13 +104,15 @@ server.tool("telegram-send-message", "Send a message to a Telegram chat", {
     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"),
-}, async ({ chatId, text, replyTo, parseMode }) => {
+    topicId: z.number().optional().describe("Forum topic ID to send message into (for groups with Topics enabled)"),
+}, async ({ chatId, text, replyTo, parseMode, topicId }) => {
     const err = await requireConnection();
     if (err)
         return { content: [{ type: "text", text: err }] };
     try {
-        await telegram.sendMessage(chatId, text, replyTo, parseMode);
-        return { content: [{ type: "text", text: `Message sent to ${chatId}` }] };
+        await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+        const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
+        return { content: [{ type: "text", text: `Message sent to ${dest}` }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: `Send error: ${e.message}` }] };
@@ -217,7 +219,13 @@ server.tool("telegram-get-unread", "Get unread Telegram chats", {
             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]" : "";
-            return `${prefix} ${d.name} (${d.id})${botTag}${contactTag} [${d.unreadCount} unread]`;
+            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 { content: [{ type: "text", text: text || "No unread chats" }] };
@@ -303,6 +311,7 @@ server.tool("telegram-get-chat-info", "Get detailed info about a Telegram chat",
             `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}`] : []),
@@ -594,6 +603,49 @@ server.tool("telegram-report-spam", "Report a chat as spam to Telegram", {
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
+server.tool("telegram-list-topics", "List forum topics in a Telegram group with Topics enabled. Shows topic names, unread counts, and status", {
+    chatId: z.string().describe("Chat ID or username of a group with Topics enabled"),
+    limit: z.number().default(100).describe("Max topics to return"),
+}, async ({ chatId, limit }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: 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 { content: [{ type: "text", text: text || "No topics found" }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-read-topic-messages", "Read messages from a specific forum topic in a Telegram group", {
+    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)"),
+}, async ({ chatId, topicId, limit, offsetId }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    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}` : ""}]` : ""}`)
+            .join("\n\n");
+        return { content: [{ type: "text", text: text || "No messages in this topic" }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
 // --- Start ---
 async function main() {
     // Try to auto-connect with saved session

package/dist/telegram-client.d.ts

@@ -4,9 +4,13 @@ export declare class TelegramService {
     private apiHash;
     private sessionString;
     private connected;
+    private sessionPath;
     lastError: string;
-    constructor(apiId: number, apiHash: string);
+    constructor(apiId: number, apiHash: string, options?: {
+        sessionPath?: string;
+    });
     loadSession(): Promise<boolean>;
+    private isValidSessionString;
     /** Set session string in memory (for programmatic / hosted use) */
     setSessionString(session: string): void;
     /** Get the current session string (for external persistence) */
@@ -32,7 +36,7 @@ export declare class TelegramService {
         username?: string;
         firstName?: string;
     }>;
-    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number): Promise<void>;
     sendFile(chatId: string, filePath: string, caption?: string): Promise<void>;
     downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
     downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
@@ -58,6 +62,12 @@ export declare class TelegramService {
         unreadCount: number;
         isBot?: boolean;
         isContact?: boolean;
+        forum?: boolean;
+        topics?: Array<{
+            id: number;
+            title: string;
+            unreadCount: number;
+        }>;
     }>>;
     getContactRequests(limit?: number): Promise<Array<{
         id: string;
@@ -84,6 +94,7 @@ export declare class TelegramService {
         membersCount?: number;
         isBot?: boolean;
         isContact?: boolean;
+        forum?: boolean;
     }>;
     /** Extract media info from a message */
     private extractMediaInfo;
@@ -144,6 +155,28 @@ export declare class TelegramService {
         quiz?: boolean;
         correctAnswer?: number;
     }): Promise<number>;
+    getForumTopics(chatId: string, limit?: number): Promise<Array<{
+        id: number;
+        title: string;
+        unreadCount: number;
+        unreadMentions: number;
+        iconColor: number;
+        closed: boolean;
+        pinned: boolean;
+    }>>;
+    getTopicMessages(chatId: string, topicId: number, limit?: number, offsetId?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    /** Check if a chat entity is a forum (has topics enabled) */
+    isForum(chatId: string): Promise<boolean>;
     joinChat(target: string): Promise<{
         id: string;
         title: string;

package/dist/telegram-client.js

@@ -1,5 +1,6 @@
-import { existsSync } from "node:fs";
-import { readFile, unlink, writeFile } from "node:fs/promises";
+import { existsSync, mkdirSync } from "node:fs";
+import { chmod, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import bigInt from "big-integer";
@@ -8,25 +9,66 @@ 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");
+const LEGACY_SESSION_FILE = join(__dirname, "..", ".telegram-session");
+const DEFAULT_SESSION_DIR = join(homedir(), ".mcp-telegram");
+const DEFAULT_SESSION_FILE = join(DEFAULT_SESSION_DIR, "session");
+const SESSION_STRING_RE = /^[A-Za-z0-9+/=]+$/;
+const MIN_SESSION_LENGTH = 100;
+function resolveSessionPath(sessionPath) {
+    return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
+}
+function ensureSessionDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
 export class TelegramService {
     client = null;
     apiId;
     apiHash;
     sessionString = "";
     connected = false;
+    sessionPath;
     lastError = "";
-    constructor(apiId, apiHash) {
+    constructor(apiId, apiHash, options) {
         this.apiId = apiId;
         this.apiHash = apiHash;
+        this.sessionPath = resolveSessionPath(options?.sessionPath);
     }
     async loadSession() {
-        if (existsSync(SESSION_FILE)) {
-            this.sessionString = (await readFile(SESSION_FILE, "utf-8")).trim();
-            return true;
+        // Try current session path
+        if (existsSync(this.sessionPath)) {
+            const raw = (await readFile(this.sessionPath, "utf-8")).trim();
+            if (this.isValidSessionString(raw)) {
+                this.sessionString = raw;
+                // Fix permissions on existing files
+                try {
+                    await chmod(this.sessionPath, 0o600);
+                }
+                catch { }
+                return true;
+            }
+        }
+        // Migrate from legacy path (inside node_modules / package root)
+        if (this.sessionPath === DEFAULT_SESSION_FILE && existsSync(LEGACY_SESSION_FILE)) {
+            const raw = (await readFile(LEGACY_SESSION_FILE, "utf-8")).trim();
+            if (this.isValidSessionString(raw)) {
+                this.sessionString = raw;
+                ensureSessionDir(this.sessionPath);
+                await writeFile(this.sessionPath, raw, { encoding: "utf-8", mode: 0o600 });
+                try {
+                    await unlink(LEGACY_SESSION_FILE);
+                }
+                catch { }
+                return true;
+            }
         }
         return false;
     }
+    isValidSessionString(value) {
+        return value.length >= MIN_SESSION_LENGTH && SESSION_STRING_RE.test(value);
+    }
     /** Set session string in memory (for programmatic / hosted use) */
     setSessionString(session) {
         this.sessionString = session;
@@ -38,7 +80,8 @@ export class TelegramService {
     async saveSession(session) {
         this.sessionString = session;
         try {
-            await writeFile(SESSION_FILE, session, "utf-8");
+            ensureSessionDir(this.sessionPath);
+            await writeFile(this.sessionPath, session, { encoding: "utf-8", mode: 0o600 });
         }
         catch {
             // File write may fail in containerized environments — session string is still in memory
@@ -95,8 +138,8 @@ export class TelegramService {
         this.connected = false;
         this.sessionString = "";
         this.client = null;
-        if (existsSync(SESSION_FILE)) {
-            await unlink(SESSION_FILE);
+        if (existsSync(this.sessionPath)) {
+            await unlink(this.sessionPath);
         }
     }
     /** Ensure connection is active, auto-reconnect if session exists */
@@ -230,14 +273,29 @@ export class TelegramService {
             firstName: user.firstName ?? undefined,
         };
     }
-    async sendMessage(chatId, text, replyTo, parseMode) {
+    async sendMessage(chatId, text, replyTo, parseMode, topicId) {
         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" } : {}),
-        });
+        if (topicId) {
+            // Forum topics require raw API call with InputReplyToMessage
+            const peer = await this.client.getInputEntity(chatId);
+            await this.client.invoke(new Api.messages.SendMessage({
+                peer,
+                message: text,
+                randomId: bigInt(Math.floor(Math.random() * 1e15)),
+                replyTo: new Api.InputReplyToMessage({
+                    replyToMsgId: replyTo ?? topicId,
+                    topMsgId: topicId,
+                }),
+            }));
+        }
+        else {
+            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)
@@ -331,12 +389,11 @@ export class TelegramService {
         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) => {
+        const unread = dialogs.filter((d) => d.unreadCount > 0).slice(0, limit);
+        const results = await Promise.all(unread.map(async (d) => {
             const isUser = d.entity instanceof Api.User;
-            return {
+            const isForum = d.entity instanceof Api.Channel && Boolean(d.entity.forum);
+            const base = {
                 id: d.id?.toString() ?? "",
                 name: d.title ?? d.name ?? "Unknown",
                 type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
@@ -345,7 +402,29 @@ export class TelegramService {
                     ? { isBot: Boolean(d.entity.bot), isContact: Boolean(d.entity.contact) }
                     : {}),
             };
-        });
+            if (isForum) {
+                try {
+                    const forumTopics = await this.getForumTopics(d.id?.toString() ?? "");
+                    const unreadTopics = forumTopics
+                        .filter((t) => t.unreadCount > 0)
+                        .map((t) => ({ id: t.id, title: t.title, unreadCount: t.unreadCount }));
+                    const realUnread = unreadTopics.reduce((sum, t) => sum + t.unreadCount, 0);
+                    if (realUnread === 0)
+                        return null;
+                    return {
+                        ...base,
+                        unreadCount: realUnread,
+                        forum: true,
+                        topics: unreadTopics.length > 0 ? unreadTopics : undefined,
+                    };
+                }
+                catch {
+                    return { ...base, forum: true };
+                }
+            }
+            return base;
+        }));
+        return results.filter((r) => r !== null);
     }
     async getContactRequests(limit = 20) {
         if (!this.client || !this.connected)
@@ -450,6 +529,7 @@ export class TelegramService {
                 username: entity.username ?? undefined,
                 description,
                 membersCount,
+                forum: Boolean(entity.forum) || undefined,
             };
         }
         if (entity instanceof Api.Chat) {
@@ -726,6 +806,75 @@ export class TelegramService {
         }
         return 0;
     }
+    async getForumTopics(chatId, limit = 100) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Forum topics are only available in supergroups");
+        const result = await this.client.invoke(new Api.channels.GetForumTopics({
+            channel: entity,
+            limit,
+            offsetTopic: 0,
+            offsetDate: 0,
+            offsetId: 0,
+        }));
+        const topics = [];
+        for (const topic of result.topics) {
+            if (topic instanceof Api.ForumTopic) {
+                topics.push({
+                    id: topic.id,
+                    title: topic.title,
+                    unreadCount: topic.unreadCount,
+                    unreadMentions: topic.unreadMentionsCount,
+                    iconColor: topic.iconColor,
+                    closed: Boolean(topic.closed),
+                    pinned: Boolean(topic.pinned),
+                });
+            }
+        }
+        return topics;
+    }
+    async getTopicMessages(chatId, topicId, limit = 20, offsetId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const peer = await this.client.getInputEntity(chatId);
+        const result = await this.client.invoke(new Api.messages.GetReplies({
+            peer,
+            msgId: topicId,
+            limit,
+            ...(offsetId ? { offsetId } : {}),
+            offsetDate: 0,
+            addOffset: 0,
+            maxId: 0,
+            minId: 0,
+            hash: bigInt(0),
+        }));
+        const messages = "messages" in result ? result.messages : [];
+        const results = await Promise.all(messages
+            .filter((m) => m instanceof Api.Message)
+            .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;
+    }
+    /** Check if a chat entity is a forum (has topics enabled) */
+    async isForum(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        try {
+            const entity = await this.client.getEntity(chatId);
+            if (entity instanceof Api.Channel) {
+                return Boolean(entity.forum);
+            }
+        }
+        catch { }
+        return false;
+    }
     async joinChat(target) {
         if (!this.client)
             throw new Error("Not connected");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -56,8 +56,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
-    "@types/node": "^25.4.0",
+    "@biomejs/biome": "^2.4.7",
+    "@types/node": "^25.5.0",
     "@types/qrcode": "^1.5.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"