@overpod/mcp-telegram 1.32.0 → 1.34.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.34.0] — 2026-04-24
+
+### Added
+
+**Star Gifts (7 new tools, opt-in `MCP_TELEGRAM_ENABLE_STARS=1`):**
+- **telegram-get-available-star-gifts** — List all available Star Gift catalog items: gift ID, cost in Stars, conversion value, limited-edition availability, and upgrade cost
+- **telegram-get-saved-star-gifts** — List Star Gifts received by a user/chat. Supports pagination (`offset`/`nextOffset`), filter flags (`excludeUnsaved`, `excludeSaved`, `excludeUnlimited`, `excludeLimited`, `excludeUnique`), and `sortByValue`. Returns kind (regular/unique), from-peer, date, and upgrade eligibility
+- **telegram-save-star-gift** — Show or hide a received gift on your profile. For personal gifts pass `msgId`; for chat/channel gifts pass `chatId` + `savedId`. Set `unsave=true` to hide, omit to show
+- **telegram-convert-star-gift** — Convert a received gift into Stars (non-reversible, removes gift from profile). Same addressing as save: `msgId` for personal, `chatId`+`savedId` for chat gifts
+- **telegram-get-stars-topup-options** — List available Stars top-up tiers with star count, currency, price amount (smallest currency units), and extended/standard tier flag
+- **telegram-get-stars-subscriptions** — List active Stars subscriptions for a peer (`me` for self). Returns subscription ID, peer, until date, billing period (seconds), price in Stars, canceled status, and title. Pagination via `offset`
+- **telegram-change-stars-subscription** — Cancel or restore a Stars subscription by ID. `canceled=true` to cancel before next renewal, `canceled=false` to restore
+
+## [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;
@@ -850,6 +901,75 @@ export declare class TelegramService {
         offset?: string;
         limit?: number;
     }): Promise<StarsStatusSummary>;
+    getAvailableStarGifts(): Promise<Array<{
+        id: string;
+        stars: string;
+        convertStars: string;
+        limited: boolean;
+        availabilityRemains?: number;
+        availabilityTotal?: number;
+        upgradeStars?: string;
+    }>>;
+    getSavedStarGifts(chatId: string, opts?: {
+        limit?: number;
+        offset?: string;
+        excludeUnsaved?: boolean;
+        excludeSaved?: boolean;
+        excludeUnlimited?: boolean;
+        excludeLimited?: boolean;
+        excludeUnique?: boolean;
+        sortByValue?: boolean;
+    }): Promise<{
+        count: number;
+        nextOffset?: string;
+        gifts: Array<{
+            giftId: string;
+            giftKind: "regular" | "unique";
+            giftTitle?: string;
+            stars?: string;
+            convertStars?: string;
+            msgId?: number;
+            savedId?: string;
+            fromPeerId?: string;
+            date: number;
+            unsaved: boolean;
+            canUpgrade: boolean;
+            upgradeStars?: string;
+        }>;
+    }>;
+    saveStarGift(opts: {
+        msgId?: number;
+        chatId?: string;
+        savedId?: string;
+        unsave?: boolean;
+    }): Promise<void>;
+    convertStarGift(opts: {
+        msgId?: number;
+        chatId?: string;
+        savedId?: string;
+    }): Promise<void>;
+    getStarsTopupOptions(): Promise<Array<{
+        stars: string;
+        currency: string;
+        amount: string;
+        extended: boolean;
+    }>>;
+    getStarsSubscriptions(chatId: string, opts?: {
+        offset?: string;
+        missingBalance?: boolean;
+    }): Promise<{
+        subscriptions: Array<{
+            id: string;
+            peerId: string;
+            untilDate: number;
+            periodSeconds: number;
+            priceStars: string;
+            canceled: boolean;
+            title?: string;
+        }>;
+        nextOffset?: string;
+    }>;
+    changeStarsSubscription(chatId: string, subscriptionId: string, canceled: boolean): Promise<void>;
     getQuickReplies(hash?: string): Promise<QuickRepliesSummary>;
     getQuickReplyMessages(shortcutId: number, options?: {
         ids?: number[];

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)
@@ -4057,6 +4196,152 @@ export class TelegramService {
             return summarizeStarsStatus(response);
         }, `getStarsTransactions ${chatId}`);
     }
