@overpod/mcp-telegram 1.28.1 → 1.32.0

package/dist/telegram-helpers.d.ts

@@ -1,5 +1,26 @@
-import type bigInt from "big-integer";
+import bigInt from "big-integer";
 import { Api } from "telegram/tl/index.js";
+/**
+ * Build an InputReplyToMessage from optional replyTo / topicId, matching the shape used by
+ * raw messages.SendMedia. Returns undefined when neither is set so the caller can spread-omit it.
+ */
+export declare function buildReplyTo(replyTo?: number, topicId?: number): Api.InputReplyToMessage | undefined;
+/** Cryptographically random 64-bit bigInt for TL randomId (SendMedia/SendMultiMedia require it). */
+export declare function generateRandomBigInt(): bigInt.BigInteger;
+/**
+ * Extract the server-assigned message ID from an Updates envelope returned by SendMedia/SendMessage.
+ * Prefers UpdateMessageID (authoritative for SendMedia), falls back to UpdateNewMessage /
+ * UpdateNewChannelMessage for safety. Returns undefined when no ID is found.
+ */
+export declare function extractMessageId(result: Api.TypeUpdates | Api.Message | Api.UpdateShortSentMessage | undefined): number | undefined;
+/**
+ * Extract the MessageMediaDice value and captured message ID from a SendMedia dice envelope.
+ * Value is only present in UpdateNewMessage/UpdateNewChannelMessage; UpdateMessageID carries the ID only.
+ */
+export declare function extractDiceResult(result: Api.TypeUpdates | undefined): {
+    id: number;
+    value?: number;
+} | undefined;
 export declare function describeAdminLogAction(action: Api.TypeChannelAdminLogEventAction): string;
 export declare function describeAdminLogDetails(action: Api.TypeChannelAdminLogEventAction, describeUser: (userId: bigInt.BigInteger) => string): string;
 export declare function reactionToEmoji(reaction: Api.TypeReaction): string | null;
@@ -467,4 +488,93 @@ export declare function summarizePeerStories(ps: Api.TypePeerStories): PeerStori
 export declare function summarizeStoriesById(result: Api.stories.TypeStories): StoriesByIdSummary;
 export declare function summarizeStoryView(view: Api.TypeStoryView): StoryViewSummary;
 export declare function summarizeStoryViewsList(result: Api.stories.TypeStoryViewsList): StoryViewsListSummary;
+export type StoryPrivacy = "everyone" | "contacts" | "close_friends" | "selected";
+export declare function detectMediaType(filePath: string): "photo" | "video";
+export declare function buildStoryPrivacyRules(privacy: StoryPrivacy, allowUserIds?: string[], disallowUserIds?: string[]): Api.TypeInputPrivacyRule[];
+export declare function extractStoryIdFromUpdates(result: Api.TypeUpdates | undefined): number;
+export type DiscussionMessageSummary = {
+    discussionGroupId: string;
+    discussionMsgId: number;
+    unreadCount: number;
+    readInboxMaxId?: number;
+    readOutboxMaxId?: number;
+    topMessage?: {
+        id: number;
+        text?: string;
+        date: number;
+    };
+};
+export declare function summarizeDiscussionMessage(result: Api.messages.DiscussionMessage): DiscussionMessageSummary;
+export type GroupsForDiscussionSummary = {
+    groups: Array<{
+        id: string;
+        title: string;
+        username?: string;
+        participantsCount?: number;
+    }>;
+};
+export declare function summarizeGroupsForDiscussion(result: Api.messages.TypeChats): GroupsForDiscussionSummary;
+export type ReadParticipantsSummary = {
+    messageId: number;
+    readers: Array<{
+        userId: string;
+        readAt: string;
+    }>;
+    count: number;
+};
+export declare function summarizeReadParticipants(list: Api.TypeReadParticipantDate[], messageId: number): ReadParticipantsSummary;
+export type ReportResultSummary = {
+    kind: "reported";
+} | {
+    kind: "chooseOption";
+    title?: string;
+    options: Array<{
+        text: string;
+        option: string;
+    }>;
+} | {
+    kind: "addComment";
+    optional?: boolean;
+};
+export declare function summarizeReportResult(result: Api.TypeReportResult): ReportResultSummary;
+export type PollSummary = {
+    question: string;
+    isClosed: boolean;
+    isQuiz: boolean;
+    isMulti: boolean;
+    totalVoters: number;
+    options: Array<{
+        index: number;
+        text: string;
+        votes: number;
+        percent: number;
+        chosen: boolean;
+        correct?: boolean;
+    }>;
+};
+export declare function summarizePoll(poll: Api.Poll, results?: Api.PollResults): PollSummary;
+export declare function extractPollMediaFromUpdates(updates: Api.TypeUpdates): {
+    poll: Api.Poll;
+    results?: Api.PollResults;
+} | null;
+export declare function extractPeerId(peer: Api.TypePeer): string;
+export type EmojiStatusSummary = {
+    kind: "default" | "collectible" | "empty";
+    documentId?: string;
+    collectibleId?: string;
+    until?: number;
+    title?: string;
+    slug?: string;
+};
+export declare function summarizeEmojiStatus(s: Api.TypeEmojiStatus): EmojiStatusSummary;
+export type PeerSummary = {
+    id: string;
+    type: "user" | "chat" | "channel";
+};
+export declare function summarizePeer(peer: Api.TypePeer): PeerSummary;
+export type ResolvedBusinessChatLinkSummary = {
+    peer: PeerSummary;
+    message: string;
+    entityCount: number;
+};
 export declare function summarizeAllStories(result: Api.stories.TypeAllStories): AllStoriesSummary;

