Address review feedback from @chigwell and @l1v0n1:
- Restore parse_mode=parse_mode in send_message and reply_to_message
- Restore _resolve_readable_file_path() in send_file, send_voice,
send_sticker, and edit_chat_photo
- Use str(safe_path) instead of raw file_path in upload_file calls
The entity cache fix (resolve_entity/resolve_input_entity) is preserved
in all affected functions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
contacts.SearchRequest returns both result.users and result.chats,
but only users were returned. Chats (channels, groups) are now
included, making search work by channel/group title as intended.
Shared folders in Telegram use DialogFilterChatlist type instead of
DialogFilter. Previously, all folder operations (list, get, create,
add/remove chat) silently ignored shared folders. This fix ensures
they are recognized and handled correctly alongside regular folders.
MCP clients (e.g. ZeroClaw) communicate via JSON-RPC over stdin/stdout.
Startup messages and warnings written to stdout corrupt the protocol
stream, causing parse failures. Redirect all print() calls to stderr.
Telethon's DeletePhotosRequest requires InputPhoto objects, which it derives
from Photo objects via get_input_photo(). Passing photo.id (an int) causes:
AttributeError: 'int' object has no attribute 'SUBCLASS_OF_ID'
TypeError: Cannot cast int to any kind of InputPhoto.
Fix: pass the Photo object directly (photos.photos[0]) so Telethon can
convert it to InputPhoto internally.
- implement server-side allowlist via CLI positional roots (fallback)\n- implement client MCP Roots override semantics (replace server roots when available)\n- add realpath + in-root validation, traversal/glob rejection, extension and size checks\n- make write path default to <first_root>/downloads when file_path is omitted\n- reintroduce upload_file tool with the same path security model\n- update README with security model and usage\n- add tests for root resolution, replacement semantics, traversal checks, and default write path\n- add pytest and pytest-asyncio to dev dependencies
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>