+    // ─── Star Gifts (v1.34.0) ──────────────────────────────────────────────────
+    async getAvailableStarGifts() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.payments.GetStarGifts({ hash: 0 }));
+        if (result.className === "payments.StarGiftsNotModified")
+            return [];
+        const gifts = result.className === "payments.StarGifts" ? result.gifts : [];
+        return gifts
+            .filter((g) => g instanceof Api.StarGift)
+            .map((g) => ({
+            id: g.id.toString(),
+            stars: g.stars.toString(),
+            convertStars: g.convertStars.toString(),
+            limited: g.limited ?? false,
+            availabilityRemains: g.availabilityRemains,
+            availabilityTotal: g.availabilityTotal,
+            upgradeStars: g.upgradeStars?.toString(),
+        }));
+    }
+    async getSavedStarGifts(chatId, opts = {}) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        const peer = await this.resolvePeer(chatId);
+        const resolved = await client.getInputEntity(peer);
+        const result = await client.invoke(new Api.payments.GetSavedStarGifts({
+            peer: resolved,
+            offset: opts.offset ?? "",
+            limit: opts.limit ?? 20,
+            excludeUnsaved: opts.excludeUnsaved,
+            excludeSaved: opts.excludeSaved,
+            excludeUnlimited: opts.excludeUnlimited,
+            excludeLimited: opts.excludeLimited,
+            excludeUnique: opts.excludeUnique,
+            sortByValue: opts.sortByValue,
+        }));
+        const r = result;
+        return {
+            count: r.count,
+            nextOffset: r.nextOffset,
+            gifts: r.gifts.map((sg) => {
+                const gift = sg.gift;
+                if (gift instanceof Api.StarGift) {
+                    return {
+                        giftId: gift.id.toString(),
+                        giftKind: "regular",
+                        stars: gift.stars.toString(),
+                        convertStars: gift.convertStars.toString(),
+                        msgId: sg.msgId ?? undefined,
+                        savedId: sg.savedId?.toString(),
+                        fromPeerId: sg.fromId ? summarizePeer(sg.fromId).id : undefined,
+                        date: sg.date,
+                        unsaved: sg.unsaved ?? false,
+                        canUpgrade: sg.canUpgrade ?? false,
+                        upgradeStars: sg.upgradeStars?.toString(),
+                    };
+                }
+                const u = gift;
+                return {
+                    giftId: u.id.toString(),
+                    giftKind: "unique",
+                    giftTitle: u.title,
+                    msgId: sg.msgId ?? undefined,
+                    savedId: sg.savedId?.toString(),
+                    fromPeerId: sg.fromId ? summarizePeer(sg.fromId).id : undefined,
+                    date: sg.date,
+                    unsaved: sg.unsaved ?? false,
+                    canUpgrade: false,
+                };
+            }),
+        };
+    }
+    async saveStarGift(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        let stargift;
+        if (opts.msgId !== undefined) {
+            stargift = new Api.InputSavedStarGiftUser({ msgId: opts.msgId });
+        }
+        else if (opts.chatId && opts.savedId) {
+            const peer = await this.resolvePeer(opts.chatId);
+            const inputPeer = await client.getInputEntity(peer);
+            stargift = new Api.InputSavedStarGiftChat({ peer: inputPeer, savedId: bigInt(opts.savedId) });
+        }
+        else {
+            throw new Error("Provide msgId (user gift) or both chatId and savedId (chat gift)");
+        }
+        await client.invoke(new Api.payments.SaveStarGift({ stargift, unsave: opts.unsave }));
+    }
+    async convertStarGift(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        let stargift;
+        if (opts.msgId !== undefined) {
+            stargift = new Api.InputSavedStarGiftUser({ msgId: opts.msgId });
+        }
+        else if (opts.chatId && opts.savedId) {
+            const peer = await this.resolvePeer(opts.chatId);
+            const inputPeer = await client.getInputEntity(peer);
+            stargift = new Api.InputSavedStarGiftChat({ peer: inputPeer, savedId: bigInt(opts.savedId) });
+        }
+        else {
+            throw new Error("Provide msgId (user gift) or both chatId and savedId (chat gift)");
+        }
+        await client.invoke(new Api.payments.ConvertStarGift({ stargift }));
+    }
+    async getStarsTopupOptions() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.payments.GetStarsTopupOptions());
+        return result.map((o) => ({
+            stars: o.stars.toString(),
+            currency: o.currency,
+            amount: o.amount.toString(),
+            extended: o.extended ?? false,
+        }));
+    }
+    async getStarsSubscriptions(chatId, opts = {}) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const peer = await this.resolvePeer(chatId);
+        const result = await this.client.invoke(new Api.payments.GetStarsSubscriptions({ peer, offset: opts.offset ?? "", missingBalance: opts.missingBalance }));
+        const r = result;
+        const subs = r.subscriptions ?? [];
+        return {
+            subscriptions: subs.map((s) => ({
+                id: s.id,
+                peerId: summarizePeer(s.peer).id,
+                untilDate: s.untilDate,
+                periodSeconds: s.pricing.period,
+                priceStars: s.pricing.amount.toString(),
+                canceled: s.canceled ?? false,
+                title: s.title,
+            })),
+            nextOffset: r.subscriptionsNextOffset,
+        };
+    }
+    async changeStarsSubscription(chatId, subscriptionId, canceled) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const peer = await this.resolvePeer(chatId);
+        await this.client.invoke(new Api.payments.ChangeStarsSubscription({ peer, subscriptionId, canceled }));
+    }
     // ─── Quick replies ─────────────────────────────────────────────────────────
     async getQuickReplies(hash) {
         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/dist/tools/stars.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function isStarsEnabled() {
     return process.env.MCP_TELEGRAM_ENABLE_STARS === "1";
 }
@@ -68,4 +68,181 @@ export function registerStarsTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-available-star-gifts", {
+        description: "List all available Telegram Star Gifts that can be sent to other users. Returns gift ID, cost in Stars, conversion value, availability (for limited gifts), and upgrade cost. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const gifts = await telegram.getAvailableStarGifts();
+            return ok(JSON.stringify(gifts));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-saved-star-gifts", {
+        description: "List Star Gifts received by a user or chat. Pass 'me' for your own gifts. Supports pagination via offset/nextOffset and filtering flags. Returns gift ID, kind (regular/unique), stars cost, from-peer, date, and upgrade eligibility. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            chatId: z.string().describe("User or chat to fetch received gifts for — 'me' for self"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max gifts per page"),
+            offset: z.string().optional().describe("Pagination cursor from a prior response's nextOffset"),
+            excludeUnsaved: z.boolean().optional().describe("Skip gifts the recipient chose to hide"),
+            excludeSaved: z.boolean().optional().describe("Skip gifts the recipient chose to show"),
+            excludeUnlimited: z.boolean().optional().describe("Skip unlimited-edition gifts"),
+            excludeLimited: z.boolean().optional().describe("Skip limited-edition gifts"),
+            excludeUnique: z.boolean().optional().describe("Skip unique gifts"),
+            sortByValue: z.boolean().optional().describe("Sort by Star value descending instead of date"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit, offset, excludeUnsaved, excludeSaved, excludeUnlimited, excludeLimited, excludeUnique, sortByValue, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getSavedStarGifts(chatId, {
+                limit,
+                offset,
+                excludeUnsaved,
+                excludeSaved,
+                excludeUnlimited,
+                excludeLimited,
+                excludeUnique,
+                sortByValue,
+            });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-save-star-gift", {
+        description: "Show or hide a received Star Gift on your profile. Pass msgId for a gift received as a personal message (DM), or chatId + savedId for a gift in a chat/channel. Set unsave=true to hide the gift (remove from profile display). Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            msgId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Message ID of the gift (from your DMs) — use this for personal gifts"),
+            chatId: z
+                .string()
+                .optional()
+                .describe("Chat/channel ID where the gift was received (required with savedId for chat gifts)"),
+            savedId: z
+                .string()
+                .regex(/^\d+$/, "must be a numeric saved gift ID")
+                .optional()
+                .describe("Saved gift ID (from get-saved-star-gifts) — required with chatId for chat gifts"),
+            unsave: z.boolean().optional().describe("true = hide the gift from profile; false/omit = show it"),
+        },
+        annotations: WRITE,
+    }, async ({ msgId, chatId, savedId, unsave }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (msgId === undefined && !(chatId && savedId)) {
+            return fail(new Error("Provide msgId, or both chatId and savedId"));
+        }
+        try {
+            await telegram.saveStarGift({ msgId, chatId, savedId, unsave });
+            return ok(unsave ? "Gift hidden from profile" : "Gift shown on profile");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-convert-star-gift", {
+        description: "Convert a received Star Gift into Stars (non-reversible). The gift is removed from your profile and its conversion value is added to your Stars balance. Pass msgId for personal gifts or chatId + savedId for chat gifts. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            msgId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Message ID of the gift (from your DMs) — for personal gifts"),
+            chatId: z.string().optional().describe("Chat/channel ID (for chat gifts, required with savedId)"),
+            savedId: z
+                .string()
+                .regex(/^\d+$/, "must be a numeric saved gift ID")
+                .optional()
+                .describe("Saved gift ID — for chat gifts, required with chatId"),
+        },
+        annotations: WRITE,
+    }, async ({ msgId, chatId, savedId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (msgId === undefined && !(chatId && savedId)) {
+            return fail(new Error("Provide msgId, or both chatId and savedId"));
+        }
+        try {
+            await telegram.convertStarGift({ msgId, chatId, savedId });
+            return ok("Gift converted to Stars");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stars-topup-options", {
+        description: "List available Telegram Stars top-up tiers (from payments.GetStarsTopupOptions). Returns each option with star count, currency, price amount (in smallest currency units), and whether it is an extended/premium tier. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const options = await telegram.getStarsTopupOptions();
+            return ok(JSON.stringify(options));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stars-subscriptions", {
+        description: "List active Telegram Stars subscriptions for a peer (payments.GetStarsSubscriptions). Pass 'me' for your own account or a bot/channel you own. Returns subscription ID, peer, renewal date, period, price in Stars, and canceled status. Paginate with offset. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            chatId: z.string().describe("Peer to query — 'me' for your own subscriptions, or a bot/channel you own"),
+            offset: z.string().optional().describe("Pagination cursor from a prior nextOffset"),
+            missingBalance: z.boolean().optional().describe("If true, return only subscriptions with missing balance"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, offset, missingBalance }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStarsSubscriptions(chatId, { offset, missingBalance });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-change-stars-subscription", {
+        description: "Cancel or restore a Telegram Stars subscription (payments.ChangeStarsSubscription). Pass canceled=true to cancel an active subscription before its next renewal, or false to restore a previously canceled one. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            chatId: z
+                .string()
+                .describe("The peer the subscription belongs to — 'me' for your own subscriptions or a bot/channel you own"),
+            subscriptionId: z.string().min(1).describe("Subscription ID (from telegram-get-stars-subscriptions)"),
+            canceled: z.boolean().describe("true = cancel the subscription; false = restore a canceled subscription"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, subscriptionId, canceled }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.changeStarsSubscription(chatId, subscriptionId, canceled);
+            return ok(canceled ? `Subscription ${subscriptionId} canceled` : `Subscription ${subscriptionId} restored`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/package.json

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