@overpod/mcp-telegram 1.24.1 → 1.26.0

package/dist/tools/reactions.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
 export function registerReactionTools(server, telegram) {
     server.registerTool("telegram-send-reaction", {
         description: "Send emoji reaction(s) to a message. Supports multiple reactions and adding to existing ones. Omit emoji to remove all reactions",
@@ -60,4 +60,105 @@ export function registerReactionTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-set-default-reaction", {
+        description: "Set the default emoji reaction used in quick-reaction menus across Telegram",
+        inputSchema: {
+            emoji: z.string().min(1).max(8).describe("Emoji character (e.g. 👍 ❤️ 🔥)"),
+        },
+        annotations: WRITE,
+    }, async ({ emoji }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setDefaultReaction(emoji);
+            return ok(`Default reaction set to ${sanitize(emoji)}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-top-reactions", {
+        description: "Get the list of most popular emoji reactions available on Telegram",
+        inputSchema: {
+            limit: z.number().int().min(1).max(100).default(20).describe("Max number of reactions to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const reactions = await telegram.getTopReactions(limit);
+            if (reactions.length === 0)
+                return ok("No top reactions available");
+            return ok(sanitize(reactions.map((r) => r.emoji).join(" ")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-chat-reactions", {
+        description: "Set which reactions are available in a chat. type='all' allows all standard emoji (set allowCustom=true to also permit custom emoji for Premium users), type='some' restricts to a specific emoji list, type='none' disables reactions entirely. Requires admin",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (group, supergroup, or channel)"),
+            reactions: z
+                .discriminatedUnion("type", [
+                z.object({
+                    type: z.literal("all"),
+                    allowCustom: z
+                        .boolean()
+                        .optional()
+                        .describe("If true, also allow custom emoji reactions (requires Premium users)"),
+                }),
+                z.object({
+                    type: z.literal("some"),
+                    emoji: z
+                        .array(z.string().min(1).max(8))
+                        .min(1)
+                        .max(100)
+                        .describe("List of allowed reaction emoji (e.g. ['👍','❤️','🔥'])"),
+                }),
+                z.object({ type: z.literal("none") }),
+            ])
+                .describe("Reaction policy for the chat"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, reactions }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setChatAvailableReactions(chatId, reactions);
+            const summary = reactions.type === "all"
+                ? `all reactions${reactions.allowCustom ? " (incl. custom)" : ""}`
+                : reactions.type === "none"
+                    ? "no reactions"
+                    : `${reactions.emoji.length} reaction(s): ${sanitize(reactions.emoji.join(" "))}`;
+            return ok(`Set ${summary} for ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-recent-reactions", {
+        description: "Get the list of emoji reactions the current account used recently",
+        inputSchema: {
+            limit: z.number().int().min(1).max(100).default(20).describe("Max number of reactions to return"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const reactions = await telegram.getRecentReactions(limit);
+            if (reactions.length === 0)
+                return ok("No recent reactions");
+            return ok(sanitize(reactions.map((r) => r.emoji).join(" ")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/stars.d.ts

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

package/dist/tools/stars.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize } from "./shared.js";
+export function isStarsEnabled() {
+    return process.env.MCP_TELEGRAM_ENABLE_STARS === "1";
+}
+export function registerStarsTools(server, telegram) {
+    if (!isStarsEnabled())
+        return;
+    server.registerTool("telegram-get-stars-status", {
+        description: "Fetch the current Telegram Stars balance and recent activity for a peer (payments.GetStarsStatus). Pass 'me' / '@me' (or the user's own id) to inspect your own wallet, or a bot/channel peer you own/administrate. Returns {balance:{amount,nanos}, subscriptions?[], subscriptionsNextOffset?, subscriptionsMissingBalance?, history?[], nextOffset?}. Each transaction has id, stars, date, peer (kind: appStore|playMarket|premiumBot|fragment|ads|api|peer|unsupported), and flags (refund/pending/failed/gift/reaction). Use telegram-get-stars-transactions for full paginated history. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            peer: z
+                .string()
+                .describe("Peer whose Stars wallet to inspect — 'me'/'@me' or user id for self, or @username/id for a bot/channel you control"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ peer }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStarsStatus(peer);
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stars-transactions", {
+        description: "Fetch a paginated Telegram Stars transaction history for a peer (payments.GetStarsTransactions). Pass 'me'/'@me' (or your own user id) for your wallet, or a bot/channel peer you own/administrate. Filters: inbound (credits only), outbound (debits only), ascending (chronological; default descending), subscriptionId (scope to a single subscription). Paginate with offset (cursor string from a prior response's nextOffset) and limit (default 50). Returns {balance, history[], nextOffset?, subscriptions?[], ...} — same shape as telegram-get-stars-status but focused on transactions. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            peer: z
+                .string()
+                .describe("Peer whose Stars transactions to fetch — 'me'/'@me' or user id for self, or @username/id for a bot/channel you control"),
+            inbound: z.boolean().optional().describe("If true, return only inbound (credit) transactions"),
+            outbound: z.boolean().optional().describe("If true, return only outbound (debit) transactions"),
+            ascending: z
+                .boolean()
+                .optional()
+                .describe("If true, return transactions in chronological (oldest first) order; default: newest first"),
+            subscriptionId: z.string().optional().describe("If set, filter transactions to a single subscription id"),
+            offset: z
+                .string()
+                .optional()
+                .describe("Pagination cursor — pass the nextOffset from a previous response; empty/undefined for first page"),
+            limit: z.number().int().min(1).max(100).optional().describe("Max transactions per page (default 50, max 100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ peer, inbound, outbound, ascending, subscriptionId, offset, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (inbound && outbound) {
+            return fail(new Error("inbound and outbound are mutually exclusive — provide at most one"));
+        }
+        try {
+            const result = await telegram.getStarsTransactions(peer, {
+                inbound,
+                outbound,
+                ascending,
+                subscriptionId,
+                offset,
+                limit,
+            });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/stories.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 registerStoryTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/stories.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize } from "./shared.js";
+export function registerStoryTools(server, telegram) {
+    server.registerTool("telegram-get-all-stories", {
+        description: "Fetch active stories from contacts/channels the user follows. Pagination via 'next' + 'state' — pass the returned state back on the next call with next:true to load more. Use hidden:true to read stories from muted/archived peers. Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) without raw media blobs.",
+        inputSchema: {
+            next: z.boolean().optional().describe("Load the next page (use with state from a prior response)"),
+            hidden: z.boolean().optional().describe("Fetch stories from hidden/archived peers instead of the main feed"),
+            state: z.string().optional().describe("Pagination state token returned by a previous call"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ next, hidden, state }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (next === true && !state) {
+            return fail(new Error("'state' is required when 'next' is true — use the state token from a prior telegram-get-all-stories response"));
+        }
+        try {
+            const result = await telegram.getAllStories({ next, hidden, state });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-peer-stories", {
+        description: "Fetch currently active stories posted by a specific peer (user/channel). Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) with media type className only — no raw media blobs. Use telegram-download-media with the story id if you need media bytes.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Peer to fetch stories from — user/channel id, @username, phone, or display name fragment"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPeerStories(chat);
+            if (result === null)
+                return ok("No active stories found for the specified peer");
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stories-by-id", {
+        description: "Fetch specific stories from a peer by their numeric IDs. Useful for retrieving archived/pinned stories outside the active feed. Returns compact story metadata and optional pinnedToTop list. Pass up to ~100 ids per request.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Peer to fetch stories from — user/channel id, @username, phone, or display name fragment"),
+            ids: z.array(z.number().int().positive()).min(1).max(100).describe("Story IDs to fetch (1–100 per request)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, ids }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStoriesById(chat, ids);
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-story-views", {
+        description: "List viewers of one of YOUR stories (stories.GetStoryViewsList). Returns per-viewer entries (user id, view date, their reaction emoji if any), plus totals (viewsCount, forwardsCount, reactionsCount) and nextOffset for pagination. Pass your own user id (numeric) or @username as the peer — this only works for stories you posted. Some accounts (non-Premium, old stories) may not get a full viewer list — a Premium hint is surfaced on typical errors.",
+        inputSchema: {
+            chat: z.string().describe("Peer owning the story — usually 'me' or your own user id/@username"),
+            storyId: z.number().int().positive().describe("Story ID to fetch viewers for"),
+            q: z.string().optional().describe("Filter viewers by name substring"),
+            justContacts: z.boolean().optional().describe("Return only contacts"),
+            reactionsFirst: z.boolean().optional().describe("Sort viewers who reacted first"),
+            forwardsFirst: z.boolean().optional().describe("Sort forwards/reposts first"),
+            offset: z.string().optional().describe("Pagination offset from a previous response's nextOffset"),
+            limit: z.number().int().min(1).max(100).optional().describe("Max viewers to return (default 50, max 100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, storyId, q, justContacts, reactionsFirst, forwardsFirst, offset, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStoryViewsList(chat, {
+                id: storyId,
+                q,
+                justContacts,
+                reactionsFirst,
+                forwardsFirst,
+                offset,
+                limit,
+            });
+            return ok(sanitize(JSON.stringify(result)));
+        }
+        catch (e) {
+            const msg = e.message ?? "";
+            if (/PREMIUM|PAYMENT_REQUIRED/i.test(msg)) {
+                return fail(new Error("story view stats may require Telegram Premium"));
+            }
+            return fail(e);
+        }
+    });
+}

package/package.json

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