Added Black and flake8 to development dependencies to ensure
consistent code formatting and linting across the project.
🤖 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
Renamed all instances of 'telegram-mcp-server' to 'telegram-mcp' in docker-compose.yml, README.md, and the Docker build workflow to ensure consistency and clarity across the project.
Added badges for Python linting and Docker build validation to the README.md, enhancing visibility of the project's continuous integration status and encouraging best practices in code quality and deployment.
Introduced a new section in the README.md detailing how to run the server using Docker, including steps for building the image and running the container with both Docker Compose and the `docker run` command. This enhances the documentation for users looking to simplify dependency management.
Introduced a step in the Docker build workflow to create a dummy .env file with placeholder values for TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING, facilitating local development and testing.
Improved the organization and clarity of error handling in main.py by consolidating exception management and refining error messages, particularly in asynchronous functions.
Updated error handling mechanisms in main.py to improve clarity and efficiency. This includes consolidating error messages and enhancing the structure of exception handling across asynchronous functions.
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.
