Review: fix(media): search GIFs through the @gif inline bot

Verdict: no changes required. I verified the new flow against the pinned Telethon 1.45 source (pyproject.toml: telethon>=1.45.0); would approve, but GitHub does not allow the PR author account to submit an approval, so this is filed as a comment review.

Premise confirmed

• functions.messages.SearchGifsRequest does not exist in Telethon 1.45 (grep over the installed package finds nothing), so the old primary path always raised AttributeError into the fallback — the PR's diagnosis is right.
• The old fallback returned bare document IDs with no access_hash/file_reference; send_file on such an int reached utils.get_input_media and died with the opaque ValueError: Failed to convert ... to media (telethon/client/uploads.py:830). Old send path was indeed broken for search results.

New flow verified against Telethon 1.45 source

• telegram_mcp/tools/media.py:539 — cl.inline_query("gif", query) is valid (telethon/client/bots.py:11); it takes no limit parameter, so the client-side [: max(limit, 0)] truncation is the right call.
• telegram_mcp/tools/media.py:543 — InlineResult.document is a property (telethon/tl/custom/inlineresult.py:95): it returns a Document for BotInlineMediaResult, a WebDocument (which has no id attribute) for plain results, or None — the isinstance(...id..., int) guard filters the latter two correctly.
• telegram_mcp/tools/media.py:506 — utils.get_input_document handles Document → InputDocument(id, access_hash, file_reference) (telethon/utils.py:331).
• telegram_mcp/tools/media.py:579 — send_file(entity, InputDocument) routes through utils.get_input_media → InputMediaDocument (telethon/utils.py:455) → SendMediaRequest, so the access hash and file reference reach the wire.
• telegram_mcp/tools/media.py:515 — GetSavedGifsRequest(hash=0) exists and with hash=0 always returns the full messages.SavedGifs; the getattr(saved, "gifs", []) guard additionally covers the (practically impossible) SavedGifsNotModified.

Tests assert the changed behavior

tests/test_gif_tools.py drives the real TelegramClient.inline_query/send_file wrappers over a stubbed __call__: the search test asserts GetInlineBotResultsRequest is issued to the bot and IDs are returned; the send test asserts the emitted SendMediaRequest carries (id, access_hash, file_reference) == (GIF_ID, 777, b"ref"); the unknown-ID test asserts refusal with no SendMediaRequest. The saved-GIF fallback path is covered too.

Non-blocking observations

1. telegram_mcp/tools/media.py:576 — a remembered InputDocument can go stale between search and send (FILE_REFERENCE_EXPIRED); the send then surfaces a raw RPC error and the user must re-run get_gif_search to refresh. A catch-and-refresh (re-query the inline bot, or drop the cache entry and fall through to saved GIFs) would make this self-healing. No regression vs. the old always-broken path, so fine to keep as-is.
2. telegram_mcp/tools/media.py:502 — _known_gifs grows for the process lifetime (one small InputDocument per search result). Entries are tiny and keyed per account, so this is negligible in practice for an MCP server; an LRU cap would be enough if it ever matters.
3. telegram_mcp/tools/media.py:539 — limit no longer reaches the API (the inline-query request has no limit field; the server returns one page of ~20–50 results). A caller asking for limit=100 silently gets at most one page. Still within the documented "max number of GIFs" contract; noting it for awareness.
4. tests/test_error_logging.py:309 — test_gif_fallback_error_omits_exception_and_query_payload is now stale: it patches the removed SearchGifsRequest and its second __call__ branch (RuntimeError("exception-payload-secret")) is unreachable, since the new code fails on the missing inline_query attribute before ever calling __call__. The test still passes and still pins the payload-redaction behavior, but it now exercises only the outer error formatting. Worth renaming/reworking in a follow-up, not in this PR.

Hi @axisrow, thank you for your useful contributions. We really appreciate it.

That said, regarding this specific PR, I am not comfortable with adding an integration with another bot, even if it is Telegram’s @gif bot. I think it would be better to keep telegram-mcp isolated from third-party bot integrations, or at least make this integration optional and disabled by default.

Review: PR #345 — native GIF search feeding send_gif (head 06c9dcc)

Approving. Both commits reviewed as one diff against e55d9c7.

Verified:

• get_gif_search now returns document IDs whose access_hash/file_reference are remembered, and send_gif resolves the InputDocument from that memory or the account saved-GIFs list before send_file — this fixes the old flow where a bare document ID could never be sent back.
• The comprehension guard handles msg.media None and missing document attributes; a get_messages failure propagates to log_and_format_error with the query omitted (pinned by the updated error-logging test).
• limit=max(limit, 0) is safe: Telethon 1.44 iter_messages stops immediately for limit <= 0 (no unbounded sweep).
• The new test file pins the real Telethon path end to end: SearchGlobalRequest with InputMessagesFilterGif, no inline-bot fallback, SendMediaRequest carrying (id, access_hash, file_reference), the saved-GIF fallback, and the unknown-ID reply without any send.
• ensure_ascii=False is preserved per the earlier json fix.

Non-blocking notes:

• The isinstance(id, int) guard lets DocumentEmpty (id=0) through: it is cached and reported as a sendable ID. Restricting to id > 0 or isinstance(document, types.Document) would drop the junk entry.
• _known_gifs is keyed by the raw account string, not the canonical label, so differently spelled account args miss the cache (they degrade to the saved-GIFs lookup, which is acceptable).
• Cached file_reference can expire after a long delay; the FILE_REFERENCE_EXPIRED error sends the agent back to get_gif_search, which refreshes the cache — fine as is.
• _known_gifs never evicts; entries are tiny, acceptable for a long-running server.

Verdict: approved.