telegram-summarize: Instructions file for Codex

telegram-mcp — Agent Instructions

This repository exposes a Telegram account to MCP clients through MTProto. It uses Bun, TypeScript, mtcute, and @modelcontextprotocol/sdk. The Streamable HTTP endpoint is /mcp.

Primary Workflow

Operate this repository primarily as a read-only Telegram discussion summarizer for Codex, Claude, and other MCP-compatible agents.

For every date-and-source summary request, load and follow .agents/skills/meeting-minutes/SKILL.md.

request -> normalize range -> resolve source -> fetch bounded windows
-> verify coverage -> deduplicate -> chronological sort
-> summarize topics and participants -> cite sources -> state limitations

The MCP server supplies atomic Telegram data operations. The agent orchestrates those tools and writes the summary; the server does not embed an LLM.

Source and Time Resolution

• Use an exact @username or numeric chat ID directly.
• Otherwise call search_dialogs. If multiple plausible matches remain, ask the user to choose. Never guess a Telegram identity.
• Accept one or more sources. Retrieve and report coverage independently for each source.
• Treat start and end as inclusive.
• When the end is omitted, use the actual current time.
• When the timezone is omitted, use the MCP client's environment timezone and state it. Ask when no timezone is available.
• When the year is omitted, use the current year. If that places the start in the future, ask for the year.
• Convert boundaries to ISO 8601 before calling Telegram tools.

Complete Range Retrieval

1. Call get_messages with chatId, minDate, maxDate, limit: 500, onlyUnread: false, and markAsRead: false.
2. When limitReached is true, split the interval at its midpoint. Start the right window one second before the midpoint when both children remain strictly smaller.
3. Split saturated children recursively. If a range cannot be split safely, report it as incomplete instead of looping or claiming full coverage.
4. Deduplicate overlapping results by (chatId, id) and sort by date, then id.
5. Do not substitute search_messages for range retrieval unless the user explicitly asks for keyword search.
6. On FLOOD_WAIT, authentication failure, or inaccessible history, do not retry automatically. State the successful and missing subranges.