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>
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>
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.
