<p align="center">
  <img src="assets/banner.svg" alt="Telegram Bot — a private MCP connection for ChatGPT and Codex" width="100%" />
</p>

<p align="center">
  <a href="https://github.com/Evr1kys/telegram-bot/actions/workflows/tests.yml"><img src="https://github.com/Evr1kys/telegram-bot/actions/workflows/tests.yml/badge.svg" alt="Tests" /></a>
  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+" />
  <img src="https://img.shields.io/badge/Protocol-MCP-74D9DE" alt="Model Context Protocol" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-A3E635" alt="MIT license" /></a>
</p>

<p align="center">
  <strong>Читайте разрешённые чаты. Публикуйте от имени бота. Управляйте доступом.</strong><br />
  Локальный плагин Telegram Bot API для ChatGPT, Codex и других MCP-клиентов.
</p>

<p align="center">
  <a href="#быстрый-старт">Быстрый старт</a> ·
  <a href="docs/SETUP.ru.md">Настройка</a> ·
  <a href="docs/README.en.md">English</a> ·
  <a href="https://github.com/Evr1kys/telegram-bot/releases">Релизы</a>
</p>

---

## Что умеет

| Возможность | Как работает |
| :--- | :--- |
| **Читать обновления** | Новые сообщения, правки и посты каналов, доступные боту |
| **Проверять чат** | Базовые сведения по разрешённому числовому ID |
| **Публиковать текст** | Отправка сообщений, в том числе в темы форум-групп |
| **Работать с несколькими каналами** | Отдельные списки ID для чтения и отправки |
| **Предотвращать повторные попытки** | Сохранённый `request_id` не запускает ту же отправку повторно |
| **Сохранять состояние** | Локальная SQLite-база с событиями, позицией чтения и журналом отправок |

> **Статус: MVP.** Реализован и протестирован локальный MCP-сервер. Для работы настройте собственного бота и подключение клиента. История личного аккаунта, вложения и автоматический планировщик не входят в текущую версию.

## Быстрый старт

Нужны **Python 3.11+**, **[uv](https://docs.astral.sh/uv/getting-started/installation/)** и бот, созданный через [@BotFather](https://t.me/BotFather). Запуск рассчитан на macOS/Linux.

```sh
git clone https://github.com/Evr1kys/telegram-bot.git
cd telegram-bot
uv sync --locked
uv run --locked python scripts/configure.py
```

Мастер настройки попросит токен скрытым вводом и числовые ID чатов. Токен хранится вне репозитория в файле с правами `600`. Можно вместо файла внедрить `TELEGRAM_BOT_TOKEN` через менеджер секретов. **Не вставляйте токен в разговор с моделью.**

Затем подключите сервер:

| Клиент | Подключение |
| :--- | :--- |
| **Codex / локальный MCP-клиент** | Команда `sh`, аргумент — абсолютный путь к `scripts/start.sh` |
| **ChatGPT** | Частный stdio-сервер через Secure MCP Tunnel; нужны доступ и настройка аккаунта |

Пошаговые инструкции, переменные окружения и разбор ошибок — в **[руководстве по настройке](docs/SETUP.ru.md)**. Само клонирование не подключает Telegram к ChatGPT.

## Три инструмента

| Инструмент | Назначение | Основные параметры |
| :--- | :--- | :--- |
| `read_updates` | Прочитать события разрешённых чатов | `after_update_id`, `limit`, `poll` |
| `get_chat` | Получить сведения о чате | `chat_id` |
| `send_message` | Отправить разрешённое пользователем сообщение | `chat_id`, `text`, `request_id` |

<details>
<summary><strong>Примеры запросов и аргументов</strong></summary>

- «Покажи новые сообщения из разрешённых Telegram-чатов».
- «Проверь название и тип чата с ID −1001234567890».
- «Отправь в канал −1001234567890: Встреча сегодня в 18:00».

Пример аргументов отправки после поручения пользователя:

```json
{
  "chat_id": -1001234567890,
  "text": "Встреча сегодня в 18:00",
  "request_id": "meeting_20260916_001"
}
```

Параметр `message_thread_id` позволяет указать тему форума. Сохраняйте тот же `request_id` при повторном вызове одного запроса. Новый ID — новая попытка отправки.

</details>

## Контроль доступа и отправки

**Доступ закрыт по умолчанию.** Чтение и отправка разрешаются отдельно для конкретных числовых ID. Плагин использует отдельного бота и не входит в личный аккаунт Telegram.

**Секреты остаются в окружении сервера.** Токен не входит в manifest, аргументы инструментов или сообщения об ошибках. Локальный сервер работает через stdio и не открывает сетевой порт.

**Неопределённая доставка не повторяется автоматически.** При таймауте состояние сохраняется как `uncertain`, при прерывании может остаться `pending`. Нужно проверить Telegram; нельзя обходить эту защиту новым идентификатором. Защита зависит от сохранности общей базы состояния.

**Текст из чатов — данные.** Skill запрещает воспринимать сообщения Telegram как инструкции, менять по ним разрешения или публиковать без поручения пользователя.

Подробнее: [модель безопасности](SECURITY.md) · [статусы и ограничения](docs/SETUP.ru.md#ошибки-и-повторная-отправка).

## Как устроено

```mermaid
flowchart LR
    A[ChatGPT / Codex] -->|MCP| B[Три инструмента]
    B --> C[Проверка разрешений]
    C --> D[Telegram Bot API]
    C <--> E[(SQLite: события и отправки)]
```

```text
src/telegram_bot/
├── config.py      # Секреты и списки разрешённых чатов
├── client.py      # Ограниченный клиент Bot API
├── store.py       # Состояние и блокировки SQLite
├── service.py     # Чтение и защита отправки от повторов
└── server.py      # MCP-инструменты
```

Слой `Service` отделён от MCP: поверх него можно добавить планировщик и очередь заданий. Несколько каналов одного владельца уже поддерживаются; изоляция нескольких владельцев требует дальнейшей разработки.

## Разработка

```sh
uv sync --locked
uv run --locked python -m unittest discover -s tests -v
```

Тесты проверяют доступ, фильтрацию, перезапуски, конкурентные отправки, ошибки Telegram и настоящий обмен MCP через stdio. Telegram HTTP заменён имитацией: тестам не нужны токены, они не отправляют сообщения.

GitHub Actions запускает тесты на Python 3.11, 3.12 и 3.13. Порядок внесения изменений: [CONTRIBUTING.md](CONTRIBUTING.md).

## Дальнейшее развитие

- [x] Три MCP-инструмента и отдельные разрешения
- [x] Несколько каналов одного владельца
- [x] Сохранение состояния и защита повторных вызовов
- [ ] Очередь публикаций с расписанием, лимитами и паузой
- [ ] Отправка вложений
- [ ] Раздельные учётные записи владельцев
- [ ] Публичный HTTP-сервер с аутентификацией

Планы не означают, что эти функции уже доступны. Идеи и воспроизводимые ошибки можно оставить в [Issues](https://github.com/Evr1kys/telegram-bot/issues).

---

[MIT License](LICENSE) · Автор: [Evr1kys](https://github.com/Evr1kys) · Независимый проект, не официальный продукт Telegram или OpenAI.