overpod/mcp-telegram

What's New

This release adds 29 new tools across three phases of GramJS API coverage, bringing the total toolkit to 90+ tools.

Phase 2 — Admin Toggles, Customization & Stats

| Tool | Description |
|------|-------------|
| telegram-toggle-channel-signatures | Toggle author signatures on channel posts (chat, enabled) |
| telegram-toggle-anti-spam | Toggle aggressive anti-spam in supergroups — megagroups only (chat, enabled) |
| telegram-toggle-forum-mode | Convert supergroup to/from forum mode — confirm: true required when disabling (destructive: deletes all topics) |
| telegram-approve-join-request | Approve or decline pending join request (chat, userId, approved) — channels/supergroups only |
| telegram-toggle-prehistory-hidden | Hide/show old messages for new supergroup members (chat, hidden) |
| telegram-set-chat-reactions | Set allowed reactions: {type: "all"}, {type: "some", emoji: [...]}, or {type: "none"} |
| telegram-get-broadcast-stats | Channel broadcast stats (views, shares, reactions, growth) — compact by default, includeGraphs: true for raw data. Premium admin may be required. |
| telegram-get-megagroup-stats | Supergroup activity stats — rate-limited to 1 request per 30 minutes per channel |

Phase 3 — Inline Bots, Buttons & Real-Time Polling

| Tool | Description |
|------|-------------|
| telegram-inline-query | Query an inline bot (bot, chat, query, offset?) — returns queryId + results. queryId valid ~1 min. |
| telegram-inline-query-send | Send chosen inline result to a chat (chat, queryId, id, replyTo?, silent?) — returns messageId |
| telegram-get-message-buttons | List inline keyboard buttons with type, label, index — helper for press-button (chat, messageId) |
| telegram-press-button | Press an inline callback button by {row, col} or raw data — returns alert/message/url. URL/Game buttons rejected with descriptive error. |
| telegram-get-state | Get current update cursor {pts, qts, date, seq} — use once to initialize polling |
| telegram-get-updates | Stateless update polling via GetDifference (pts, qts, date) — caller holds cursor between calls. Returns {newMessages, deletedIds, otherUpdates, state, isFinal}. Falls back gracefully on DifferenceTooLong. |
| telegram-get-channel-updates | Per-channel update polling via GetChannelDifference (channel, pts, limit?) — separate cursor per channel |

Polling design: Cursors are not stored server-side. The calling agent stores {pts, qts, date} between invocations — stateless by design.

Phase 4 (Ship) — Stories, Boosts & Business

| Tool | Description |
|------|-------------|
| telegram-get-all-stories | All stories in feed (hidden?, next?, state?) |
| telegram-get-peer-stories | Stories for a specific user/channel (chat) |
| telegram-get-stories-by-id | Fetch specific stories by IDs (chat, ids[]) |
| telegram-get-story-views | Views on own stories — may require Telegram Premium (chat, storyId) |
| telegram-get-my-boosts | List of channels the authenticated user is boosting |
| telegram-get-boosts-status | Boost level, next level threshold, premium audience for a channel (chat) |
| telegram-get-boosts-list | Paginated list of users boosting a channel (chat, gifts?, offset?, limit?) |
| telegram-get-business-chat-links | Telegram Business chat links for the authenticated account |

Phase 4 (Opt-in) — Gated by Environment Flags

These tools are not registered by default — set the corresponding env flag to enable:

| Tool | Flag | Notes |
|------|------|-------|
| telegram-get-group-call | MCP_TELEGRAM_ENABLE_GROUP_CALLS=1 | Active group call metadata (callId, accessHash) |
| telegram-get-group-call-participants | MCP_TELEGRAM_ENABLE_GROUP_CALLS=1 | Paginated participant list (callId, accessHash, offset?, limit?) |
| telegram-get-stars-status | MCP_TELEGRAM_ENABLE_STARS=1 | Stars balance for a peer — creator accounts only |
| telegram-get-stars-transactions | MCP_TELEGRAM_ENABLE_STARS=1 | Stars transaction history (peer, inbound?, outbound?, offset?, limit?) — mutually exclusive filters |
| telegram-get-quick-replies | MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1 | Quick reply shortcuts — Telegram Business accounts only |
| telegram-get-quick-reply-messages | MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1 | Messages in a quick reply shortcut (shortcutId) |

Takeout API deferred to Phase 5 (requires GDPR/legal review).

Quality & Internals

• 199 unit tests — full coverage for all new tools
• 18 bugs caught and fixed by Ralphex autonomous review loop (7 Claude iterations + Codex GPT-5 external review)
• All tools follow existing conventions: registerTool() API, Zod input validation, sanitize() on output, isError: true on failures, rate-limit retry via existing wrapper
• Cloud-safety labels on all tools — whitelist diff for mcp-telegram-cloud coming in v1.10.0