StringSession has no persistent entity cache. After each MCP server
restart, client.get_entity(positive_int) fails for basic group chats
because Telethon interprets positive integers as PeerUser IDs when
they're not in the cache.
Fix:
- Add resolve_entity() / resolve_input_entity() helpers that retry
after warming cache via get_dialogs() on ValueError
- Warm entity cache on startup in _main()
- Replace all ~72 client.get_entity() / client.get_input_entity()
call sites with the new helpers
Tested: 60/60 pass across 6 basic group chats (send_message,
get_history, reply, edit, draft, reactions, search, mark_as_read,
delete) with cold cache -> warm cache transition verified.
Fixeschigwell/telegram-mcp#76
archive_chat and unarchive_chat were using ToggleDialogPinRequest which
pins/unpins dialogs instead of archiving them. Replace with
folders.EditPeerFoldersRequest using folder_id=1 (Archive) and
folder_id=0 (Main) which is the correct API for moving chats to/from
the Archive folder.
- Changed phone parameter to Optional[str] = None
- Added separate username parameter (Optional[str] = None)
- Improved function signature clarity - username is now explicit parameter
- Updated validation logic to check for either phone or username
- Maintains backward compatibility with phone-based contacts
- Better API design - no longer need to pass username via phone parameter
- Modified add_contact function to support username-based contact addition
- If phone parameter is empty or starts with @, function resolves username first
- Uses contacts.AddContactRequest API for username-based contacts
- Maintains backward compatibility with phone-based contact addition
- Allows adding contacts as done in Telegram UI when searching by username
Add new MCP tools to manage Telegram dialog folders (filters):
- list_folders: get all folders with IDs, names, emoji
- get_folder: get folder details including all included chats
- create_folder: create new folder with filters and chat list
- add_chat_to_folder: add chat to existing folder (idempotent)
- remove_chat_from_folder: remove chat from folder (idempotent)
- delete_folder: delete folder (chats preserved)
- reorder_folders: change folder order
Handles Telegram API specifics:
- TextWithEntities for folder titles
- Max 10 folders limit
- System folder protection (ID < 2)
- title_noanimate and color attributes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds views, forwards, and reaction counts to message output for channel posts.
These metrics are available in Telegram's API for channel content.
Changes:
- get_messages: Include engagement info in output
- list_messages: Include engagement info in output
Example output: 'views:1234, forwards:56, reactions:78'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The individual line suggestions created invalid Python when applied
separately. Combined the ternary expression properly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously list_chats only checked dialog.unread_count, missing chats
that were manually marked as unread via Telegram's "mark as unread" feature.
Now also checks dialog.dialog.unread_mark flag:
- unread_count > 0: shows "Unread: N"
- unread_mark = True: shows "Unread: marked"
This matches the behavior of Telegram's "Unread" folder filter.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add three new tools for managing Telegram drafts:
- save_draft: Save a draft message to any chat/channel
- get_drafts: List all drafts across all chats
- clear_draft: Clear a draft from a specific chat
Uses Telethon's SaveDraftRequest and GetAllDraftsRequest APIs.
Drafts appear in Telegram's input field for review before sending.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add invite_to_group function to the Chat & Group Management section
of the README. This function exists in main.py with @mcp.tool() decorator
but was missing from the documentation.
Add documentation for three new message reaction tools from PR #41:
- send_reaction(chat_id, message_id, emoji, big=False): Add a reaction to a message
- remove_reaction(chat_id, message_id): Remove a reaction from a message
- get_message_reactions(chat_id, message_id, limit=50): Get all reactions on a message
These tools are now part of the Messaging section in the features list.
Add three new MCP tools for handling Telegram message reactions:
- send_reaction: Send emoji reaction to a message
- remove_reaction: Remove your reaction from a message
- get_message_reactions: Get list of reactions on a message
All tools include proper ToolAnnotations and follow existing code patterns.
Add human-readable title annotations to all MCP tools to help clients
display tool names in a user-friendly format.
Changes:
- Added title annotation to all 78 tools (e.g., "Get Chats", "Send Message")
- Formatted with Black for code style consistency
This improves the user experience when MCP clients display tool lists.
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#37
The mcp package was locked at version 1.6.0 which does not include
the ToolAnnotations type. This caused the server to fail on startup
with:
ImportError: cannot import name 'ToolAnnotations' from 'mcp.types'
Updated mcp from 1.6.0 to 1.22.0 which includes ToolAnnotations
and is compatible with the code added in PR #34.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