package/dist/telegram-helpers.js

@@ -1,4 +1,77 @@
+import { randomBytes } from "node:crypto";
+import bigInt from "big-integer";
 import { Api } from "telegram/tl/index.js";
+/**
+ * Build an InputReplyToMessage from optional replyTo / topicId, matching the shape used by
+ * raw messages.SendMedia. Returns undefined when neither is set so the caller can spread-omit it.
+ */
+export function buildReplyTo(replyTo, topicId) {
+    if (!replyTo && !topicId)
+        return undefined;
+    // Telegram expects replyToMsgId to equal topicId when replying to the topic root
+    // (posting into a topic without quoting a specific message inside it).
+    return new Api.InputReplyToMessage({
+        replyToMsgId: (replyTo ?? topicId),
+        topMsgId: topicId,
+    });
+}
+/** Cryptographically random 64-bit bigInt for TL randomId (SendMedia/SendMultiMedia require it). */
+export function generateRandomBigInt() {
+    return bigInt(randomBytes(8).toString("hex"), 16);
+}
+/**
+ * Extract the server-assigned message ID from an Updates envelope returned by SendMedia/SendMessage.
+ * Prefers UpdateMessageID (authoritative for SendMedia), falls back to UpdateNewMessage /
+ * UpdateNewChannelMessage for safety. Returns undefined when no ID is found.
+ */
+export function extractMessageId(result) {
+    if (!result)
+        return undefined;
+    if (result instanceof Api.Message)
+        return result.id;
+    if (result instanceof Api.UpdateShortSentMessage)
+        return result.id;
+    if (result instanceof Api.Updates || result instanceof Api.UpdatesCombined) {
+        for (const u of result.updates) {
+            if (u instanceof Api.UpdateMessageID)
+                return u.id;
+        }
+        for (const u of result.updates) {
+            if (u instanceof Api.UpdateNewMessage || u instanceof Api.UpdateNewChannelMessage) {
+                if (u.message instanceof Api.Message)
+                    return u.message.id;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract the MessageMediaDice value and captured message ID from a SendMedia dice envelope.
+ * Value is only present in UpdateNewMessage/UpdateNewChannelMessage; UpdateMessageID carries the ID only.
+ */
+export function extractDiceResult(result) {
+    if (!result)
+        return undefined;
+    if (!(result instanceof Api.Updates) && !(result instanceof Api.UpdatesCombined))
+        return undefined;
+    let id;
+    let value;
+    for (const u of result.updates) {
+        if (u instanceof Api.UpdateMessageID && id === undefined)
+            id = u.id;
+        if (u instanceof Api.UpdateNewMessage || u instanceof Api.UpdateNewChannelMessage) {
+            if (u.message instanceof Api.Message) {
+                if (id === undefined)
+                    id = u.message.id;
+                if (u.message.media instanceof Api.MessageMediaDice)
+                    value = u.message.media.value;
+            }
+        }
+    }
+    if (id === undefined)
+        return undefined;
+    return { id, value };
+}
 export function describeAdminLogAction(action) {
     const prefix = "ChannelAdminLogEventAction";
     const raw = action.className.startsWith(prefix) ? action.className.slice(prefix.length) : action.className;
@@ -840,6 +913,203 @@ export function summarizeStoryViewsList(result) {
         nextOffset: list.nextOffset,
     };
 }
+export function detectMediaType(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop() ?? "";
+    if (["jpg", "jpeg", "png", "webp", "heic", "heif"].includes(ext))
+        return "photo";
+    return "video";
+}
+export function buildStoryPrivacyRules(privacy, allowUserIds, disallowUserIds) {
+    const rules = [];
+    switch (privacy) {
+        case "everyone":
+            rules.push(new Api.InputPrivacyValueAllowAll());
+            break;
+        case "contacts":
+            rules.push(new Api.InputPrivacyValueAllowContacts());
+            break;
+        case "close_friends":
+            rules.push(new Api.InputPrivacyValueAllowCloseFriends());
+            break;
+        case "selected":
+            rules.push(new Api.InputPrivacyValueAllowUsers({
+                users: (allowUserIds ?? []).map((id) => new Api.InputUser({ userId: bigInt(id), accessHash: bigInt(0) })),
+            }));
+            break;
+    }
+    if (disallowUserIds?.length && privacy !== "selected") {
+        rules.push(new Api.InputPrivacyValueDisallowUsers({
+            users: disallowUserIds.map((id) => new Api.InputUser({ userId: bigInt(id), accessHash: bigInt(0) })),
+        }));
+    }
+    return rules;
+}
+export function extractStoryIdFromUpdates(result) {
+    if (!result)
+        return 0;
+    if (result instanceof Api.Updates || result instanceof Api.UpdatesCombined) {
+        for (const u of result.updates) {
+            if (u instanceof Api.UpdateStoryID)
+                return u.id;
+        }
+        for (const u of result.updates) {
+            if (u instanceof Api.UpdateStory && u.story instanceof Api.StoryItem)
+                return u.story.id;
+        }
+    }
+    return 0;
+}
+export function summarizeDiscussionMessage(result) {
+    const topMsg = result.messages?.[0];
+    let discussionGroupId = "";
+    for (const chat of result.chats ?? []) {
+        const isBroadcast = "broadcast" in chat && chat.broadcast;
+        if (!isBroadcast) {
+            discussionGroupId = `-100${chat.id.toString()}`;
+            break;
+        }
+    }
+    const discussionMsgId = topMsg instanceof Api.Message || topMsg instanceof Api.MessageService ? topMsg.id : 0;
+    const topMessage = topMsg instanceof Api.Message
+        ? {
+            id: topMsg.id,
+            text: topMsg.message?.slice(0, 200),
+            date: topMsg.date,
+        }
+        : undefined;
+    return {
+        discussionGroupId,
+        discussionMsgId,
+        unreadCount: result.unreadCount ?? 0,
+        readInboxMaxId: result.readInboxMaxId,
+        readOutboxMaxId: result.readOutboxMaxId,
+        topMessage,
+    };
+}
+export function summarizeGroupsForDiscussion(result) {
+    const chats = "chats" in result ? result.chats : [];
+    return {
+        groups: chats.map((c) => {
+            const id = `-100${c.id.toString()}`;
+            const title = "title" in c ? c.title : "";
+            const username = "username" in c ? (c.username ?? undefined) : undefined;
+            const participantsCount = "participantsCount" in c ? (c.participantsCount ?? undefined) : undefined;
+            return { id, title, username, participantsCount };
+        }),
+    };
+}
+export function summarizeReadParticipants(list, messageId) {
+    return {
+        messageId,
+        readers: list.map((r) => ({
+            userId: r.userId.toString(),
+            readAt: new Date(r.date * 1000).toISOString(),
+        })),
+        count: list.length,
+    };
+}
+export function summarizeReportResult(result) {
+    if (result instanceof Api.ReportResultReported)
+        return { kind: "reported" };
+    if (result instanceof Api.ReportResultAddComment)
+        return { kind: "addComment", optional: result.optional };
+    if (result instanceof Api.ReportResultChooseOption) {
+        return {
+            kind: "chooseOption",
+            title: result.title,
+            options: (result.options ?? []).map((o) => {
+                const opt = o;
+                return {
+                    text: opt.text,
+                    option: Buffer.from(opt.option).toString("base64"),
+                };
+            }),
+        };
+    }
+    throw new Error(`unknown ReportResult type: ${result.className ?? "unknown"}`);
+}
+export function summarizePoll(poll, results) {
+    const total = results?.totalVoters ?? 0;
+    const answerResults = results?.results ?? [];
+    const options = poll.answers.map((answer, index) => {
+        // Match by option bytes
+        const v = answerResults.find((r) => {
+            const rOpt = Buffer.from(r.option);
+            const aOpt = Buffer.from(answer.option);
+            return rOpt.equals(aOpt);
+        });
+        const votes = v?.voters ?? 0;
+        const percent = total > 0 ? Math.round((votes / total) * 1000) / 10 : 0;
+        return {
+            index,
+            text: answer.text.text,
+            votes,
+            percent,
+            chosen: v?.chosen ?? false,
+            correct: poll.quiz ? (v?.correct ?? false) : undefined,
+        };
+    });
+    return {
+        question: poll.question.text,
+        isClosed: poll.closed ?? false,
+        isQuiz: poll.quiz ?? false,
+        isMulti: poll.multipleChoice ?? false,
+        totalVoters: total,
+        options,
+    };
+}
+export function extractPollMediaFromUpdates(updates) {
+    let list = [];
+    if (updates instanceof Api.Updates || updates instanceof Api.UpdatesCombined) {
+        list = updates.updates;
+    }
+    else if (updates instanceof Api.UpdateShort) {
+        list = [updates.update];
+    }
+    for (const u of list) {
+        if (u instanceof Api.UpdateMessagePoll) {
+            if (u.poll instanceof Api.Poll) {
+                return {
+                    poll: u.poll,
+                    results: u.results instanceof Api.PollResults ? u.results : undefined,
+                };
+            }
+        }
+    }
+    return null;
+}
+export function extractPeerId(peer) {
+    if (peer instanceof Api.PeerUser)
+        return peer.userId.toString();
+    if (peer instanceof Api.PeerChat)
+        return peer.chatId.toString();
+    if (peer instanceof Api.PeerChannel)
+        return peer.channelId.toString();
+    return "0";
+}
+export function summarizeEmojiStatus(s) {
+    if (s instanceof Api.EmojiStatusCollectible) {
+        return {
+            kind: "collectible",
+            collectibleId: s.collectibleId.toString(),
+            documentId: s.documentId?.toString(),
+            title: s.title,
+            slug: s.slug,
+            until: s.until,
+        };
+    }
+    if (s instanceof Api.EmojiStatus) {
+        return { kind: "default", documentId: s.documentId.toString(), until: s.until };
+    }
+    return { kind: "empty" };
+}
+export function summarizePeer(peer) {
+    if (peer instanceof Api.PeerUser)
+        return { id: peer.userId.toString(), type: "user" };
+    if (peer instanceof Api.PeerChat)
+        return { id: peer.chatId.toString(), type: "chat" };
+    return { id: peer.channelId.toString(), type: "channel" };
+}
 export function summarizeAllStories(result) {
     const stealthMode = result.stealthMode
         ? {

package/dist/tools/account.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+import { ABSOLUTE_PATH_ERROR, DESTRUCTIVE, fail, isSafeAbsolutePath, ok, READ_ONLY, requireConnection, WRITE, } from "./shared.js";
 const MUTE_FOREVER_UNTIL = 2147483647; // max 32-bit signed int
 export function registerAccountTools(server, telegram) {
     server.registerTool("telegram-mute-chat", {
@@ -369,17 +369,232 @@ export function registerAccountTools(server, telegram) {
             return fail(e);
         }
     });
-    server.registerTool("telegram-get-business-chat-links", {
-        description: "List Telegram Business chat links configured for the account (account.GetBusinessChatLinks). Each entry includes the t.me/... link, the prefilled message, optional title (admin-facing label), views count, and entityCount (number of formatting entities in the message). Requires a Telegram Business-enabled account — returns an empty list when the account has none configured. Read-only.",
-        inputSchema: {},
+    // ─── Profile write tools (v1.32.0) ─────────────────────────────────────────
+    server.registerTool("telegram-set-emoji-status", {
+        description: "Set your profile emoji status (custom animated emoji shown next to your name). Requires Telegram Premium. Pass documentId or collectibleId to set — omit both to clear the status. Use telegram-list-emoji-statuses to browse available IDs.",
+        inputSchema: {
+            documentId: z
+                .string()
+                .optional()
+                .describe("Custom emoji document ID (stringified long). Omit to clear the status."),
+            collectibleId: z
+                .string()
+                .optional()
+                .describe("Collectible emoji ID (stringified long) — for paid unique emoji. Exactly one of documentId/collectibleId may be set."),
+            untilUnix: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Unix timestamp when status expires. Omit for permanent."),
+        },
+        annotations: WRITE,
+    }, async ({ documentId, collectibleId, untilUnix }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (documentId && collectibleId) {
+            return fail(new Error("Only one of documentId or collectibleId may be set"));
+        }
+        try {
+            await telegram.setEmojiStatus({ documentId, collectibleId, untilUnix });
+            if (!documentId && !collectibleId)
+                return ok("Emoji status cleared");
+            const id = collectibleId ?? documentId;
+            const until = untilUnix ? ` until ${new Date(untilUnix * 1000).toISOString()}` : "";
+            return ok(`Emoji status set: ${id}${until}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-list-emoji-statuses", {
+        description: "List default or recently-used emoji statuses available for your account. Useful for finding a documentId to pass to telegram-set-emoji-status.",
+        inputSchema: {
+            kind: z
+                .enum(["default", "recent", "channel_default", "collectible"])
+                .default("default")
+                .describe("Which list: default (popular set), recent (your recent usage), channel_default (for channels), collectible (paid unique)"),
+            limit: z.number().int().positive().max(200).default(50).describe("Max items to return"),
+        },
         annotations: READ_ONLY,
+    }, async ({ kind, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const items = await telegram.listEmojiStatuses(kind, limit);
+            if (!items.length)
+                return ok(`[${kind}]\n(no statuses)`);
+            const lines = items.map((s) => {
+                const id = s.collectibleId ?? s.documentId ?? "empty";
+                const until = s.until ? ` until=${s.until}` : " until=permanent";
+                const extra = s.title ? ` title="${s.title}"` : "";
+                return `${s.kind} id=${id}${until}${extra}`;
+            });
+            return ok(`[${kind}]\n${lines.join("\n")}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-clear-recent-emoji-statuses", {
+        description: "Clear your recently-used emoji status list (the 'recent' section in the emoji status picker).",
+        inputSchema: {},
+        annotations: WRITE,
     }, async () => {
         const err = await requireConnection(telegram);
         if (err)
             return fail(new Error(err));
         try {
-            const result = await telegram.getBusinessChatLinks();
-            return ok(JSON.stringify(result));
+            await telegram.clearRecentEmojiStatuses();
+            return ok("Recent emoji statuses cleared");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-profile-color", {
+        description: "Set your profile name color or profile background color. Requires Telegram Premium for colors above index 6 and for profile background patterns. Omit color to reset to default.",
+        inputSchema: {
+            forProfile: z
+                .boolean()
+                .default(false)
+                .describe("true = profile page color + background pattern (Premium); false = name color in chat lists"),
+            color: z
+                .number()
+                .int()
+                .min(0)
+                .max(20)
+                .optional()
+                .describe("Color index (0-6 free palette; 7+ Premium custom). Omit to reset to default."),
+            backgroundEmojiId: z
+                .string()
+                .optional()
+                .describe("Custom emoji document ID (stringified long) for profile background pattern (Premium). Omit to remove."),
+        },
+        annotations: WRITE,
+    }, async ({ forProfile, color, backgroundEmojiId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setProfileColor({ forProfile, color, backgroundEmojiId });
+            if (color === undefined && !backgroundEmojiId)
+                return ok("Profile color reset");
+            return ok(`Profile color updated: forProfile=${forProfile} color=${color ?? "default"} bg=${backgroundEmojiId ?? "none"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-birthday", {
+        description: "Set your birthday in your Telegram profile. Year is optional (omit to hide age). Pass clear=true to remove birthday. Requires day and month unless clearing.",
+        inputSchema: {
+            day: z.number().int().min(1).max(31).optional().describe("Day of month (1-31)"),
+            month: z.number().int().min(1).max(12).optional().describe("Month (1-12)"),
+            year: z.number().int().min(1900).max(2100).optional().describe("Year (optional — omit to hide age)"),
+            clear: z.boolean().optional().describe("Pass true to remove birthday from profile"),
+        },
+        annotations: WRITE,
+    }, async ({ day, month, year, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && (!day || !month)) {
+            return fail(new Error("day and month are required when not clearing"));
+        }
+        try {
+            await telegram.setBirthday({ day, month, year, clear });
+            if (clear)
+                return ok("Birthday cleared");
+            const yearStr = year ? `/${year}` : "";
+            return ok(`Birthday set: ${day}/${month}${yearStr}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-personal-channel", {
+        description: "Set the channel displayed on your profile as 'Personal Channel'. Pass clear=true to remove. Pass channelId or @username of a channel you own or are subscribed to.",
+        inputSchema: {
+            channelId: z.string().optional().describe("Channel ID or @username to feature on profile"),
+            clear: z.boolean().optional().describe("Pass true to remove personal channel from profile"),
+        },
+        annotations: WRITE,
+    }, async ({ channelId, clear }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (!clear && !channelId) {
+            return fail(new Error("channelId is required when not clearing"));
+        }
+        if (clear && channelId) {
+            return fail(new Error("Cannot set channelId and clear=true simultaneously"));
+        }
+        try {
+            const title = await telegram.setPersonalChannel({ channelId, clear });
+            if (clear)
+                return ok("Personal channel cleared");
+            return ok(`Personal channel set to ${title ?? channelId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-profile-photo", {
+        description: "Upload and set a new profile photo from a local file. Supports JPEG/PNG for static avatar or MP4 for animated avatar (square, up to 10s). Optionally set as fallback photo shown to users who cannot see your main photo.",
+        inputSchema: {
+            filePath: z
+                .string()
+                .min(1)
+                .refine(isSafeAbsolutePath, ABSOLUTE_PATH_ERROR)
+                .describe("Absolute local filesystem path to photo (JPEG/PNG) or video (MP4, square) to upload as avatar. URLs are rejected."),
+            isVideo: z.boolean().default(false).describe("true if file is an MP4 animated avatar; false for static photo"),
+            videoStartTs: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("For video avatar: timestamp in seconds to use as still preview frame"),
+            fallback: z
+                .boolean()
+                .default(false)
+                .describe("true = set as fallback photo (shown to users who cannot see your main photo due to privacy settings)"),
+        },
+        annotations: WRITE,
+    }, async ({ filePath, isVideo, videoStartTs, fallback }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.setProfilePhoto({ filePath, isVideo, videoStartTs, fallback });
+            const label = fallback ? "Fallback profile photo" : "Profile photo";
+            return ok(`${label} updated [id=${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-delete-profile-photo", {
+        description: "Delete one or more profile photos by their photo IDs. Use telegram-get-profile-photo to obtain the current photo ID. Returns which IDs were deleted and which were not found.",
+        inputSchema: {
+            photoIds: z
+                .array(z.string().regex(/^\d{1,20}$/, "must be a numeric photo ID"))
+                .min(1)
+                .max(100)
+                .describe("Array of photo IDs (stringified long) to delete from your profile photo history"),
+        },
+        annotations: WRITE,
+    }, async ({ photoIds }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { deleted, missing } = await telegram.deleteProfilePhotos(photoIds);
+            const parts = [`Deleted ${deleted.length} profile photo(s): ${deleted.join(", ")}`];
+            if (missing.length)
+                parts.push(`Not found: ${missing.join(", ")}`);
+            return ok(parts.join(". "));
         }
         catch (e) {
             return fail(e);

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