Telegram MCP Server — Documentation
A Telegram bot that acts as an MCP (Model Context Protocol) server, exposing structured tools to an external AI agent. The agent handles all decision logic; this system handles I/O, auth, memory, and async job execution.
Stack: Node.js + TypeScript, Fastify, telegraf, @modelcontextprotocol/sdk, Postgres, Inngest Cloud, Zod, pino.
Where things live
| Folder | Purpose | Populated |
|---|---|---|
| plan/ | Phase-by-phase execution checklists + design reference docs (architecture, data model, MCP tool contracts, deployment runbook, testing strategy, open questions). | Now — the source of truth before code exists. |
| api/ | MCP tool API documentation: signatures, request/response shapes, error codes, examples. | As tools land (starting Phase 2). |
| architecture/ | Architecture-as-built: diagrams, component boundaries, data flow, request lifecycle. | As components ship. |
| components/ | Per-module documentation (one page per source module). | As modules are implemented. |
| dev/ | Developer setup, contributing guide, deployment runbook. | As tooling stabilizes. |
| testing/ | Testing strategy, how to run the suites, coverage expectations. | As tests are added. |
Start here
If you’re picking up the project for the first time, read plan/README.md — it lists the phases and links to the design reference docs.