feat: view peer photos through MCP — index, open and contact sheet

[dagahan]

Summary

Photos are the one thing this server can detect but never show. get_media_label correctly classifies an attached photo, get_user_photos returns bare integers, and get_chat reports has_photo: true — but the only route to the actual bytes is download_media, which writes to disk and returns a path. An MCP client without filesystem access simply cannot see a Telegram photo.

This adds three tools that close that gap for any peer — user, basic group, supergroup or channel — and surfaces the profile fields GetFullUser already returns.

Design: a tool either returns text or returns images, never conditionally

Vision tokens are expensive, so cost is predictable from the tool name alone rather than hidden behind a parameter:

Tool	Cost	Returns
list_photos	free	JSON index of ids, dates, captions
open_photo	1 image	one photo, full resolution
get_photo_sheet	1 image	labelled collage of the last N

Each cell of the sheet is stamped with the exact id open_photo accepts, so the collage is a navigable index rather than a preview. Discovery stays free; you pay only for what you decide to look at.

list_photos(peer)      → text index, no image transferred
get_photo_sheet(peer)  → six avatars for one image of tokens, each cell labelled
open_photo(peer, id)   → that one, full resolution

Three sources, one resolver

telegram_mcp/photo_source.py is the only place that branches on peer type:

source	User	Group / supergroup / channel
avatars	GetUserPhotosRequest	InputMessagesFilterChatPhotos (no equivalent API exists)
messages	InputMessagesFilterPhotos	InputMessagesFilterPhotos

All three converge on one PhotoReference, so the tools never branch and the sheet builder exists once. Bytes go straight to memory via download_media(..., file=bytes); the sheet requests Telegram's pre-rendered small sizes rather than full images.

Two pre-existing bugs this arms, fixed first

Both are independent of the feature and reachable by any tool returning non-text:

• with_account corrupts non-string returns. The multi-account read-only fan-out joins results with "\n\n".join(f"[{label}]\n{result}"), which stringifies an Image into its repr. It now emits content blocks when any account yields non-text, and keeps the joined string when all yield text.
• The audience=["user"] annotation hook skips images. _install_annotation_hook only tagged TextContent, so image blocks would reach clients without the user-generated-data marker that the hook exists to apply. Now covers ImageContent.

Profile fields

get_full_user discarded most of what GetFullUser returns. Added, all additive and sanitized: collectible usernames, language, business profile (location/hours/intro), trust flags (scam/fake/restricted + reasons), relationship flags, and current_avatar_id. get_chat gains the same avatar id for every peer type. The id comes off the entity, so none of this costs an extra round trip.

Conformance

• readOnlyHint=True on all three tools, so TELEGRAM_EXPOSED_TOOLS=read-only keeps them
• @validate_id, @with_account(readonly=True), log_and_format_error, sanitize_user_content throughout
• MCP resources were considered and rejected: resources/read bypasses the annotation hook, the TELEGRAM_EXPOSED_TOOLS gate and with_account, so a resource surface would silently disable three safeguards and break under multi-account
• Degrades rather than fails — Pillow absent disables only the sheet, an unsearchable channel returns an empty index, a single avatar returns no sheet

Dependency

Pillow, in both pyproject.toml and requirements.txt since the Dockerfile installs from the latter. ffmpeg's tile filter was the alternative but common builds omit drawtext, which would lose the cell labels that make the sheet useful. Pillow ships cp313 musllinux wheels, so the Alpine image needs no extra system packages — verified by building it.

Testing

50 new tests; 335 pass overall, up from 281. black and flake8 clean, Docker image builds.

Verified against the live API, not only fixtures: avatar and message sheets, full-resolution opens addressed from sheet labels in both directions, the chat-photo service-message branch on a real supergroup, and the error paths for unknown ids and invalid sources.

Live testing also caught something fixtures could not — GetUserPhotos returns avatars in profile display order, not chronologically. Since that order is the peer's own arrangement, sorting would discard real information; the docstrings now state it instead.

🤖 Generated with Claude Code