@overpod/mcp-telegram 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.33.0] — 2026-04-24
+
+### Added
+
+**Folder management (6 new tools):**
+- **telegram-create-folder** — Create a new chat folder. Accepts `title` (max 12 chars), optional `emoticon`, type flags (`contacts`, `nonContacts`, `groups`, `broadcasts`, `bots`), filter flags (`excludeMuted`, `excludeRead`, `excludeArchived`), and peer lists (`includePeers`, `excludePeers`, `pinnedPeers` max 5). Auto-assigns the next available folder ID ≥ 2. Returns the new ID
+- **telegram-edit-folder** — Edit an existing folder by `id`. Only pass fields to change — omitted fields preserve current values (fetches current state first via `messages.GetDialogFilters`)
+- **telegram-delete-folder** — Delete a chat folder by ID. Chats remain in All Chats. System folders (0 = All Chats, 1 = Archive) cannot be deleted. Uses `messages.UpdateDialogFilter` without a filter argument
+- **telegram-reorder-folders** — Set the display order of folders by passing an ordered array of folder IDs. Uses `messages.UpdateDialogFiltersOrder`
+- **telegram-get-suggested-folders** — Fetch Telegram's server-side folder suggestions based on your chat list (e.g. "Unread", "Work", "Personal"). Skips `DialogFilterDefault` entries that lack a title
+- **telegram-toggle-folder-tags** — Enable or disable folder tag labels on messages in chat lists. Requires Telegram Premium. Uses `messages.ToggleDialogFilterTags`
+
+**Global privacy (2 new tools):**
+- **telegram-get-global-privacy-settings** — Read all five global privacy flags: `archiveAndMuteNewNoncontactPeers`, `keepArchivedUnmuted`, `keepArchivedFolders`, `hideReadMarks`, `newNoncontactPeersRequirePremium`. Returns JSON
+- **telegram-set-global-privacy-settings** — Update any subset of global privacy flags. Fetches current settings first and merges only the fields you pass. `hideReadMarks` and `newNoncontactPeersRequirePremium` require Telegram Premium
+
 ## [1.32.0] — 2026-04-24
 
 ### Added

package/dist/telegram-client.d.ts

@@ -646,6 +646,57 @@ export declare class TelegramService {
         includeCount: number;
     }>>;
     setAutoDelete(chatId: string, period: number): Promise<void>;
