@overpod/mcp-telegram 1.15.0 → 1.17.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;
@@ -267,4 +277,21 @@ export declare class TelegramService {
         type: string;
         inviteLink?: string;
     }>;
+    inviteToGroup(chatId: string, users: string[]): Promise<{
+        invited: string[];
+        failed: string[];
+    }>;
+    kickUser(chatId: string, userId: string): Promise<void>;
+    banUser(chatId: string, userId: string): Promise<void>;
+    unbanUser(chatId: string, userId: string): Promise<void>;
+    editGroup(chatId: string, options: {
+        title?: string;
+        description?: string;
+        photoPath?: string;
+    }): Promise<void>;
+    leaveGroup(chatId: string): Promise<void>;
+    setAdmin(chatId: string, userId: string, options?: {
+        title?: string;
+    }): Promise<void>;
+    removeAdmin(chatId: string, userId: string): Promise<void>;
 }

package/dist/telegram-client.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { chmod, readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import bigInt from "big-integer";
 import QRCode from "qrcode";
 import { TelegramClient } from "telegram";
+import { CustomFile } from "telegram/client/uploads.js";
 import { StringSession } from "telegram/sessions/index.js";
 import { Api } from "telegram/tl/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -298,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,
@@ -312,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" } : {}),
@@ -322,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`);
@@ -342,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`);
@@ -377,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)
@@ -504,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 {
@@ -627,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);
@@ -780,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 } : {}),
@@ -950,13 +1007,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) {
@@ -989,9 +1047,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 };
@@ -1043,7 +1102,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 } : {}),
@@ -1089,7 +1149,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({
@@ -1148,7 +1208,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);
             }
@@ -1261,4 +1321,179 @@ export class TelegramService {
             throw new Error("Failed to create group");
         return { id: chat.id.toString(), title, type: "group" };
     }
+    async inviteToGroup(chatId, users) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.resolveChat(chatId);
+        const invited = [];
+        const failed = [];
+        for (const u of users) {
+            try {
+                const user = await this.client.getEntity(u);
+                if (!(user instanceof Api.User)) {
+                    failed.push(u);
+                    continue;
+                }
+                const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+                if (entity instanceof Api.Channel) {
+                    await this.client.invoke(new Api.channels.InviteToChannel({ channel: entity, users: [inputUser] }));
+                }
+                else if (entity instanceof Api.Chat) {
+                    await this.client.invoke(new Api.messages.AddChatUser({ chatId: entity.id, userId: inputUser, fwdLimit: 50 }));
+                }
+                invited.push(u);
+            }
+            catch {
+                failed.push(u);
+            }
+        }
+        return { invited, failed };
+    }
+    async kickUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        if (entity instanceof Api.Channel) {
+            // Kick = ban + unban (removes without permanent ban)
+            await this.client.invoke(new Api.channels.EditBanned({
+                channel: entity,
+                participant: inputUser,
+                bannedRights: new Api.ChatBannedRights({ untilDate: 0, viewMessages: true }),
+            }));
+            await this.client.invoke(new Api.channels.EditBanned({
+                channel: entity,
+                participant: inputUser,
+                bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+            }));
+        }
+        else if (entity instanceof Api.Chat) {
+            await this.client.invoke(new Api.messages.DeleteChatUser({ chatId: entity.id, userId: inputUser }));
+        }
+    }
+    async banUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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");
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Ban is only supported for supergroups and channels");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditBanned({
+            channel: entity,
+            participant: inputUser,
+            bannedRights: new Api.ChatBannedRights({ untilDate: 0, viewMessages: true }),
+        }));
+    }
+    async unbanUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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");
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Unban is only supported for supergroups and channels");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditBanned({
+            channel: entity,
+            participant: inputUser,
+            bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+        }));
+    }
+    async editGroup(chatId, options) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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 }));
+            }
+            else if (entity instanceof Api.Chat) {
+                await this.client.invoke(new Api.messages.EditChatTitle({ chatId: entity.id, title: options.title }));
+            }
+        }
+        if (options.description != null) {
+            await this.client.invoke(new Api.messages.EditChatAbout({ peer: entity, about: options.description }));
+        }
+        if (options.photoPath) {
+            const fileData = readFileSync(options.photoPath);
+            const uploaded = await this.client.uploadFile({
+                file: new CustomFile(options.photoPath, fileData.length, options.photoPath, fileData),
+                workers: 1,
+            });
+            const inputPhoto = new Api.InputChatUploadedPhoto({ file: uploaded });
+            if (entity instanceof Api.Channel) {
+                await this.client.invoke(new Api.channels.EditPhoto({ channel: entity, photo: inputPhoto }));
+            }
+            else if (entity instanceof Api.Chat) {
+                await this.client.invoke(new Api.messages.EditChatPhoto({ chatId: entity.id, photo: inputPhoto }));
+            }
+        }
+    }
+    async leaveGroup(chatId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.resolveChat(chatId);
+        if (entity instanceof Api.Channel) {
+            await this.client.invoke(new Api.channels.LeaveChannel({ channel: entity }));
+        }
+        else if (entity instanceof Api.Chat) {
+            await this.client.invoke(new Api.messages.DeleteChatUser({
+                chatId: entity.id,
+                userId: new Api.InputUserSelf(),
+            }));
+        }
+        else {
+            throw new Error("Target is not a group or channel");
+        }
+    }
+    async setAdmin(chatId, userId, options) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditAdmin({
+            channel: entity,
+            userId: inputUser,
+            adminRights: new Api.ChatAdminRights({
+                changeInfo: true,
+                postMessages: true,
+                editMessages: true,
+                deleteMessages: true,
+                banUsers: true,
+                inviteUsers: true,
+                pinMessages: true,
+                manageCall: true,
+            }),
+            rank: options?.title ?? "",
+        }));
+    }
+    async removeAdmin(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        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);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditAdmin({
+            channel: entity,
+            userId: inputUser,
+            adminRights: new Api.ChatAdminRights({}),
+            rank: "",
+        }));
+    }
 }

