@overpod/mcp-telegram 1.28.1 → 1.33.0

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())

package/dist/tools/stories.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection } from "./shared.js";
+import { ABSOLUTE_PATH_ERROR, DESTRUCTIVE, fail, isSafeAbsolutePath, ok, READ_ONLY, requireConnection, sanitizeInputText, WRITE, } from "./shared.js";
+const absolutePath = z.string().refine(isSafeAbsolutePath, { message: ABSOLUTE_PATH_ERROR });
+const safeText = z.string().transform(sanitizeInputText);
 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.",
@@ -104,4 +106,304 @@ export function registerStoryTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-send-story", {
+        description: "Publish a new story (photo or video) to your profile or a channel you manage. Privacy: everyone/contacts/close_friends/selected (allowUserIds required for 'selected'). MediaAreas not supported in this version.",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer to post the story to — 'me', @username, or numeric ID"),
+            filePath: absolutePath.describe("Absolute path to the photo or video file to upload"),
+            type: z.enum(["photo", "video"]).optional().describe("Override auto-detected media type"),
+            caption: safeText.pipe(z.string().max(2048)).optional().describe("Story caption (max 2048 chars)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption parse mode: md or html"),
+            privacy: z
+                .enum(["everyone", "contacts", "close_friends", "selected"])
+                .default("everyone")
+                .describe("Who can see the story"),
+            allowUserIds: z
+                .array(z.string().regex(/^\d{1,19}$/, "must be a numeric Telegram user ID"))
+                .optional()
+                .describe("Required when privacy='selected': numeric user IDs allowed to see the story"),
+            disallowUserIds: z
+                .array(z.string().regex(/^\d{1,19}$/, "must be a numeric Telegram user ID"))
+                .optional()
+                .describe("User IDs explicitly blocked from seeing the story (ignored for privacy='selected')"),
+            period: z
+                .union([z.literal(21600), z.literal(43200), z.literal(86400), z.literal(172800)])
+                .optional()
+                .describe("Story lifetime in seconds: 21600=6h, 43200=12h, 86400=24h (default), 172800=48h"),
+            pinned: z.boolean().optional().describe("Keep the story in the profile highlights after expiry"),
+            noforwards: z.boolean().optional().describe("Prevent others from forwarding or saving the story"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, type, caption, parseMode, privacy, allowUserIds, disallowUserIds, period, pinned, noforwards, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (privacy === "selected" && !allowUserIds?.length) {
+            return fail(new Error("privacy='selected' requires at least one user ID in allowUserIds"));
+        }
+        try {
+            const result = await telegram.sendStory(chatId, filePath, {
+                type,
+                caption,
+                parseMode,
+                privacy,
+                allowUserIds,
+                disallowUserIds,
+                period,
+                pinned,
+                noforwards,
+            });
+            const idInfo = result.id ? ` [#${result.id}]` : "";
+            return ok(`Story published to ${chatId}${idInfo} (expires in ${result.period}s)`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-story", {
+        description: "Edit an existing story: replace media, update caption ('' clears it), or change privacy rules.",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer owning the story"),
+            storyId: z.number().int().positive().describe("ID of the story to edit"),
+            filePath: absolutePath.optional().describe("Absolute path to replacement media"),
+            type: z.enum(["photo", "video"]).optional().describe("Override auto-detected media type for new file"),
+            caption: safeText.pipe(z.string().max(2048)).optional().describe("New caption; pass '' to clear"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption parse mode"),
+            privacy: z
+                .enum(["everyone", "contacts", "close_friends", "selected"])
+                .optional()
+                .describe("New privacy setting"),
+            allowUserIds: z
+                .array(z.string().regex(/^\d{1,19}$/, "must be a numeric Telegram user ID"))
+                .optional()
+                .describe("Required when privacy='selected'"),
+            disallowUserIds: z
+                .array(z.string().regex(/^\d{1,19}$/, "must be a numeric Telegram user ID"))
+                .optional()
+                .describe("Blocked user IDs (ignored for 'selected')"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, storyId, filePath, type, caption, parseMode, privacy, allowUserIds, disallowUserIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (filePath === undefined && caption === undefined && privacy === undefined) {
+            return fail(new Error("At least one field (filePath, caption, or privacy) must be provided"));
+        }
+        if (privacy === "selected" && !allowUserIds?.length) {
+            return fail(new Error("privacy='selected' requires at least one user ID in allowUserIds"));
+        }
+        try {
+            const result = await telegram.editStory(chatId, storyId, {
+                filePath,
+                type,
+                caption,
+                parseMode,
+                privacy,
+                allowUserIds,
+                disallowUserIds,
+            });
+            return ok(`Story #${storyId} edited (${result.changed.join(", ")})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-stories", {
+        description: "Delete one or more of your own stories. This action is irreversible and requires confirm:true.",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer owning the stories"),
+            ids: z.array(z.number().int().positive()).min(1).max(100).describe("Story IDs to delete (1–100 per request)"),
+            confirm: z.literal(true).describe("Pass true to confirm irreversible deletion"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, ids, confirm: _confirm }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.deleteStories(chatId, ids);
+            const { deleted } = result;
+            return ok(`Deleted ${deleted.length} stor${deleted.length === 1 ? "y" : "ies"}: [${deleted.join(", ")}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-react-to-story", {
+        description: "React to a story with an emoji, or remove the current reaction by passing ''.",
+        inputSchema: {
+            chatId: z.string().describe("Peer who posted the story"),
+            storyId: z.number().int().positive().describe("Story ID to react to"),
+            emoji: z.string().max(8).describe("Reaction emoji. Empty string '' removes the reaction."),
+            addToRecent: z.boolean().optional().describe("Add emoji to your recently used reactions"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, storyId, emoji, addToRecent }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendStoryReaction(chatId, storyId, emoji, addToRecent);
+            return ok(emoji === "" ? `Removed reaction from story #${storyId}` : `Reacted ${emoji} to story #${storyId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-export-story-link", {
+        description: "Get a shareable t.me/… URL for a public story.",
+        inputSchema: {
+            chatId: z.string().describe("Peer who posted the story"),
+            storyId: z.number().int().positive().describe("Story ID to get the link for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, storyId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.exportStoryLink(chatId, storyId);
+            return ok(result.link);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-read-stories", {
+        description: "Mark stories as seen up to a given story ID (maxId, inclusive).",
+        inputSchema: {
+            chatId: z.string().describe("Peer whose stories to mark as seen"),
+            maxId: z.number().int().positive().describe("Stories up to and including this ID will be marked seen"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, maxId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.readStories(chatId, maxId);
+            return ok(`Marked stories as read up to #${maxId} (${result.ids.length} newly seen)`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-story-pinned", {
+        description: "Pin or unpin stories in your profile highlights (Telegram allows up to 3 pinned stories).",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer owning the stories"),
+            ids: z.array(z.number().int().positive()).min(1).max(100).describe("Story IDs to pin or unpin"),
+            pinned: z.boolean().describe("true to pin, false to unpin"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, ids, pinned }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.toggleStoryPinned(chatId, ids, pinned);
+            const { affected } = result;
+            return ok(`${pinned ? "Pinned" : "Unpinned"} ${affected.length} stor${affected.length === 1 ? "y" : "ies"}: [${affected.join(", ")}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-story-pinned-to-top", {
+        description: "Pin stories to the very top of your pinned row. Pass an empty array [] to clear all top-pinned stories.",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer owning the stories"),
+            ids: z
+                .array(z.number().int().positive())
+                .max(100)
+                .describe("Story IDs to pin to the top row; pass [] to clear"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, ids }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.toggleStoryPinnedToTop(chatId, ids);
+            return ok(ids.length === 0
+                ? "Cleared top-pinned stories"
+                : `Pinned ${ids.length} stor${ids.length === 1 ? "y" : "ies"} to top: [${ids.join(", ")}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-activate-stealth-mode", {
+        description: "Hide your story views retroactively (past=true) and/or for the next 25 minutes (future=true). Requires Telegram Premium — non-Premium accounts receive PREMIUM_ACCOUNT_REQUIRED.",
+        inputSchema: {
+            past: z.boolean().optional().describe("Remove your views from stories you already watched"),
+            future: z.boolean().optional().describe("Hide your views for the next 25 minutes"),
+        },
+        annotations: WRITE,
+    }, async ({ past, future }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!past && !future) {
+            return fail(new Error("At least one of past or future must be true"));
+        }
+        try {
+            await telegram.activateStealthMode(past, future);
+            return ok(`Stealth mode activated (past: ${past ?? false}, future: ${future ?? false})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stories-archive", {
+        description: "Fetch auto-archived (expired) stories from a peer's archive. Paginate via offsetId (pass last story id from previous page).",
+        inputSchema: {
+            chatId: z.string().default("me").describe("Peer whose archive to fetch"),
+            offsetId: z
+                .number()
+                .int()
+                .nonnegative()
+                .default(0)
+                .describe("Pagination offset: pass last story ID from previous page (0 to start)"),
+            limit: z.number().int().min(1).max(100).default(50).describe("Max stories to return (1–100, default 50)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, offsetId, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStoriesArchive(chatId, offsetId, limit);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-report-story", {
+        description: "Report a story via the multi-step option flow. First call with option:'' starts the flow; subsequent calls pass the base64 option bytes from the previous response.",
+        inputSchema: {
+            chatId: z.string().describe("Peer who posted the story"),
+            ids: z.array(z.number().int().positive()).min(1).max(100).describe("Story IDs to report"),
+            option: z
+                .string()
+                .max(128)
+                .default("")
+                .describe("Base64-encoded option bytes from a prior report step, or empty string to start the flow"),
+            message: safeText.pipe(z.string().max(1024)).default("").describe("Optional message to accompany the report"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, ids, option, message }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.reportStory(chatId, ids, option, message);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

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

package/dist/tools/transcribe.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+export function registerTranscribeTools(server, telegram) {
+    server.registerTool("telegram-transcribe-audio", {
+        description: "Request server-side transcription of a voice note or video note (Telegram Premium feature). Returns immediately with transcriptionId — if pending:true, call telegram-get-transcription to poll for completion.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the voice or video note"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.transcribeAudio(chatId, messageId);
+            const trialInfo = result.trialRemainsNum !== undefined
+                ? `\nTrial remaining: ${result.trialRemainsNum} free transcription(s)`
+                : "";
+            if (result.pending) {
+                return ok(`Transcription started for message #${messageId}\nTranscriptionId: ${result.transcriptionId}\nStatus: pending${trialInfo}`);
+            }
+            return ok(`Transcription for message #${messageId}:\nTranscriptionId: ${result.transcriptionId}\nStatus: complete\n\n${result.text}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-transcription", {
+        description: "Poll for updated transcription result. Calls the same endpoint as telegram-transcribe-audio — Telegram guarantees idempotency (returns same transcriptionId with updated text once processing completes).",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the voice or video note"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.transcribeAudio(chatId, messageId);
+            const trialInfo = result.trialRemainsNum !== undefined
+                ? `\nTrial remaining: ${result.trialRemainsNum} free transcription(s)`
+                : "";
+            if (result.pending) {
+                return ok(`Transcription started for message #${messageId}\nTranscriptionId: ${result.transcriptionId}\nStatus: pending${trialInfo}`);
+            }
+            return ok(`Transcription for message #${messageId}:\nTranscriptionId: ${result.transcriptionId}\nStatus: complete\n\n${result.text}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-rate-transcription", {
+        description: "Rate transcription quality (good/poor) to improve Telegram speech-to-text.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the voice or video note"),
+            transcriptionId: z.string().describe("Transcription ID returned by telegram-transcribe-audio"),
+            good: z.boolean().describe("true = good quality, false = poor quality"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, transcriptionId, good }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.rateTranscription(chatId, messageId, transcriptionId, good);
+            return ok(`Rated transcription ${transcriptionId} for message #${messageId} as ${good ? "good" : "poor"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/package.json

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