feat: add Telegram chat tools

[tdakkota]

Grows tgmcp from "read unread channels" into a Telegram client an agent can actually use: read any chat, send to it, move files in and out, and mark what an agent sent. Every capability stays opt-in, and the server is read-only unless a right is granted.

Tools

Reading: get_me, resolve_peer, search_chats, list_chats, get_chat_messages, search_chat_messages, mark_chat_read, mark_all_channels_read, get_file.

Sending, behind TG_ALLOW_SEND: send_message, edit_message, preview_format, send_file, send_poll, vote_poll, send_reaction, send_chat_action, send_screenshot_notification, list_inline_results, send_inline_result.

Profile, behind TG_ALLOW_PROFILE_EDIT: update_profile, update_profile_photo.

Formatting

parse_mode takes plain (default), markdown, html, or rich_markdown / rich_html. The rich modes send a rich message — page blocks rather than entities, so headings, lists, checklists, tables and block math work; there is no table entity, so this is how a table gets into a chat. Reading goes the other way: a rich message leaves the flat text empty, so its blocks are rendered back to Markdown and flagged rich: true, without which such a message reads as blank.

preview_format renders any of those without sending, returning the text Telegram will display, the entities with the substring each covers, and the length in UTF-16 units — so an agent can catch a markup error before it reaches a chat.

Files

get_file stores media in a blob store and returns a reference: a URL for the agent to fetch and an id another MCP server sharing the store can read. Nothing large enters the model's context. The store is either an S3 bucket (TG_BLOB_S3_*), which works when the agent cannot reach this process, or the server's own HTTP listener (TG_BLOB_BASE_URL). Neither configured means storage is denied outright rather than minting a URL that resolves nowhere.

send_file reads from that store too, so one server's output is another's input without a shared filesystem. kind picks how Telegram renders the bytes — auto, document, photo, video, gif, audio, voice, video_note, sticker — and reading names media the same way, so a voice message no longer reads as "document".

Agent attribution

TG_ATTRIBUTION marks messages as agent-sent: footer appends an italic line, bot routes them through an inline echo bot so Telegram renders a via @bot header. The bot is a second process (tgmcp echobot) with its own access list. Uploads and rich messages fall back to the footer, since an inline result cannot carry them. It marks by convention, not by proof.

Telemetry

serve runs under go-faster/sdk/app: OTLP traces, metrics and logs, with a span and metrics per MCP call. Payloads are not logged — that would be the contents of your chats — unless TG_LOG_PAYLOADS=true.

Notable fixes along the way

• Deadlock: floodwait.Waiter serialises through one goroutine, and gotd re-enters the middleware chain on DC migration, wedging the whole server. Replaced with a waiter that retries in the calling goroutine. Reported as Deadlock: DC migration re-enters the middleware chain, hangs with floodwait.Waiter td#1842.
• Unclassifiable uploads: message.FromReader cannot know the length, and gotd sends an unsized upload as inputFileBig with no checksum, after which Telegram will not classify the media — animations arrived as videos and round messages as flat ones, whatever attributes were attached. Uploads now carry their size. Reported as uploader: FromReader always uploads as inputFileBig, and Telegram then refuses to classify the media td#1845.
• Leaks: get_me, resolve_peer and search_chats returned phone numbers and access hashes, copied wholesale from tg.User; the MCP middleware logged every request and response body at debug, which reaches any configured log exporter. Both fixed, with a test asserting on the serialized form.