# telegram-mcp (движок)

Read-only MCP-читалка своей Telegram (self-host, Telethon). Открытый движок — актив бренда [aiaiai](https://getaiaiai.ru). Session живёт на устройстве (keychain), наружу не уходит. v1 = читалка; write-методы не выставлены.

Дизайн и решения — в umbrella-репо `telegram-mcp-hosted` (`docs/decisions.md`, `architecture.md`, `build-plan.md`).

## Раскладка
```
telegram_mcp/
  server.py        # entrypoint: FastMCP + авто-дискавери tools/
  _app.py          # единый FastMCP-инстанс (mcp)
  config.py        # app-креды (BYO env/.env; broker позже)
  qr_render.py     # ASCII-QR полублоками (обкатан в спайке) ✅
  session_store.py # SessionStore: keychain+Fernet — интерфейс (impl = T2)
  client.py        # get_client() -> авторизованный TelegramClient — интерфейс (impl = T3)
  auth.py          # QR-login + 2FA — интерфейс (impl = T4)
  tools/
    _base.py       # mcp, get_client, общие хелперы — единая точка импорта
    *.py           # по тулу на файл, саморегистрация через @mcp.tool (стабы T5–T12)
```

## Контракт для авторов тулзов (Wave 1, T5–T12)
- Файл тула начинается с `from telegram_mcp.tools._base import mcp, get_client`.
- Регистрация — `@mcp.tool` (FastMCP берёт сигнатуру+докстринг в схему). Центрального списка НЕТ — добавил файл, тул появился (авто-дискавери).
- В Telegram — **только** через `await get_client()`.
- **read-only**: только `get_*`/`iter_*`/`download_*`. Ни одного write-вызова.
- Возвращай JSON-сериализуемое (dict/list), не объекты Telethon.
- Трогаешь **только свой файл**. Не редактируешь `pyproject`, `server.py`, `_base.py`, `_app.py` (нужна общая утилита/зависимость → флаг в интеграцию T16). Свой git worktree.

## Установка (self-host)
```bash
# 1. поставить как CLI (uv сам тянет нужный python ≥3.10)
uv tool install git+https://github.com/expremiental/telegram-mcp

# 2. залогиниться — отсканировать QR своим Telegram
#    (app-креды берутся с брокера автоматически, ничего на my.telegram.org создавать не надо)
telegram-mcp login

# 3. подключить в Claude Code / Cursor
claude mcp add -s user telegram-mcp -- telegram-mcp serve
```
Перезапусти хост → спрашивай обычным языком: «сделай дайджест непрочитанного», «найди чат с …», «что писали в … за сегодня».

- **read-only** — выставлены только read-тулзы; ничего не отправляет/не меняет.
- **session шифрованная в keychain, машину не покидает.** Сброс: `telegram-mcp logout`.
- BYO-креды (advanced): `TELEGRAM_API_ID`/`TELEGRAM_API_HASH` в окружении переопределяют брокер.

## Dev
```bash
uv venv --python 3.12 .venv && uv pip install -e . --python .venv
.venv/bin/telegram-mcp serve   # сервер (stdio)   ·   login / logout — онбординг
```
Требует Python ≥3.10 (FastMCP).