package/dist/tools/chats.js

@@ -145,4 +145,164 @@ export function registerChatTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-leave-group", {
+        description: "Leave a Telegram group or channel",
+        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.leaveGroup(chatId);
+            return ok(`Left chat ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-invite-to-group", {
+        description: "Invite users to a Telegram group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            users: z.array(z.string()).describe("Usernames or IDs to invite"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, users }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.inviteToGroup(chatId, users);
+            const lines = [];
+            if (result.invited.length > 0)
+                lines.push(`Invited: ${result.invited.join(", ")}`);
+            if (result.failed.length > 0)
+                lines.push(`Failed: ${result.failed.join(", ")}`);
+            return ok(lines.join("\n") || "No users processed");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-kick-user", {
+        description: "Kick a user from a Telegram group (removes without permanent ban)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to kick"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.kickUser(chatId, userId);
+            return ok(`Kicked ${userId} from ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-ban-user", {
+        description: "Ban a user from a supergroup or channel (permanent until unbanned)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to ban"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.banUser(chatId, userId);
+            return ok(`Banned ${userId} from ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-unban-user", {
+        description: "Unban a previously banned user from a supergroup or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to unban"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.unbanUser(chatId, userId);
+            return ok(`Unbanned ${userId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-group", {
+        description: "Edit a group's title, description, or photo",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            title: z.string().optional().describe("New group title"),
+            description: z.string().optional().describe("New group description (supergroups only)"),
+            photoPath: z.string().optional().describe("Absolute path to new group photo image file"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, title, description, photoPath }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editGroup(chatId, { title, description, photoPath });
+            const changed = [title && "title", description != null && "description", photoPath && "photo"].filter(Boolean);
+            return ok(`Updated ${changed.join(", ")} for ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-admin", {
+        description: "Promote a user to admin in a supergroup or channel with full permissions",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to promote"),
+            title: z.string().optional().describe("Custom admin title"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId, title }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setAdmin(chatId, userId, { title });
+            return ok(`Promoted ${userId} to admin in ${chatId}${title ? ` (${title})` : ""}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-remove-admin", {
+        description: "Remove admin rights from a user in a supergroup or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to demote"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.removeAdmin(chatId, userId);
+            return ok(`Removed admin rights from ${userId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/package.json

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