@overpod/mcp-telegram 1.16.0 → 1.18.0

package/README.md

@@ -204,302 +204,13 @@ const telegramMcp = new MCPClient({
 });
 ```
 
-## Available Tools
+## Tools
 
-### Connection
-
-| Tool | Description |
-|------|-------------|
-| `telegram-status` | Check connection status and current account info |
-| `telegram-login` | Authenticate via QR code |
+All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.
 
-### Messaging
+**Categories:** authentication, messaging (send, edit, delete, forward, schedule, polls), reading (chats, messages, search, unread), forum topics, group management (create, edit, invite, kick, ban, admin, leave), contacts & moderation, user profiles, reactions, media.
 
-| Tool | Description |
-|------|-------------|
-| `telegram-send-message` | Send a text message to a chat |
-| `telegram-send-file` | Send a file (photo, document, video, etc.) to a chat |
-| `telegram-send-reaction` | Send or remove an emoji reaction on a message |
-| `telegram-send-scheduled` | Schedule a message for future delivery |
-| `telegram-create-poll` | Create a poll (multiple choice or quiz mode) |
-| `telegram-edit-message` | Edit a previously sent message |
-| `telegram-delete-message` | Delete messages in a chat |
-| `telegram-forward-message` | Forward messages between chats |
-
-### Reading
-
-| Tool | Description |
-|------|-------------|
-| `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-search-global` | Search messages across all public chats and channels |
-| `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, 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 |
-|------|-------------|
-| `telegram-get-contacts` | Get your contacts list with phone numbers |
-| `telegram-get-profile` | Get detailed profile info for a user (bio, photo, last seen) |
-| `telegram-get-profile-photo` | Get a user's or chat's profile photo (inline or file) |
-| `telegram-get-reactions` | Get reactions on a specific message with user details |
-
-### Media
-
-| Tool | Description |
-|------|-------------|
-| `telegram-download-media` | Download media from a message to a local file |
-
-## Tool Parameters
-
-### Common patterns
-
-Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-1001234567890"`) or a username (e.g., `"@username"`).
-
-### telegram-send-message
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `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
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `limit` | number | no | Number of chats to return (default: 20) |
-| `offsetDate` | number | no | Unix timestamp for pagination |
-| `filterType` | `"private"` / `"group"` / `"channel"` / `"contact_requests"` | no | Filter by chat type |
-
-### telegram-read-messages
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `limit` | number | no | Number of messages (default: 10) |
-| `offsetId` | number | no | Message ID for pagination |
-
-### telegram-send-file
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `filePath` | string | yes | Absolute path to the file |
-| `caption` | string | no | File caption |
-
-### telegram-download-media
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageId` | number | yes | Message ID containing media |
-| `downloadPath` | string | yes | Absolute path to save the file |
-
-### telegram-forward-message
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `fromChatId` | string | yes | Source chat ID or @username |
-| `toChatId` | string | yes | Destination chat ID or @username |
-| `messageIds` | number[] | yes | Array of message IDs to forward |
-
-### telegram-edit-message
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageId` | number | yes | ID of the message to edit |
-| `text` | string | yes | New message text |
-
-### telegram-delete-message
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageIds` | number[] | yes | Array of message IDs to delete |
-
-### telegram-pin-message
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageId` | number | yes | Message ID to pin |
-| `silent` | boolean | no | Pin without notification (default: false) |
-
-### telegram-join-chat
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `target` | string | yes | Username (@group), link (t.me/group), or invite link (t.me/+xxx) |
-
-### telegram-send-reaction
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageId` | number | yes | Message ID to react to |
-| `emoji` | string \| string[] | no | Single emoji `"👍"` or array `["👍","🔥"]`. Omit to remove all reactions |
-| `addToExisting` | boolean | no | Add to existing reactions instead of replacing (default: false) |
-
-### telegram-send-scheduled
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username (use `"me"` or `"self"` for Saved Messages) |
-| `text` | string | yes | Message text |
-| `scheduleDate` | number | yes | Unix timestamp when to send (must be in the future) |
-| `replyTo` | number | no | Message ID to reply to |
-| `parseMode` | `"md"` / `"html"` | no | Message formatting mode |
-
-### telegram-create-poll
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `question` | string | yes | Poll question |
-| `answers` | string[] | yes | Answer options (2-10 items) |
-| `multipleChoice` | boolean | no | Allow multiple answers (default: false) |
-| `quiz` | boolean | no | Quiz mode with one correct answer (default: false) |
-| `correctAnswer` | number | no | Index of correct answer, 0-based (required for quiz mode) |
-
-### telegram-search-messages
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `query` | string | yes | Search text |
-| `limit` | number | no | Max results (default: 20) |
-
-### telegram-search-global
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | yes | Search text |
-| `limit` | number | no | Max results (default: 20) |
-| `minDate` | number | no | Unix timestamp: only messages after this date |
-| `maxDate` | number | no | Unix timestamp: only messages before this date |
-
-### telegram-search-chats
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | yes | Search query (name or username) |
-| `limit` | number | no | Max results (default: 10) |
-
-### telegram-get-chat-members
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `limit` | number | no | Number of members (default: 50) |
-
-### telegram-get-contacts
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `limit` | number | no | Number of contacts (default: 50) |
-
-### telegram-get-profile
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `userId` | string | yes | User ID or @username |
-
-### telegram-get-profile-photo
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `entityId` | string | yes | User/Chat/Channel ID or username |
-| `savePath` | string | no | Absolute path to save file. If omitted, returns inline base64 image |
-| `size` | `"small"` / `"big"` | no | Photo size: small (160x160) or big (640x640). Default: big |
-
-### telegram-get-reactions
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `chatId` | string | yes | Chat ID or @username |
-| `messageId` | number | yes | Message ID to get reactions for |
-
-### telegram-get-unread
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `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 |
+> **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the current list with parameters.
 
 ## Development
 
@@ -517,9 +228,18 @@ npm run format     # Format code with Biome
 
 ```
 src/
