@overpod/mcp-telegram 1.25.0 → 1.26.1

package/dist/tools/messages.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function registerMessageTools(server, telegram) {
     server.registerTool("telegram-send-message", {
         description: "Send a message to a Telegram chat",
@@ -45,7 +45,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No messages");
+            return ok(text || "No messages");
         }
         catch (e) {
             return fail(e);
@@ -70,7 +70,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No messages found");
+            return ok(text || "No messages found");
         }
         catch (e) {
             return fail(e);
@@ -94,7 +94,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] [${m.chat.type === "channel" ? "C" : m.chat.type === "group" ? "G" : "P"} ${m.chat.name}${m.chat.username ? ` @${m.chat.username}` : ""}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No messages found");
+            return ok(text || "No messages found");
         }
         catch (e) {
             return fail(e);
@@ -185,7 +185,7 @@ export function registerMessageTools(server, telegram) {
                 return line;
             })
                 .join("\n");
-            return ok(sanitize(text) || "No unread chats");
+            return ok(text || "No unread chats");
         }
         catch (e) {
             return fail(e);
@@ -206,7 +206,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No scheduled messages");
+            return ok(text || "No scheduled messages");
         }
         catch (e) {
             return fail(e);
@@ -252,7 +252,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No replies");
+            return ok(text || "No replies");
         }
         catch (e) {
             return fail(e);
@@ -272,7 +272,7 @@ export function registerMessageTools(server, telegram) {
             return fail(new Error(err));
         try {
             const link = await telegram.getMessageLink(chatId, messageId, thread);
-            return ok(sanitize(link));
+            return ok(link);
         }
         catch (e) {
             return fail(e);
@@ -294,7 +294,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No unread mentions");
+            return ok(text || "No unread mentions");
         }
         catch (e) {
             return fail(e);
@@ -316,7 +316,7 @@ export function registerMessageTools(server, telegram) {
             const text = messages
                 .map((m) => `[#${m.id}] [${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}${formatReactions(m.reactions)}`)
                 .join("\n\n");
-            return ok(sanitize(text) || "No unread reactions");
+            return ok(text || "No unread reactions");
         }
         catch (e) {
             return fail(e);
@@ -346,7 +346,7 @@ export function registerMessageTools(server, telegram) {
             const text = translations.length === messageIds.length
                 ? translations.map((t, i) => `[#${messageIds[i]}] ${t}`).join("\n\n")
                 : translations.join("\n\n");
-            return ok(sanitize(text) || "No translations");
+            return ok(text || "No translations");
         }
         catch (e) {
             const msg = e.message ?? "";
@@ -394,4 +394,196 @@ export function registerMessageTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-inline-query", {
+        description: "Query an inline bot (like @gif, @bing) in a chat context and return the compact result list. Returns queryId, cacheTime, and results[{id,type,title?,description?,url?}]. The queryId is typically valid for ~60s and can be passed to telegram-inline-query-send to deliver a chosen result. Bot must be a real bot account",
+        inputSchema: {
+            bot: z.string().describe("Inline bot username (e.g. @gif) or numeric user ID"),
+            chatId: z.string().describe("Chat ID or username providing context for the inline query"),
+            query: z.string().describe("Query text the bot should resolve (may be empty string)"),
+            offset: z
+                .string()
+                .optional()
+                .describe("Pagination offset returned by a previous call as nextOffset (empty string on first call)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ bot, chatId, query, offset }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const res = await telegram.getInlineBotResults(bot, chatId, query, offset);
+            return ok(JSON.stringify(res));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-inline-query-send", {
+        description: "Send an inline bot result to a chat by queryId + resultId (as returned by telegram-inline-query). The queryId is valid for ~60s after the original query, so call this soon after telegram-inline-query. Returns the sent messageId (0 if not extractable from the update).",
+        inputSchema: {
+            chatId: z.string().describe("Target chat ID or username to send the result into"),
+            queryId: z
+                .string()
+                .regex(/^\d+$/, "queryId must be a numeric string")
+                .describe("queryId from a prior telegram-inline-query call (valid ~60s)"),
+            resultId: z.string().describe("id of the chosen result from telegram-inline-query results[]"),
+            replyTo: z.number().optional().describe("Message ID to reply to"),
+            silent: z.boolean().optional().describe("Send without notification"),
+            hideVia: z.boolean().optional().describe("Hide the 'via @bot' label on the sent message"),
+            clearDraft: z.boolean().optional().describe("Clear the chat draft after sending"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, queryId, resultId, replyTo, silent, hideVia, clearDraft }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { messageId } = await telegram.sendInlineBotResult(chatId, queryId, resultId, {
+                replyTo,
+                silent,
+                hideVia,
+                clearDraft,
+            });
+            const idInfo = messageId ? ` [#${messageId}]` : "";
+            return ok(`Inline result ${resultId} sent to ${chatId}${idInfo}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-message-buttons", {
+        description: "List the inline/reply keyboard buttons on a Telegram message with their (row, col) indices, type (e.g. KeyboardButtonCallback, KeyboardButtonUrl), label and type-specific fields (callback data as base64, url, switchQuery, userId, copyText, etc). Helper for telegram-press-button — call this first to discover indices and filter by type before pressing. Returns markupType='none' and empty buttons when the message has no keyboard",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username where the message lives"),
+            messageId: z.number().describe("Message ID whose keyboard to inspect"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMessageButtons(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-press-button", {
+        description: "Press an inline keyboard callback button on a message. Identify the button by (row, column) from its replyMarkup, or pass raw callback_data as base64. URL, switch-inline, game and 2FA-password buttons are rejected with a clear error. Returns the bot's callback answer: {alert?, hasUrl?, nativeUi?, message?, url?, cacheTime}",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username where the message lives"),
+            messageId: z.number().describe("Message ID whose inline button to press"),
+            row: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Button row index (0-based) — required unless data is provided"),
+            column: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Button column index (0-based) — required unless data is provided"),
+            data: z.string().optional().describe("Raw callback_data as base64 string (escape hatch — prefer row/column)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, row, column, data }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        const hasIndex = row !== undefined && column !== undefined;
+        if (!hasIndex && data === undefined) {
+            return fail(new Error("Provide either both row+column, or data (base64 callback_data)"));
+        }
+        if (hasIndex && data !== undefined) {
+            return fail(new Error("Provide either row+column OR data, not both"));
+        }
+        try {
+            const answer = await telegram.pressButton(chatId, messageId, {
+                buttonIndex: hasIndex ? { row: row, column: column } : undefined,
+                data,
+            });
+            return ok(JSON.stringify(answer));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-state", {
+        description: "Initialize the polling cursor by fetching the current Telegram updates state {pts, qts, date, seq, unreadCount}. Call once before telegram-get-updates; then persist {pts, qts, date} in your agent state and feed them into telegram-get-updates. The MCP server does NOT store the cursor — you do.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const state = await telegram.getUpdatesState();
+            return ok(JSON.stringify(state));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-updates", {
+        description: "Fetch new messages, deleted messages, and other updates since a previously-known {pts, qts, date} cursor (from telegram-get-state or a prior call). Returns compact newMessages[], deletedMessageIds[], otherUpdates[] (className only), and the new cursor state. isFinal=false means more updates are queued — call again with the returned state. If Telegram reports the gap is too long, a fallback hint is returned suggesting to resync via telegram-read-messages per chat. Cursor is stateless — the agent must persist {pts, qts, date} between calls.",
+        inputSchema: {
+            pts: z.number().int().describe("Last known pts (from telegram-get-state or prior telegram-get-updates)"),
+            qts: z.number().int().describe("Last known qts (secret-chat / encrypted stream cursor; 0 if unknown)"),
+            date: z.number().int().describe("Last known date (unix seconds from prior state)"),
+            ptsLimit: z
+                .number()
+                .int()
+                .positive()
+                .max(1000)
+                .optional()
+                .describe("Max updates per batch (default 100, capped at 1000)"),
+            ptsTotalLimit: z
+                .number()
+                .int()
+                .positive()
+                .max(1000)
+                .optional()
+                .describe("Max total updates across paginated slices (default 1000, capped at 1000)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ pts, qts, date, ptsLimit, ptsTotalLimit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const diff = await telegram.getUpdates({ pts, qts, date, ptsLimit, ptsTotalLimit });
+            return ok(JSON.stringify(diff));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-channel-updates", {
+        description: "Fetch new messages and updates for a single channel/supergroup since a known per-channel pts cursor. Separate from the global cursor used by telegram-get-updates. Returns compact newMessages[], otherUpdates[], and new {pts, isFinal, timeout?}. If the channel gap is too long, Telegram returns a dialog snapshot — this tool forwards it and hints to resync via telegram-read-messages. Cursor is stateless — the agent stores pts.",
+        inputSchema: {
+            chatId: z.string().describe("Channel or supergroup ID or username"),
+            pts: z.number().int().describe("Last known per-channel pts"),
+            limit: z.number().int().positive().optional().describe("Max updates per batch (default 100)"),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Force request updates even if the client hasn't processed previous ones (rarely needed)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, pts, limit, force }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const diff = await telegram.getChannelUpdates(chatId, { pts, limit, force });
+            return ok(JSON.stringify(diff));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/quick-replies.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 isQuickRepliesEnabled(): boolean;
+export declare function registerQuickRepliesTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/quick-replies.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection } from "./shared.js";
+export function isQuickRepliesEnabled() {
+    return process.env.MCP_TELEGRAM_ENABLE_QUICK_REPLIES === "1";
+}
+export function registerQuickRepliesTools(server, telegram) {
+    if (!isQuickRepliesEnabled())
+        return;
+    server.registerTool("telegram-get-quick-replies", {
+        description: "Fetch the list of quick-reply shortcuts configured for the user account (messages.GetQuickReplies). Each entry has {shortcutId, shortcut, topMessage, count} — use the shortcutId with telegram-get-quick-reply-messages to inspect the stored messages. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string and the server may respond with {notModified:true} if nothing changed. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.",
+        inputSchema: {
+            hash: z
+                .string()
+                .regex(/^\d+$/)
+                .optional()
+                .describe("Aggregate hash from a previous response (decimal string); omit for a fresh fetch"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ hash }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getQuickReplies(hash);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-quick-reply-messages", {
+        description: "Fetch messages stored under a quick-reply shortcut (messages.GetQuickReplyMessages). Use `shortcutId` from telegram-get-quick-replies. Optional `ids` narrows to specific message ids within the shortcut. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string — the server may respond with {notModified:true, count} if nothing changed. Returns compact {count, messages[{id, date, text, isService, fromId?, replyToMsgId?}]}. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.",
+        inputSchema: {
+            shortcutId: z.number().int().nonnegative().describe("Shortcut id from telegram-get-quick-replies"),
+            ids: z
+                .array(z.number().int().nonnegative())
+                .optional()
+                .describe("Optional list of message ids to fetch within the shortcut"),
+            hash: z
+                .string()
+                .regex(/^\d+$/)
+                .optional()
+                .describe("Aggregate hash from a previous response (decimal string); omit for a fresh fetch"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ shortcutId, ids, hash }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getQuickReplyMessages(shortcutId, { ids, hash });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/reactions.js

@@ -92,7 +92,50 @@ export function registerReactionTools(server, telegram) {
             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(" ")));
+            return ok(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);
@@ -112,7 +155,7 @@ export function registerReactionTools(server, telegram) {
             const reactions = await telegram.getRecentReactions(limit);
             if (reactions.length === 0)
                 return ok("No recent reactions");
-            return ok(sanitize(reactions.map((r) => r.emoji).join(" ")));
+            return ok(reactions.map((r) => r.emoji).join(" "));
         }
         catch (e) {
             return fail(e);

package/dist/tools/shared.d.ts

@@ -13,7 +13,9 @@ export declare const DESTRUCTIVE: {
     readonly destructiveHint: true;
     readonly openWorldHint: true;
 };
-/** Helper: success response */
+/** Remove unpaired UTF-16 surrogates that break JSON serialization */
+export declare function sanitize(text: string): string;
+/** Helper: success response — always sanitizes to prevent surrogate crashes */
 export declare function ok(text: string): {
     content: {
         type: "text";
@@ -28,8 +30,6 @@ export declare function fail(e: unknown): {
     }[];
     isError: true;
 };
-/** Remove unpaired UTF-16 surrogates that break JSON serialization */
-export declare function sanitize(text: string): string;
 /** Format reactions array into compact text like: [👍×5 ❤️×3(me) 🔥×1] */
 export declare function formatReactions(reactions?: {
     emoji: string;

package/dist/tools/shared.js

@@ -2,17 +2,18 @@
 export const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
 export const WRITE = { readOnlyHint: false, openWorldHint: true };
 export const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
-/** Helper: success response */
+/** Remove unpaired UTF-16 surrogates that break JSON serialization */
+export function sanitize(text) {
+    return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+}
+/** Helper: success response — always sanitizes to prevent surrogate crashes */
 export function ok(text) {
-    return { content: [{ type: "text", text }] };
+    return { content: [{ type: "text", text: sanitize(text) }] };
 }
 /** Helper: error response with isError flag */
 export function fail(e) {
-    return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
-}
-/** Remove unpaired UTF-16 surrogates that break JSON serialization */
-export function sanitize(text) {
-    return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+    const msg = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: "text", text: `Error: ${sanitize(msg)}` }], isError: true };
 }
 /** Format reactions array into compact text like: [👍×5 ❤️×3(me) 🔥×1] */
 export function formatReactions(reactions) {

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 } 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(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(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/stickers.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function registerStickerTools(server, telegram) {
     server.registerTool("telegram-get-sticker-set", {
         description: "Get all stickers from a sticker set by its short name. Returns each sticker with index and emoji. Use the index with telegram-send-sticker to send a specific sticker",
@@ -25,7 +25,7 @@ export function registerStickerTools(server, telegram) {
             }
             lines.push("");
             lines.push(`Send a sticker: telegram-send-sticker(chatId, stickerSet="${set.shortName}", index=N)`);
-            return ok(sanitize(lines.join("\n")));
+            return ok(lines.join("\n"));
         }
         catch (e) {
             return fail(e);
@@ -54,7 +54,7 @@ export function registerStickerTools(server, telegram) {
             }
             lines.push("");
             lines.push("Use telegram-get-sticker-set(shortName) to see individual stickers.");
-            return ok(sanitize(lines.join("\n")));
+            return ok(lines.join("\n"));
         }
         catch (e) {
             return fail(e);
@@ -79,7 +79,7 @@ export function registerStickerTools(server, telegram) {
                 lines.push(`• ${set.title} — ${set.count} stickers`);
                 lines.push(`  Short name: ${set.shortName}`);
             }
-            return ok(sanitize(lines.join("\n")));
+            return ok(lines.join("\n"));
         }
         catch (e) {
             return fail(e);
@@ -128,7 +128,7 @@ export function registerStickerTools(server, telegram) {
             for (let i = 0; i < stickers.length; i++) {
                 lines.push(`[${i}] ${stickers[i].emoji}`);
             }
-            return ok(sanitize(lines.join("\n")));
+            return ok(lines.join("\n"));
         }
         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;