fast-mcp-telegram: Skill for Cursor

Telegram-Specific Patterns

Entity Resolution

Always resolve chat/user entities using the utility functions:

from src.utils.entity import get_entity_by_id

# ✅ Correct - handles all entity types (users, chats, channels)
entity = await get_entity_by_id(chat_id)
if not entity:
    raise ValueError(f"Could not find chat with ID '{chat_id}'")

# ❌ Wrong - don't use client.get_entity directly
entity = await client.get_entity(chat_id)  # Missing error handling

Special Chat Identifiers

Use these special identifiers for common chats:

# Saved Messages (your own messages)
chat_id = "me"

# Channel IDs (always start with -100)
channel_id = "-1001234567890"

# User IDs (numeric strings)
user_id = "123456789"

# Usernames (without @)
username = "telegram"

Message Content Detection

Check for various types of message content:

# Check for text content
has_text = message.text and message.text.strip()

# Check for media content (photos, documents, etc.)
has_media = hasattr(message, "media") and message.media is not None

# Check for specific media types
is_photo = hasattr(message, "photo") and message.photo is not None
is_document = hasattr(message, "document") and message.document is not None
is_voice = hasattr(message, "voice") and message.voice is not None

Message Iteration

Use proper patterns for iterating through messages:

# ✅ Correct - limit results and handle empty messages
async for message in client.iter_messages(entity, limit=50):
    if not message:
        continue
    # Process message
    await process_message(message)

# ❌ Wrong - no limit can cause performance issues
async for message in client.iter_messages(entity):  # No limit!
    pass

Forwarded Message Handling

Handle forwarded messages properly:

# Check if message is forwarded
if hasattr(message, "forward") and message.forward:
    forward_info = await _extract_forward_info(message)
    original_sender = forward_info.get("sender")
    original_chat = forward_info.get("chat")
    forward_date = forward_info.get("date")