Plan
The execution plan and authoritative design reference for the Telegram MCP Server. The project is pre-implementation as of 2026-05-14: this folder is the source of truth until code lands and the api/, architecture/, components/, dev/, and testing/ folders take over.
Phases
Each phase is an independently shippable slice with its own scope, automated unit-test plan, and definition of done.
| # | Phase | One-line goal |
|---|---|---|
| 0 | Pre-flight | Accounts, infra, and secrets staged before code starts. |
| 1 | Minimal Telegram bridge | Telegram message → server → hardcoded reply, plus DB + users table. |
| 2 | MCP tool server | Bearer-gated /mcp endpoint with the four basic messaging tools wired to Telegram. |
| 3 | User & auth system | Admin approval gate + approve_user / set_role admin tools + audit log. |
| 4 | Memory system | Per-user KV memory and archived chat history exposed as MCP tools. |
| 5 | Async job system (Inngest) | create_job / get_job_status / cancel_job with push notifications on completion. |
| 6 | Agent integration | Full-surface validation via MCP Inspector; ready for the external Claude agent. |
| 7 | Multi-modal support | Photo / document / callback round-trips, all send_image source variants. |
| 8 | Polish & hardening | Rate limits, backups, token rotation, crash-loop guard, complete runbook. |
Reference documents
Cross-cutting design and operational documents that the phase files reference:
- design-overview.md — Architecture, components, hosting topology, repo layout, system flows, security, observability, error handling, key design rules.
- data-and-contracts.md — Environment variables, Postgres schema, MCP tool contracts, MCP session/push model, Inngest event schemas.
- operations-and-strategy.md — Testing strategy, deployment runbook, tech stack, open questions.
How to use this folder
When picking up work:
- Find the current phase’s
phase-n-*.mdfile. - Check off Scope / Deliverables as you ship them.
- Write the listed Automated Unit Testing cases alongside the implementation.
- The phase is done when every box in the Definition of Done section is checked.
When making a design decision: update the relevant reference doc (design-overview.md, data-and-contracts.md, or operations-and-strategy.md) and link the phase file to it.