@overpod/mcp-telegram 1.15.0 → 1.16.0

package/dist/telegram-client.d.ts

@@ -267,4 +267,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));
@@ -1261,4 +1262,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.client.getEntity(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.client.getEntity(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.client.getEntity(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.client.getEntity(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.client.getEntity(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.client.getEntity(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.client.getEntity(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.client.getEntity(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.16.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",