+    createFolder(opts: {
+        title: string;
+        emoticon?: string;
+        contacts?: boolean;
+        nonContacts?: boolean;
+        groups?: boolean;
+        broadcasts?: boolean;
+        bots?: boolean;
+        excludeMuted?: boolean;
+        excludeRead?: boolean;
+        excludeArchived?: boolean;
+        includePeers?: string[];
+        excludePeers?: string[];
+        pinnedPeers?: string[];
+    }): Promise<number>;
+    editFolder(id: number, opts: {
+        title?: string;
+        emoticon?: string;
+        contacts?: boolean;
+        nonContacts?: boolean;
+        groups?: boolean;
+        broadcasts?: boolean;
+        bots?: boolean;
+        excludeMuted?: boolean;
+        excludeRead?: boolean;
+        excludeArchived?: boolean;
+        includePeers?: string[];
+        excludePeers?: string[];
+        pinnedPeers?: string[];
+    }): Promise<void>;
+    deleteFolder(id: number): Promise<void>;
+    reorderFolders(ids: number[]): Promise<void>;
+    getSuggestedFolders(): Promise<Array<{
+        title: string;
+        emoticon?: string;
+    }>>;
+    toggleDialogFilterTags(enabled: boolean): Promise<void>;
+    getGlobalPrivacySettings(): Promise<{
+        archiveAndMuteNewNoncontactPeers: boolean;
+        keepArchivedUnmuted: boolean;
+        keepArchivedFolders: boolean;
+        hideReadMarks: boolean;
+        newNoncontactPeersRequirePremium: boolean;
+    }>;
+    setGlobalPrivacySettings(opts: {
+        archiveAndMuteNewNoncontactPeers?: boolean;
+        keepArchivedUnmuted?: boolean;
+        keepArchivedFolders?: boolean;
+        hideReadMarks?: boolean;
+        newNoncontactPeersRequirePremium?: boolean;
+    }): Promise<void>;
     getActiveSessions(): Promise<Array<{
         hash: string;
         device: string;

package/dist/telegram-client.js

@@ -3089,6 +3089,145 @@ export class TelegramService {
         const peer = await this.client.getInputEntity(resolved);
         await this.client.invoke(new Api.messages.SetHistoryTTL({ peer, period }));
     }
+    // ─── Folder management (v1.33.0) ───────────────────────────────────────────
+    async createFolder(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        const filtersResult = await client.invoke(new Api.messages.GetDialogFilters());
+        const existing = "filters" in filtersResult ? filtersResult.filters : [];
+        const usedIds = existing
+            .filter((f) => "id" in f)
+            .map((f) => f.id);
+        let newId = 2;
+        while (usedIds.includes(newId))
+            newId++;
+        const toInput = async (ids) => {
+            const peers = [];
+            for (const id of ids) {
+                const resolved = await this.resolvePeer(id);
+                peers.push(await client.getInputEntity(resolved));
+            }
+            return peers;
+        };
+        const includePeers = await toInput(opts.includePeers ?? []);
+        const excludePeers = await toInput(opts.excludePeers ?? []);
+        const pinnedPeers = await toInput(opts.pinnedPeers ?? []);
+        await client.invoke(new Api.messages.UpdateDialogFilter({
+            id: newId,
+            filter: new Api.DialogFilter({
+                id: newId,
+                title: new Api.TextWithEntities({ text: opts.title, entities: [] }),
+                emoticon: opts.emoticon,
+                contacts: opts.contacts,
+                nonContacts: opts.nonContacts,
+                groups: opts.groups,
+                broadcasts: opts.broadcasts,
+                bots: opts.bots,
+                excludeMuted: opts.excludeMuted,
+                excludeRead: opts.excludeRead,
+                excludeArchived: opts.excludeArchived,
+                pinnedPeers,
+                includePeers,
+                excludePeers,
+            }),
+        }));
+        return newId;
+    }
+    async editFolder(id, opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        const filtersResult = await client.invoke(new Api.messages.GetDialogFilters());
+        const existing = "filters" in filtersResult ? filtersResult.filters : [];
+        const current = existing.find((f) => f instanceof Api.DialogFilter && f.id === id);
+        if (!current)
+            throw new Error(`Folder with id=${id} not found`);
+        const toInput = async (ids) => {
+            const peers = [];
+            for (const id of ids) {
+                const resolved = await this.resolvePeer(id);
+                peers.push(await client.getInputEntity(resolved));
+            }
+            return peers;
+        };
+        const includePeers = opts.includePeers !== undefined ? await toInput(opts.includePeers) : current.includePeers;
+        const excludePeers = opts.excludePeers !== undefined ? await toInput(opts.excludePeers) : current.excludePeers;
+        const pinnedPeers = opts.pinnedPeers !== undefined ? await toInput(opts.pinnedPeers) : current.pinnedPeers;
+        const titleText = opts.title !== undefined ? opts.title : typeof current.title === "string" ? current.title : current.title.text;
+        await client.invoke(new Api.messages.UpdateDialogFilter({
+            id,
+            filter: new Api.DialogFilter({
+                id,
+                title: new Api.TextWithEntities({ text: titleText, entities: [] }),
+                emoticon: opts.emoticon !== undefined ? opts.emoticon : current.emoticon,
+                contacts: opts.contacts !== undefined ? opts.contacts : current.contacts,
+                nonContacts: opts.nonContacts !== undefined ? opts.nonContacts : current.nonContacts,
+                groups: opts.groups !== undefined ? opts.groups : current.groups,
+                broadcasts: opts.broadcasts !== undefined ? opts.broadcasts : current.broadcasts,
+                bots: opts.bots !== undefined ? opts.bots : current.bots,
+                excludeMuted: opts.excludeMuted !== undefined ? opts.excludeMuted : current.excludeMuted,
+                excludeRead: opts.excludeRead !== undefined ? opts.excludeRead : current.excludeRead,
+                excludeArchived: opts.excludeArchived !== undefined ? opts.excludeArchived : current.excludeArchived,
+                pinnedPeers,
+                includePeers,
+                excludePeers,
+            }),
+        }));
+    }
+    async deleteFolder(id) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.messages.UpdateDialogFilter({ id }));
+    }
+    async reorderFolders(ids) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.messages.UpdateDialogFiltersOrder({ order: ids }));
+    }
+    async getSuggestedFolders() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.GetSuggestedDialogFilters());
+        return result
+            .filter((s) => s.filter instanceof Api.DialogFilter || s.filter instanceof Api.DialogFilterChatlist)
+            .map((s) => ({
+            title: typeof s.filter.title === "string" ? s.filter.title : s.filter.title.text,
+            emoticon: s.filter.emoticon,
+        }));
+    }
+    async toggleDialogFilterTags(enabled) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.messages.ToggleDialogFilterTags({ enabled }));
+    }
+    // ─── Global privacy (v1.33.0) ──────────────────────────────────────────────
+    async getGlobalPrivacySettings() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const s = await this.client.invoke(new Api.account.GetGlobalPrivacySettings());
+        return {
+            archiveAndMuteNewNoncontactPeers: s.archiveAndMuteNewNoncontactPeers ?? false,
+            keepArchivedUnmuted: s.keepArchivedUnmuted ?? false,
+            keepArchivedFolders: s.keepArchivedFolders ?? false,
+            hideReadMarks: s.hideReadMarks ?? false,
+            newNoncontactPeersRequirePremium: s.newNoncontactPeersRequirePremium ?? false,
+        };
+    }
+    async setGlobalPrivacySettings(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const current = await this.client.invoke(new Api.account.GetGlobalPrivacySettings());
+        await this.client.invoke(new Api.account.SetGlobalPrivacySettings({
+            settings: new Api.GlobalPrivacySettings({
+                archiveAndMuteNewNoncontactPeers: opts.archiveAndMuteNewNoncontactPeers ?? current.archiveAndMuteNewNoncontactPeers,
+                keepArchivedUnmuted: opts.keepArchivedUnmuted ?? current.keepArchivedUnmuted,
+                keepArchivedFolders: opts.keepArchivedFolders ?? current.keepArchivedFolders,
+                hideReadMarks: opts.hideReadMarks ?? current.hideReadMarks,
+                newNoncontactPeersRequirePremium: opts.newNoncontactPeersRequirePremium ?? current.newNoncontactPeersRequirePremium,
+            }),
+        }));
+    }
     // ─── Account & privacy ─────────────────────────────────────────────────────
     async getActiveSessions() {
         if (!this.client || !this.connected)

package/dist/tools/folders.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerFolderTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/folders.js

@@ -0,0 +1,239 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+export function registerFolderTools(server, telegram) {
+    server.registerTool("telegram-create-folder", {
+        description: "Create a new Telegram chat folder (filter). Returns the new folder ID. Pass type flags to auto-include entire categories, or list specific chats in includePeers. Emoticon must be a single emoji character.",
+        inputSchema: {
+            title: z.string().min(1).max(12).describe("Folder name (max 12 chars)"),
+            emoticon: z.string().max(2).optional().describe("Single emoji icon for the folder"),
+            contacts: z.boolean().optional().describe("Include all contacts"),
+            nonContacts: z.boolean().optional().describe("Include all non-contacts"),
+            groups: z.boolean().optional().describe("Include all groups"),
+            broadcasts: z.boolean().optional().describe("Include all channels"),
+            bots: z.boolean().optional().describe("Include all bots"),
+            excludeMuted: z.boolean().optional().describe("Exclude muted chats"),
+            excludeRead: z.boolean().optional().describe("Exclude read chats"),
+            excludeArchived: z.boolean().optional().describe("Exclude archived chats"),
+            includePeers: z
+                .array(z.string())
+                .max(100)
+                .optional()
+                .describe("Chat IDs/usernames to explicitly include (max 100)"),
+            excludePeers: z
+                .array(z.string())
+                .max(100)
+                .optional()
+                .describe("Chat IDs/usernames to explicitly exclude (max 100)"),
+            pinnedPeers: z.array(z.string()).max(5).optional().describe("Chats to pin at top of this folder (max 5)"),
+        },
+        annotations: WRITE,
+    }, async ({ title, emoticon, contacts, nonContacts, groups, broadcasts, bots, excludeMuted, excludeRead, excludeArchived, includePeers, excludePeers, pinnedPeers, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const id = await telegram.createFolder({
+                title,
+                emoticon,
+                contacts,
+                nonContacts,
+                groups,
+                broadcasts,
+                bots,
+                excludeMuted,
+                excludeRead,
+                excludeArchived,
+                includePeers,
+                excludePeers,
+                pinnedPeers,
+            });
+            return ok(`Folder created: "${title}" [id=${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-folder", {
+        description: "Edit an existing Telegram chat folder by its ID (from telegram-get-chat-folders). Only pass fields you want to change — omitted fields keep their current values.",
+        inputSchema: {
+            id: z.number().int().min(2).describe("Folder ID (≥ 2; 0 = All Chats, 1 = Archive are system folders)"),
+            title: z.string().min(1).max(12).optional().describe("New folder name (max 12 chars)"),
+            emoticon: z.string().max(2).optional().describe("New emoji icon"),
+            contacts: z.boolean().optional(),
+            nonContacts: z.boolean().optional(),
+            groups: z.boolean().optional(),
+            broadcasts: z.boolean().optional(),
+            bots: z.boolean().optional(),
+            excludeMuted: z.boolean().optional(),
+            excludeRead: z.boolean().optional(),
+            excludeArchived: z.boolean().optional(),
+            includePeers: z.array(z.string()).max(100).optional().describe("Replace includePeers list entirely"),
+            excludePeers: z.array(z.string()).max(100).optional().describe("Replace excludePeers list entirely"),
+            pinnedPeers: z.array(z.string()).max(5).optional().describe("Replace pinnedPeers list entirely"),
+        },
+        annotations: WRITE,
+    }, async ({ id, title, emoticon, contacts, nonContacts, groups, broadcasts, bots, excludeMuted, excludeRead, excludeArchived, includePeers, excludePeers, pinnedPeers, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editFolder(id, {
+                title,
+                emoticon,
+                contacts,
+                nonContacts,
+                groups,
+                broadcasts,
+                bots,
+                excludeMuted,
+                excludeRead,
+                excludeArchived,
+                includePeers,
+                excludePeers,
+                pinnedPeers,
+            });
+            return ok(`Folder ${id} updated`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-folder", {
+        description: "Delete a Telegram chat folder by its ID. Chats inside the folder are not deleted — they remain in All Chats. System folders (0 = All Chats, 1 = Archive) cannot be deleted.",
+        inputSchema: {
+            id: z.number().int().min(2).describe("Folder ID to delete (≥ 2)"),
+        },
+        annotations: WRITE,
+    }, async ({ id }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.deleteFolder(id);
+            return ok(`Folder ${id} deleted`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-reorder-folders", {
+        description: "Reorder Telegram chat folders by specifying a new order of folder IDs. All existing custom folder IDs must be included.",
+        inputSchema: {
+            order: z
+                .array(z.number().int().min(2))
+                .min(1)
+                .describe("Ordered list of folder IDs (≥ 2). Obtain IDs from telegram-get-chat-folders"),
+        },
+        annotations: WRITE,
+    }, async ({ order }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.reorderFolders(order);
+            return ok(`Folders reordered: [${order.join(", ")}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-suggested-folders", {
+        description: "Get Telegram's suggested chat folders based on your chat list (e.g. 'Unread', 'Personal', 'Work'). Returns folder templates you can create with telegram-create-folder.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const suggestions = await telegram.getSuggestedFolders();
+            if (!suggestions.length)
+                return ok("No folder suggestions available");
+            return ok(suggestions.map((s) => `${s.emoticon ? `${s.emoticon} ` : ""}${s.title}`).join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-folder-tags", {
+        description: "Enable or disable folder tags (colored labels that appear on messages in chat lists when the message belongs to a tagged folder). Requires Telegram Premium.",
+        inputSchema: {
+            enabled: z.boolean().describe("true to enable folder tags, false to disable"),
+        },
+        annotations: WRITE,
+    }, async ({ enabled }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.toggleDialogFilterTags(enabled);
+            return ok(`Folder tags ${enabled ? "enabled" : "disabled"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-global-privacy-settings", {
+        description: "Get your account-level global privacy settings: whether new non-contacts are auto-archived/muted, whether archived chats are kept unmuted, whether read receipts are hidden, and whether non-contacts must have Premium to message you.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const s = await telegram.getGlobalPrivacySettings();
+            return ok(JSON.stringify(s, null, 2));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-global-privacy-settings", {
+        description: "Update account-level global privacy settings. Only pass the fields you want to change — omitted fields keep their current values. hideReadMarks and newNoncontactPeersRequirePremium require Telegram Premium.",
+        inputSchema: {
+            archiveAndMuteNewNoncontactPeers: z
+                .boolean()
+                .optional()
+                .describe("Auto-archive and mute messages from unknown users"),
+            keepArchivedUnmuted: z.boolean().optional().describe("Keep archived chats unmuted when archiving"),
+            keepArchivedFolders: z.boolean().optional().describe("Keep archived chats in their folders"),
+            hideReadMarks: z
+                .boolean()
+                .optional()
+                .describe("Hide read receipts — others cannot see when you read their messages (Premium)"),
+            newNoncontactPeersRequirePremium: z
+                .boolean()
+                .optional()
+                .describe("Only allow users with Telegram Premium to message you if they are not in your contacts (Premium)"),
+        },
+        annotations: WRITE,
+    }, async ({ archiveAndMuteNewNoncontactPeers, keepArchivedUnmuted, keepArchivedFolders, hideReadMarks, newNoncontactPeersRequirePremium, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setGlobalPrivacySettings({
+                archiveAndMuteNewNoncontactPeers,
+                keepArchivedUnmuted,
+                keepArchivedFolders,
+                hideReadMarks,
+                newNoncontactPeersRequirePremium,
+            });
+            const changed = Object.entries({
+                archiveAndMuteNewNoncontactPeers,
+                keepArchivedUnmuted,
+                keepArchivedFolders,
+                hideReadMarks,
+                newNoncontactPeersRequirePremium,
+            })
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(", ");
+            return ok(`Global privacy updated: ${changed || "no fields changed"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/index.js

@@ -6,6 +6,7 @@ import { registerChatTools } from "./chats.js";
 import { registerContactTools } from "./contacts.js";
 import { registerExtraTools } from "./extras.js";
 import { registerFactCheckTools } from "./fact-check.js";
+import { registerFolderTools } from "./folders.js";
 import { registerGroupCallTools } from "./group-calls.js";
 import { registerMediaTools } from "./media.js";
 import { registerMessageTools } from "./messages.js";
@@ -29,6 +30,7 @@ export function registerTools(server, telegram) {
     registerExtraTools(server, telegram);
     registerAccountTools(server, telegram);
     registerBusinessTools(server, telegram);
+    registerFolderTools(server, telegram);
     registerStickerTools(server, telegram);
     registerStoryTools(server, telegram);
     registerBoostTools(server, telegram);

package/package.json

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