# Telegram MCP Server

MCP-сервер для Telegram-канала. Предоставляет **read-only** доступ к постам, комментариям, реакциям и агрегированной статистике через MCP-протокол (Streamable HTTP). Работает по MTProto (GramJS), поэтому видит **всю историю канала**, а не только новые сообщения.

Сервер физически не умеет писать: используются только read-методы MTProto (`messages.GetHistory`, `messages.GetReplies`, `messages.Search`, `channels.GetFullChannel`, `messages.GetMessageReactionsList`).

## Инструменты

| Инструмент | Описание |
|---|---|
| `get_channel_info` | Метаданные канала: название, username, id, дата создания, описание, подписчики, закреплённый пост, доступные реакции, связанная группа обсуждений |
| `list_posts` | Последние посты: дата, текст в Markdown, просмотры, форварды, число комментариев, реакции, медиа, ссылка t.me |
| `get_post` | Один или несколько постов по id с полным текстом, медиа-метаданными и результатами опроса |
| `get_post_comments` | Ветка комментариев поста из связанной группы, с `reply_to_message_id` для вложенности |
| `search_channel` | Поиск по тексту (индекс Telegram) в постах или в комментариях |
| `get_reactions` | Разбивка реакций по эмодзи; опционально — кто именно поставил |
| `get_channel_stats` | Агрегаты: средние/медианные просмотры, реакции по эмодзи, комментарии, форварды, engagement rate, активность по дням/часам, топ-посты |
| `get_top_commenters` | Самые активные участники обсуждений: число комментариев, средняя длина, полученные реакции, период активности |

Аргумент `channel` во всех тулах опционален — если не передан, используется `TG_CHANNEL` из `.env`.

## Требования

- Node.js 18+
- `api_id` / `api_hash` с https://my.telegram.org → API development tools
- Telegram-аккаунт, который видит канал (для публичного канала подписка не обязательна)

## Установка

```bash
npm install
cp .env.example .env
# указать TG_API_ID, TG_API_HASH, API_KEY, TG_CHANNEL
npm run login          # одноразовая авторизация → выведет TG_SESSION
# скопировать TG_SESSION=... в .env
```

## Конфигурация (.env)

| Переменная | Назначение |
|---|---|
| `PORT` | Порт MCP-сервера (default `3200`) |
| `API_KEY` | Ключ доступа — клиенты передают в `X-API-Key` или `Authorization: Bearer <key>` |
| `TG_API_ID` | api_id с my.telegram.org |
| `TG_API_HASH` | api_hash с my.telegram.org |
| `TG_SESSION` | Строка сессии из `npm run login` |
| `TG_CHANNEL` | Канал по умолчанию: `@username`, ссылка `t.me/...` или `-100<id>` |
| `TG_FLOOD_SLEEP_THRESHOLD` | Сек: автоматически пересиживать `FLOOD_WAIT` короче этого значения (default `60`) |

## Запуск

```bash
npm start        # прод
npm run dev      # с автоперезапуском (--watch)
```

- MCP endpoint: `POST http://<host>:<PORT>/mcp` (требует API-ключ)
- Health check: `GET http://<host>:<PORT>/health` — проверяет соединение с Telegram и показывает аккаунт

## Подключение MCP-клиента

```json
{
  "mcpServers": {
    "telegram": {
      "url": "http://<host>:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}
```

## Замечания

- **`TG_SESSION` = полный доступ к аккаунту.** Держите его в секрете, не коммитьте, используйте отдельный аккаунт под аналитику.
- **Комментарии** существуют только если у канала подключена группа обсуждений. Без неё `get_post_comments` и `get_top_commenters` вернут понятную ошибку.
- **Числовые id** (`-100...`) резолвятся только если чат уже известен сессии; надёжнее указывать `@username`.
- **Флуд-лимиты:** тяжёлые тулы (`get_channel_stats`, `get_top_commenters`) листают историю страницами. Не выставляйте лимиты в максимум без необходимости; `FLOOD_WAIT` короче `TG_FLOOD_SLEEP_THRESHOLD` пересиживается автоматически.
- **Форматирование** постов конвертируется из Telegram entities в Markdown: `**bold**`, `_italic_`, `` `code` ``, ```` ```pre``` ````, `[text](url)`, `||spoiler||`, `~~strike~~`, цитаты — как markdown-blockquote.