-  index.ts            -- MCP server entry point, tool definitions
+  index.ts            -- MCP server entry point
   telegram-client.ts  -- TelegramService class (GramJS wrapper)
   qr-login-cli.ts     -- CLI utility for QR code login
+  tools/              -- Modular tool definitions
+    auth.ts           -- Connection & login
+    messages.ts       -- Send, read, search, edit, delete, forward
+    chats.ts          -- Chat listing, group management, admin
+    contacts.ts       -- Contacts, profiles, moderation
+    media.ts          -- Files, photos
+    reactions.ts      -- Reactions
+    extras.ts         -- Pin, schedule, polls, topics
+    shared.ts         -- Shared utilities
 ```
 
 ## Tech Stack

package/dist/telegram-client.d.ts

@@ -85,6 +85,16 @@ export declare class TelegramService {
     forwardMessage(fromChatId: string, toChatId: string, messageIds: number[]): Promise<void>;
     editMessage(chatId: string, messageId: number, newText: string): Promise<void>;
     deleteMessages(chatId: string, messageIds: number[]): Promise<void>;
+    /**
+     * Resolve a chat by ID, username, or display name.
+     * Falls back to searching user's dialogs if getEntity() fails.
+     */
+    resolveChat(chatId: string): Promise<any>;
+    /**
+     * Resolve chatId to a peer string that GramJS methods accept.
+     * Handles display names by searching dialogs.
+     */
+    private resolvePeer;
     getChatInfo(chatId: string): Promise<{
         id: string;
         name: string;
@@ -172,7 +182,15 @@ export declare class TelegramService {
         id: string;
         name: string;
         username?: string;
+        role: string;
     }>>;
+    getMyRole(chatId: string): Promise<{
+        role: string;
+        chatId: string;
+        chatName: string;
+    }>;
+    private getParticipantUserId;
+    private getParticipantRole;
     getProfile(userId: string): Promise<{
         id: string;
         name: string;

package/dist/telegram-client.js

@@ -299,9 +299,10 @@ export class TelegramService {
     async sendMessage(chatId, text, replyTo, parseMode, topicId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
+        const resolved = await this.resolvePeer(chatId);
         if (topicId) {
             // Forum topics require raw API call with InputReplyToMessage
-            const peer = await this.client.getInputEntity(chatId);
+            const peer = await this.client.getInputEntity(resolved);
             await this.client.invoke(new Api.messages.SendMessage({
                 peer,
                 message: text,
@@ -313,7 +314,7 @@ export class TelegramService {
             }));
         }
         else {
-            await this.client.sendMessage(chatId, {
+            await this.client.sendMessage(resolved, {
                 message: text,
                 ...(replyTo ? { replyTo } : {}),
                 ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
@@ -323,12 +324,14 @@ export class TelegramService {
     async sendFile(chatId, filePath, caption) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.sendFile(chatId, { file: filePath, caption });
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.sendFile(resolved, { 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 resolved = await this.resolvePeer(chatId);
+        const messages = await this.client.getMessages(resolved, { ids: [messageId] });
         const message = messages[0];
         if (!message)
             throw new Error(`Message ${messageId} not found`);
@@ -343,7 +346,8 @@ export class TelegramService {
     async downloadMediaAsBuffer(chatId, messageId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const messages = await this.client.getMessages(chatId, { ids: [messageId] });
+        const resolved = await this.resolvePeer(chatId);
+        const messages = await this.client.getMessages(resolved, { ids: [messageId] });
         const message = messages[0];
         if (!message)
             throw new Error(`Message ${messageId} not found`);
@@ -378,12 +382,14 @@ export class TelegramService {
     async pinMessage(chatId, messageId, silent = false) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.pinMessage(chatId, messageId, { notify: !silent });
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.pinMessage(resolved, messageId, { notify: !silent });
     }
     async unpinMessage(chatId, messageId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.unpinMessage(chatId, messageId);
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.unpinMessage(resolved, messageId);
     }
     async getDialogs(limit = 20, offsetDate, filterType) {
         if (!this.client || !this.connected)
@@ -505,22 +511,70 @@ export class TelegramService {
     async forwardMessage(fromChatId, toChatId, messageIds) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.forwardMessages(toChatId, { messages: messageIds, fromPeer: fromChatId });
+        const resolvedFrom = await this.resolvePeer(fromChatId);
+        const resolvedTo = await this.resolvePeer(toChatId);
+        await this.client.forwardMessages(resolvedTo, { messages: messageIds, fromPeer: resolvedFrom });
     }
     async editMessage(chatId, messageId, newText) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.editMessage(chatId, { message: messageId, text: newText });
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.editMessage(resolved, { 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 });
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.deleteMessages(resolved, messageIds, { revoke: true });
+    }
+    /**
+     * Resolve a chat by ID, username, or display name.
+     * Falls back to searching user's dialogs if getEntity() fails.
+     */
+    // biome-ignore lint: GramJS has no proper entity union type
+    async resolveChat(chatId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        // First try direct resolve (numeric ID, username, phone)
+        try {
+            return await this.client.getEntity(chatId);
+        }
+        catch {
+            // Fall through to dialog search
+        }
+        // Search dialogs by display name
+        const dialogs = await this.client.getDialogs({ limit: 100 });
+        const query = chatId.toLowerCase();
+        // Exact match first
+        const exact = dialogs.find((d) => d.title?.toLowerCase() === query);
+        if (exact?.entity)
+            return exact.entity;
+        // Partial match
+        const partial = dialogs.filter((d) => d.title?.toLowerCase().includes(query));
+        if (partial.length === 1 && partial[0].entity)
+            return partial[0].entity;
+        if (partial.length > 1) {
+            const matches = partial.map((d) => `  ${d.title} (${d.entity?.id?.toString() ?? "?"})`).join("\n");
+            throw new Error(`Multiple chats match "${chatId}". Use the numeric ID instead:\n${matches}`);
+        }
+        throw new Error(`Cannot find chat "${chatId}". Use a numeric ID, @username, or run telegram-search-chats to find it.`);
+    }
+    /**
+     * Resolve chatId to a peer string that GramJS methods accept.
+     * Handles display names by searching dialogs.
+     */
+    // biome-ignore lint: GramJS has no proper entity union type
+    async resolvePeer(chatId) {
+        // Numeric IDs and @usernames work directly
+        if (/^-?\d+$/.test(chatId) || chatId.startsWith("@"))
+            return chatId;
+        // Everything else — resolve via dialogs
+        return this.resolveChat(chatId);
     }
     async getChatInfo(chatId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         if (entity instanceof Api.User) {
             const parts = [entity.firstName, entity.lastName].filter(Boolean);
             return {
@@ -628,12 +682,13 @@ export class TelegramService {
     async getMessages(chatId, limit = 10, offsetId, minDate, maxDate) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
+        const resolved = await this.resolvePeer(chatId);
         const opts = {
             limit,
             ...(offsetId ? { offsetId } : {}),
             ...(maxDate ? { offsetDate: maxDate } : {}),
         };
-        const messages = await this.client.getMessages(chatId, opts);
+        const messages = await this.client.getMessages(resolved, opts);
         let filtered = messages;
         if (minDate) {
             filtered = filtered.filter((m) => (m.date ?? 0) >= minDate);
@@ -781,7 +836,8 @@ export class TelegramService {
     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, {
+        const resolved = await this.resolvePeer(chatId);
+        const messages = await this.client.getMessages(resolved, {
             search: query,
             limit,
             ...(maxDate ? { offsetDate: maxDate } : {}),
@@ -823,19 +879,99 @@ export class TelegramService {
     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(),
+        const entity = await this.resolveChat(chatId);
+        if (entity instanceof Api.Channel) {
+            const result = await this.client.invoke(new Api.channels.GetParticipants({
+                channel: entity,
+                filter: new Api.ChannelParticipantsRecent(),
+                offset: 0,
+                limit,
+                hash: bigInt.zero,
+            }));
+            if (!(result instanceof Api.channels.ChannelParticipants))
+                return [];
+            const userMap = new Map();
+            for (const u of result.users) {
+                if (u instanceof Api.User)
+                    userMap.set(u.id.toString(), u);
+            }
+            return result.participants.map((p) => {
+                const userId = this.getParticipantUserId(p);
+                const user = userMap.get(userId);
+                const parts = user ? [user.firstName, user.lastName].filter(Boolean) : [];
+                return {
+                    id: userId,
                     name: parts.join(" ") || "Unknown",
-                    username: p.username ?? undefined,
-                });
+                    username: user?.username ?? undefined,
+                    role: this.getParticipantRole(p),
+                };
+            });
+        }
+        // Basic group — use getParticipants (no role info available)
+        const participants = await this.client.getParticipants(entity, { limit });
+        return participants
+            .filter((p) => p instanceof Api.User)
+            .map((p) => {
+            const parts = [p.firstName, p.lastName].filter(Boolean);
+            return {
+                id: p.id.toString(),
+                name: parts.join(" ") || "Unknown",
+                username: p.username ?? undefined,
+                role: "member",
+            };
+        });
+    }
+    async getMyRole(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.resolveChat(chatId);
+        const me = await this.getMe();
+        if (entity instanceof Api.Channel) {
+            const result = await this.client.invoke(new Api.channels.GetParticipant({ channel: entity, participant: new Api.InputUserSelf() }));
+            return {
+                role: this.getParticipantRole(result.participant),
+                chatId: entity.id.toString(),
+                chatName: entity.title ?? "Unknown",
+            };
+        }
+        if (entity instanceof Api.Chat) {
+            // Basic group — check if creator
+            if (entity.creator) {
+                return { role: "creator", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
+            }
+            if (entity.adminRights) {
+                return { role: "admin", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
             }
+            return { role: "member", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
+        }
+        if (entity instanceof Api.User) {
+            return { role: "user", chatId: entity.id.toString(), chatName: me.username ?? "self" };
         }
-        return members;
+        return { role: "unknown", chatId: chatId, chatName: "Unknown" };
+    }
+    getParticipantUserId(p) {
+        if (p instanceof Api.ChannelParticipantCreator)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantAdmin)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantSelf)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantBanned)
+            return p.peer?.userId?.toString() ?? "0";
+        if (p instanceof Api.ChannelParticipant)
+            return p.userId.toString();
+        return "0";
+    }
+    getParticipantRole(p) {
+        if (p instanceof Api.ChannelParticipantCreator)
+            return "creator";
+        if (p instanceof Api.ChannelParticipantAdmin)
+            return "admin";
+        if (p instanceof Api.ChannelParticipantBanned)
+            return "banned";
+        if (p instanceof Api.ChannelParticipantLeft)
+            return "left";
+        return "member";
     }
     async getProfile(userId) {
         if (!this.client || !this.connected)
@@ -951,13 +1087,14 @@ export class TelegramService {
     async sendReaction(chatId, messageId, emoji, addToExisting = false) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const peer = await this.client.getInputEntity(chatId);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
         const reactionList = [];
         if (emoji) {
             const emojis = Array.isArray(emoji) ? emoji : [emoji];
             if (addToExisting) {
                 // Fetch current reactions to preserve them
-                const msgs = await this.client.getMessages(chatId, { ids: [messageId] });
+                const msgs = await this.client.getMessages(resolved, { ids: [messageId] });
                 const msg = msgs[0];
                 if (msg?.reactions?.results) {
                     for (const r of msg.reactions.results) {
@@ -990,9 +1127,10 @@ export class TelegramService {
     async getMessageReactions(chatId, messageId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const peer = await this.client.getInputEntity(chatId);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
         // First get the message to know which reactions exist
-        const msgs = await this.client.getMessages(chatId, { ids: [messageId] });
+        const msgs = await this.client.getMessages(resolved, { ids: [messageId] });
         const msg = msgs[0];
         if (!msg?.reactions?.results?.length) {
             return { reactions: [], total: 0 };
@@ -1044,7 +1182,8 @@ export class TelegramService {
     async sendScheduledMessage(chatId, text, scheduleDate, replyTo, parseMode) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.sendMessage(chatId, {
+        const resolved = await this.resolvePeer(chatId);
+        await this.client.sendMessage(resolved, {
             message: text,
             schedule: scheduleDate,
             ...(replyTo ? { replyTo } : {}),
@@ -1090,7 +1229,7 @@ export class TelegramService {
     async getForumTopics(chatId, limit = 100) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(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({
@@ -1149,7 +1288,7 @@ export class TelegramService {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
         try {
-            const entity = await this.client.getEntity(chatId);
+            const entity = await this.resolveChat(chatId);
             if (entity instanceof Api.Channel) {
                 return Boolean(entity.forum);
             }
@@ -1265,7 +1404,7 @@ export class TelegramService {
     async inviteToGroup(chatId, users) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         const invited = [];
         const failed = [];
         for (const u of users) {
@@ -1293,7 +1432,7 @@ export class TelegramService {
     async kickUser(chatId, userId) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
             throw new Error("Target is not a user");
@@ -1318,7 +1457,7 @@ export class TelegramService {
     async banUser(chatId, userId) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
             throw new Error("Target is not a user");
@@ -1334,7 +1473,7 @@ export class TelegramService {
     async unbanUser(chatId, userId) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
             throw new Error("Target is not a user");
@@ -1350,7 +1489,7 @@ export class TelegramService {
     async editGroup(chatId, options) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         if (options.title) {
             if (entity instanceof Api.Channel) {
                 await this.client.invoke(new Api.channels.EditTitle({ channel: entity, title: options.title }));
@@ -1380,7 +1519,7 @@ export class TelegramService {
     async leaveGroup(chatId) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         if (entity instanceof Api.Channel) {
             await this.client.invoke(new Api.channels.LeaveChannel({ channel: entity }));
         }
@@ -1397,7 +1536,7 @@ export class TelegramService {
     async setAdmin(chatId, userId, options) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         if (!(entity instanceof Api.Channel))
             throw new Error("Set admin is only supported for supergroups and channels");
         const user = await this.client.getEntity(userId);
@@ -1423,7 +1562,7 @@ export class TelegramService {
     async removeAdmin(chatId, userId) {
         if (!this.client)
             throw new Error("Not connected");
-        const entity = await this.client.getEntity(chatId);
+        const entity = await this.resolveChat(chatId);
         if (!(entity instanceof Api.Channel))
             throw new Error("Remove admin is only supported for supergroups and channels");
         const user = await this.client.getEntity(userId);

package/dist/tools/chats.js

@@ -93,13 +93,36 @@ export function registerChatTools(server, telegram) {
             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");
+            const text = members
+                .map((m) => {
+                const role = m.role !== "member" ? ` [${m.role}]` : "";
+                return `${m.name}${m.username ? ` (@${m.username})` : ""} (${m.id})${role}`;
+            })
+                .join("\n");
             return ok(sanitize(text) || "No members found");
         }
         catch (e) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-my-role", {
+        description: "Get the current user's role in a chat (creator, admin, or member)",
+        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 result = await telegram.getMyRole(chatId);
+            return ok(`Role: ${result.role}\nChat: ${result.chatName} (${result.chatId})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-create-group", {
         description: "Create a new Telegram group or supergroup",
         inputSchema: {

package/package.json

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