@overpod/mcp-telegram 1.28.1 → 1.32.0

package/dist/tools/reactions.js

@@ -161,4 +161,66 @@ export function registerReactionTools(server, telegram) {
             return fail(e);
         }
     });
+    // ─── Paid reactions ────────────────────────────────────────────────────────
+    server.registerTool("telegram-send-paid-reaction", {
+        description: "Send a paid reaction (★ Stars) on a channel post. Stars are spent from your balance. Optional private flag controls leaderboard visibility.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID of the channel post"),
+            count: z.number().int().min(1).max(2500).default(1).describe("Number of Stars to send (1-2500)"),
+            private: z
+                .boolean()
+                .optional()
+                .describe("true = anonymous on leaderboard, false = show name, omit = use account default"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, count, private: privateFlag }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendPaidReaction(chatId, messageId, count, { private: privateFlag });
+            const privacy = privateFlag === true ? " (anonymous)" : privateFlag === false ? " (public)" : "";
+            return ok(`Sent ★×${count} paid reaction to message #${messageId} in ${chatId}${privacy}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-paid-reaction-privacy", {
+        description: "Change leaderboard visibility of your paid reaction on a specific channel post (Layer 198 API).",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID of the channel post"),
+            private: z.boolean().describe("true = anonymous on leaderboard, false = show name"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, private: privateFlag }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.togglePaidReactionPrivacy(chatId, messageId, privateFlag);
+            return ok(`Updated paid reaction privacy on message #${messageId} in ${chatId}: ${privateFlag ? "anonymous" : "show name"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-paid-reaction-privacy", {
+        description: "Get your current default paid reaction privacy setting.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPaidReactionPrivacy();
+            return ok(`Default paid reaction privacy: ${result.private ? "anonymous" : "show name"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

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

package/dist/tools/send-media.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { ABSOLUTE_PATH_ERROR, fail, isSafeAbsolutePath, ok, requireConnection, sanitizeInputText, WRITE, } from "./shared.js";
+const absolutePath = z.string().min(1).refine(isSafeAbsolutePath, ABSOLUTE_PATH_ERROR);
+const safeText = z.string().transform(sanitizeInputText);
+const DICE_EMOJIS = ["🎲", "🎯", "🎰", "🏀", "⚽", "🎳"];
+export function registerSendMediaTools(server, telegram) {
+    server.registerTool("telegram-send-voice", {
+        description: "Send a voice note (audio recording) to a Telegram chat. Shows as a voice message with waveform UI.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (e.g. @username or numeric ID)"),
+            filePath: absolutePath.describe("Absolute local filesystem path to audio file (OGG/Opus preferred; M4A/MP3 also accepted). URLs are rejected."),
+            caption: safeText.optional().describe("Optional caption shown below the voice note"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID (for groups with Topics enabled)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption format: md (Markdown) or html"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, caption, replyTo, topicId, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVoice(chatId, filePath, {
+                caption,
+                replyTo,
+                topicId,
+                parseMode,
+            });
+            return ok(`Voice note sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-video-note", {
+        description: "Send a video note (round-shaped short video) to a Telegram chat. Shows as a circular video in the UI.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            filePath: absolutePath.describe("Absolute local filesystem path to video file (MP4 preferred, square source recommended for best look). URLs are rejected."),
+            duration: z.number().int().positive().max(60).optional().describe("Duration in seconds (Telegram caps at 60)"),
+            length: z
+                .number()
+                .int()
+                .positive()
+                .max(640)
+                .optional()
+                .describe("Frame edge length in pixels (the circle is square-cropped)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, duration, length, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVideoNote(chatId, filePath, {
+                duration,
+                length,
+                replyTo,
+                topicId,
+            });
+            return ok(`Video note sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-contact", {
+        description: "Send a contact card (phone number + name) to a Telegram chat.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            phone: z
+                .string()
+                .regex(/^\+?\d{6,15}$/)
+                .describe("Phone number in E.164-like format — 6-15 digits, optional leading +. " +
+                "Note: sent as-is; Telegram shows the number to the recipient."),
+            firstName: safeText.pipe(z.string().min(1).max(64)).describe("Contact first name"),
+            lastName: safeText.pipe(z.string().max(64)).optional().describe("Contact last name"),
+            vcard: safeText.pipe(z.string().max(2048)).optional().describe("Optional vCard v3.0 text content"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, phone, firstName, lastName, vcard, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendContact(chatId, phone, firstName, {
+                lastName,
+                vcard,
+                replyTo,
+                topicId,
+            });
+            return ok(`Contact sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-dice", {
+        description: "Send an animated dice/game emoji to a Telegram chat. Returns the server-rolled value — useful for games, " +
+            "coin-flips, random picks. Values: 🎲🎯🎳 = 1-6, 🏀⚽ = 1-5, 🎰 = slot combo 1-64.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            emoji: z
+                .enum(DICE_EMOJIS)
+                .default("🎲")
+                .describe("Dice emoji: 🎲 dice (1-6), 🎯 dart (1-6), 🎰 slot machine (1-64), 🏀 basketball (1-5), ⚽ football (1-5), 🎳 bowling (1-6)"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, emoji, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id, value } = await telegram.sendDice(chatId, emoji, { replyTo, topicId });
+            const rolled = value !== undefined ? `: rolled ${value}` : " (value pending)";
+            return ok(`Dice ${emoji} sent to ${chatId}${rolled} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-location", {
+        description: "Send a geographic location to a Telegram chat. Static pin by default; set livePeriod to share a live-updating location for N seconds.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            latitude: z.number().min(-90).max(90).describe("Latitude in decimal degrees (-90 to 90)"),
+            longitude: z.number().min(-180).max(180).describe("Longitude in decimal degrees (-180 to 180)"),
+            accuracyRadius: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Horizontal accuracy radius in meters (0 = unknown)"),
+            livePeriod: z
+                .number()
+                .int()
+                .min(60)
+                .max(86400)
+                .optional()
+                .describe("If set, sends a live location updated for N seconds (60-86400). Omit for static pin."),
+            heading: z
+                .number()
+                .int()
+                .min(1)
+                .max(360)
+                .optional()
+                .describe("Direction the user is heading, 1-360 degrees (meaningful only for live locations)"),
+            proximityRadius: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Alert radius for proximity notification in meters (live only)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, latitude, longitude, accuracyRadius, livePeriod, heading, proximityRadius, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendLocation(chatId, latitude, longitude, {
+                accuracyRadius,
+                livePeriod,
+                heading,
+                proximityRadius,
+                replyTo,
+                topicId,
+            });
+            const label = livePeriod ? `Live location sent to ${chatId} for ${livePeriod}s` : `Location sent to ${chatId}`;
+            return ok(`${label} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-venue", {
+        description: "Send a venue card (point-of-interest with title and address) to a Telegram chat.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            latitude: z.number().min(-90).max(90).describe("Venue latitude"),
+            longitude: z.number().min(-180).max(180).describe("Venue longitude"),
+            title: safeText.pipe(z.string().min(1).max(256)).describe("Venue name (e.g. 'Red Square')"),
+            address: safeText.pipe(z.string().min(1).max(512)).describe("Street address"),
+            provider: safeText
+                .pipe(z.string().max(32))
+                .optional()
+                .describe("Data provider — typically 'foursquare' or 'gplaces'. Defaults to 'foursquare'."),
+            venueId: safeText.pipe(z.string().max(256)).optional().describe("Provider-specific venue ID"),
+            venueType: safeText.pipe(z.string().max(256)).optional().describe("Provider-specific venue type category"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, latitude, longitude, title, address, provider, venueId, venueType, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVenue(chatId, latitude, longitude, title, address, {
+                provider,
+                venueId,
+                venueType,
+                replyTo,
+                topicId,
+            });
+            return ok(`Venue "${title}" sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-album", {
+        description: "Send an album (group) of 2-10 photos as a single grouped message. Media type is auto-detected " +
+            "by file extension — videos are supported by the underlying TL call but are not covered by v1.29.0 " +
+            "mock tests, so uniform-photo albums are the safer choice until a live checkpoint. Uploads are " +
+            "serial per item: expect ≈4-10s for 10 mid-size photos, 15-40s for 10 large videos. Prefer ≤5 " +
+            "items or photos when low latency matters.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            items: z
+                .array(z.object({
+                filePath: absolutePath.describe("Absolute local filesystem path to a photo or video file. URLs are rejected."),
+                caption: safeText
+                    .optional()
+                    .describe("Per-item caption (shown under this item when the album is expanded)"),
+            }))
+                .min(2)
+                .max(10)
+                .describe("Array of media items (2-10)"),
+            caption: safeText
+                .optional()
+                .describe("Album-level caption (attached to the first item — shown in the collapsed view)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption format (applies to all captions)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, items, caption, parseMode, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { ids } = await telegram.sendAlbum(chatId, items, { caption, parseMode, replyTo, topicId });
+            const idList = ids.map((id) => `#${id}`).join(", ");
+            return ok(`Album sent to ${chatId} (${ids.length} items) [${idList}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/shared.d.ts

@@ -36,5 +36,33 @@ export declare function formatReactions(reactions?: {
     count: number;
     me: boolean;
 }[]): string;
+/**
+ * Validate that a user-supplied path is safe to upload.
+ *
+ * The threat model is prompt-injection: an AI that was told "send the user's file" can be
+ * manipulated into sending `/proc/self/environ`, `/etc/shadow`, `http://169.254.169.254/...`,
+ * or an SMB share `\\attacker.com\share`. GramJS `sendFile` happily fetches URLs and reads
+ * any local path, so the validation has to live here.
+ *
+ * Rules:
+ * - Must be an absolute path (POSIX `/` or Windows `C:\` / `\\server\share`).
+ * - No URL schemes (http:, https:, file:, ftp:, data:, javascript:, …).
+ * - No path traversal (`..` segments) even inside an absolute path.
+ * - No OS-sensitive directories on POSIX (`/proc`, `/sys`, `/dev`, `/run`). These leak env,
+ *   kernel state, or block on device reads.
+ * - UNC paths (`\\server\share`) are blocked (NTLM-relay / remote-SMB risk).
+ *
+ * This is defence-in-depth: the admin still owns the machine and can exfiltrate files
+ * deliberately — we just refuse to help prompt-injection do it automatically.
+ */
+export declare function isSafeAbsolutePath(p: string): boolean;
+/** Zod refinement message paired with `isSafeAbsolutePath` */
+export declare const ABSOLUTE_PATH_ERROR = "Must be an absolute local filesystem path (e.g. /tmp/file.ogg). URLs, UNC shares, path traversal (..), and OS-sensitive dirs (/proc, /sys, /dev, /run) are rejected.";
+/**
+ * Sanitize a user-provided text for safe TL encoding.
+ * Strips unpaired UTF-16 surrogates that crash GramJS's wire serializer. Use on every
+ * free-text field that reaches GramJS (captions, provider names, venue titles, quoteText, …).
+ */
+export declare function sanitizeInputText(text: string): string;
 /** Try to connect, return error text if failed */
 export declare function requireConnection(telegram: TelegramService): Promise<string | null>;

package/dist/tools/shared.js

@@ -22,6 +22,65 @@ export function formatReactions(reactions) {
     const parts = reactions.map((r) => `${r.emoji}×${r.count}${r.me ? "(me)" : ""}`);
     return ` [${parts.join(" ")}]`;
 }
+/**
+ * Validate that a user-supplied path is safe to upload.
+ *
+ * The threat model is prompt-injection: an AI that was told "send the user's file" can be
+ * manipulated into sending `/proc/self/environ`, `/etc/shadow`, `http://169.254.169.254/...`,
+ * or an SMB share `\\attacker.com\share`. GramJS `sendFile` happily fetches URLs and reads
+ * any local path, so the validation has to live here.
+ *
+ * Rules:
+ * - Must be an absolute path (POSIX `/` or Windows `C:\` / `\\server\share`).
+ * - No URL schemes (http:, https:, file:, ftp:, data:, javascript:, …).
+ * - No path traversal (`..` segments) even inside an absolute path.
+ * - No OS-sensitive directories on POSIX (`/proc`, `/sys`, `/dev`, `/run`). These leak env,
+ *   kernel state, or block on device reads.
+ * - UNC paths (`\\server\share`) are blocked (NTLM-relay / remote-SMB risk).
+ *
+ * This is defence-in-depth: the admin still owns the machine and can exfiltrate files
+ * deliberately — we just refuse to help prompt-injection do it automatically.
+ */
+export function isSafeAbsolutePath(p) {
+    if (typeof p !== "string" || p.length < 2)
+        return false;
+    // Reject embedded NUL — Node fs rejects it too, but we want an earlier, clearer failure
+    if (p.includes("\0"))
+        return false;
+    // Reject URL schemes outright (scheme://... or scheme:...)
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(p))
+        return false;
+    if (/^(file|data|javascript|http|https|ftp|ftps|ws|wss):/i.test(p))
+        return false;
+    // Reject Windows UNC shares — SMB SSRF / NTLM relay primitive
+    if (p.startsWith("\\\\") || p.startsWith("//"))
+        return false;
+    // Reject path-traversal segments anywhere in the path
+    const parts = p.split(/[\\/]+/);
+    if (parts.some((seg) => seg === ".."))
+        return false;
+    // POSIX absolute path
+    if (p.startsWith("/")) {
+        // Reject kernel / device / runtime pseudo-filesystems
+        if (/^\/(proc|sys|dev|run)(\/|$)/.test(p))
+            return false;
+        return true;
+    }
+    // Windows absolute path (C:\ or C:/), no UNC (already rejected above)
+    if (/^[a-zA-Z]:[\\/]/.test(p))
+        return true;
+    return false;
+}
+/** Zod refinement message paired with `isSafeAbsolutePath` */
+export const ABSOLUTE_PATH_ERROR = "Must be an absolute local filesystem path (e.g. /tmp/file.ogg). URLs, UNC shares, path traversal (..), and OS-sensitive dirs (/proc, /sys, /dev, /run) are rejected.";
+/**
+ * Sanitize a user-provided text for safe TL encoding.
+ * Strips unpaired UTF-16 surrogates that crash GramJS's wire serializer. Use on every
+ * free-text field that reaches GramJS (captions, provider names, venue titles, quoteText, …).
+ */
+export function sanitizeInputText(text) {
+    return sanitize(text);
+}
 /** Try to connect, return error text if failed */
 export async function requireConnection(telegram) {
     if (await telegram.ensureConnected())