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 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>
Fixed undefined variable '_id' in unarchive_chat function by
changing it to 'chat_id' which is the correct parameter name.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Applied Black code formatting to main.py to resolve linting
failures in GitHub Actions for PR #24.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Applied Black code formatting to main.py and test_validation.py
to resolve linting failures in GitHub Actions.
Changes include:
- Proper line breaking for long lines
- Consistent quote style (single to double quotes)
- Better formatting of return statements
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add new list_topics() MCP tool to retrieve forum topics from Telegram
supergroups with forum feature enabled.
Features:
- Validates chat is a supergroup with forum enabled
- Supports pagination via offset_topic parameter
- Supports search filtering via search_query parameter
- Returns comprehensive topic metadata:
* Topic ID and title
* Total messages and unread count
* Status flags (closed, hidden)
* Last activity timestamp
- Proper error handling and logging
Documentation:
- Added list_topics to README Messaging tools list
- Added complete code example with implementation
- Added example output showing typical usage
Uses Telethon's GetForumTopicsRequest API for reliable forum topic
retrieval from supergroups.
- stream search results via `client.iter_messages()` and apply date bounds in-code so we collect up to `limit` matches
- use server-side iteration for date-only queries with inclusive upper bounds to avoid over-fetching
- keep the existing `get_messages()` fast path when no filters are provided
- Add python-json-logger dependency.
- Configure file handler to use JsonFormatter for structured logging.
- Keep console handler with the existing text format.
- Refactor log_and_format_error to log a dictionary with structured error data.
Adds a new `@validate_id` decorator to validate `chat_id` and `user_id` parameters in `main.py`.
This decorator ensures that all IDs passed to functions are in a valid format before making RPC calls to the Telegram API. It handles:
- Integer IDs (positive and negative)
- String representations of integer IDs
- Usernames (e.g., "@username")
- Lists of IDs
Key changes:
- Created a `validate_id` decorator in `main.py`.
- Applied the decorator to all functions that accept `chat_id`, `user_id`, or similar parameters.
- Updated the central `log_and_format_error` function to handle custom validation error messages and a specific `VALIDATION-001` error code for logging.
- Added a new test suite (`test_validation.py`) with comprehensive tests for the decorator.
- Updated `README.md` and `session_string_generator.py` with documentation about the new validation.
Updated message formatting in various functions to include details about replies. When a message is a reply, it now shows the ID of the original message and the sender's name, improving context for users.
Introduced a new helper function, get_sender_name, to retrieve the sender's name from messages. Updated various message display functions to include the sender's name in the output, improving clarity and context for users
Refactored several sections of main.py to enhance readability by adjusting line breaks and indentation. This includes formatting changes in error handling and function calls across various asynchronous functions.
Removed several functions that required direct file path access, including `send_file`, `download_media`, `set_profile_photo`, `edit_chat_photo`, `send_voice`, `send_sticker`, and `upload_file`, due to limitations in the current MCP environment. Updated the README to reflect these changes and added a section on removed functionality.
