Notification MCP

Локальный MCP-сервер с общим интерфейсом уведомлений. Нейросеть или другое приложение передаёт событие и текст; сервер выбирает канал и получателя из TOML-настроек.

Реализованы Telegram Bot API и файл JSONL для автономной проверки. Файловый канал записывает результат на диск: он не показывает системный баннер и не издаёт звук.

Возможности и границы

• notify принимает уведомление в SQLite и возвращает его ID и состояние queued.

• notification_status возвращает queued, sending, sent или failed.

• Фоновый обработчик отправляет сообщения, повторяет временные ошибки с увеличением задержки и учитывает retry_after Telegram. Ошибки 400/401/403 автоматически не повторяются.

• При повторе с тем же idempotency_key и содержимым возвращается прежняя запись. Другое содержимое с занятым ключом отклоняется. Ключи общие для базы: включайте в них проект и задачу.

• Очередь и ограничения частоты отправки сохраняются на диске. Прерванные отправки восстанавливаются при запуске. Одну базу обслуживает только один процесс отправки; блокировка ОС освобождается и при аварийном завершении.

• Имя канала, его тип и получатель фиксируются при постановке в очередь. Изменение маршрутов или chat_id не перенаправляет старые уведомления.

• Токен можно один раз указать в config.toml; переменные окружения также поддерживаются. Сам токен не сохраняется в очереди и не выводится в логи. Очередь содержит текст уведомления и адрес получателя; храните её как локальные рабочие данные.

• /start привязывает чат Telegram и сохраняет его в SQLite. Первое подключение — в личном чате; затем менять получателя может только этот пользователь. MCP-инструменты остаются общими.

• sent означает подтверждение Telegram API либо успешную запись в файл, а не прочтение человеком.

После временного обрыва связи отправка продолжится, если сервер работает и попытки ещё остались. После исчерпания max_attempts запись получает failed. Для повторной отправки после устранения причины создайте уведомление с новым ключом. Постоянной гарантии доставки нет: при обрыве после приёма сообщения Telegram, но до записи подтверждения, повтор может создать дубликат. Идемпотентность постановки в очередь не устраняет эту неоднозначность внешнего API.

Related MCP server: notify-hub

Установка

Нужны Python 3.11+ и uv. Из корня проекта:

uv sync --locked

Зависимости устанавливаются в .venv проекта. Облачный аккаунт, Cloudflare и личная Telegram-сессия не нужны. Для запуска только сервера без средств разработки: uv sync --locked --no-dev.

1. Проверка без Telegram и интернета

После установки зависимостей скопируйте диагностический конфиг и запустите сервер:

Copy-Item config.local.example.toml config.local.toml
uv run --frozen notification-mcp --config config.local.toml check-config
uv run --frozen notification-mcp --config config.local.toml serve

Оставьте терминал работающим. Во втором терминале из корня проекта:

uv run --frozen python scripts/check_mcp.py
Get-Content var/check-notifications.jsonl -Encoding utf8

Проверочный клиент выполняет MCP handshake, обнаруживает инструменты, вызывает notify и ожидает sent. В JSONL должна появиться строка с тем же id и текстом проверки. Скрипт имеет таймаут 30 секунд; при failed или таймауте завершится с ошибкой. Для локального MCP-соединения скрипт не использует системные переменные HTTP-прокси. Проверка отправляет одно настоящее уведомление через текущий канал, поэтому с Telegram-конфигом сообщение придёт в Telegram.

Для полностью автономного запуска уже установленной версии можно обращаться прямо к .venv\Scripts\notification-mcp.exe и .venv\Scripts\python.exe, не запуская менеджер пакетов.

2. Настройка Telegram

1. Создайте бота через @BotFather и получите токен.

2. Если config.toml ещё нет, скопируйте пример:

Copy-Item config.example.toml config.toml

3. Откройте config.toml и один раз укажите токен:

[channels.personal]
type = "telegram"
bot_token = "ВСТАВЬТЕ_ТОКЕН_ОТ_BOTFATHER"

При переходе со старого конфига замените строку bot_token_env на bot_token и удалите строку chat_id, чтобы включить настройку через /start. Остальные секции оставьте как есть. Токен хранится открытым текстом в локальном файле; config.toml уже включён в .gitignore.

4. Остановите прежний сервер через Ctrl+C, если он занимает порт 8765, и запустите:

uv run --frozen notification-mcp --config config.toml check-config
uv run --frozen notification-mcp --config config.toml serve

check-config проверяет настройки и наличие токена, но не обращается к Telegram. Сервер выводит имя бота после успешного подключения. Оставьте терминал работающим.

5. Откройте личный чат с ботом и отправьте /start. Дождитесь ответа «Чат подключён. Новые уведомления будут приходить сюда».

6. Во втором терминале выполните:

uv run --frozen python scripts/check_mcp.py

Ожидаются status: sent и тестовое уведомление от бота. Перезапустите сервер и повторите проверку: вводить токен или отправлять /start снова не нужно. Сохраняйте config.toml и базу из [storage]. До первого /start уведомление для этого Telegram-канала отклоняется с понятной ошибкой; остальные каналы продолжают работать.

Выбор другого чата: после первого подключения отправьте /start от того же аккаунта в нужной группе, куда добавлен бот. Для группы с несколькими ботами используйте /start@имя_вашего_бота. Вернуть уведомления в личный чат можно командой /start там же. Бот должен иметь право писать в выбранную группу. Темы форумов и каналы Telegram через /start в этой версии не настраиваются. Меняются только получатели новых уведомлений.

Первый пользователь, отправивший /start в личном чате, становится владельцем привязки, поэтому выполните первое подключение сами до передачи ссылки на бота другим людям. Команды других пользователей, пересланные сообщения и анонимные команды группы игнорируются.

Используйте отдельного бота: сервер получает команды через long polling getUpdates. Другой потребитель getUpdates или установленный webhook вызывает конфликт; сервер сообщит об этом в журнале и повторит подключение. Чужой webhook автоматически не удаляется. При обрыве связи приём /start восстанавливается автоматически; позиция обработки сохраняется.

Прежний способ остаётся доступен: вместо bot_token можно использовать bot_token_env = "TELEGRAM_BOT_TOKEN" и задавать переменную окружения. При наличии обоих полей приоритет у bot_token. Если указан chat_id = "123456789", получатель фиксирован настройками и обработчик /start для этого канала отключён. Для одного бота разрешён один автоматически настраиваемый канал; дополнительные фиксированные получатели могут использовать того же бота.

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

Основной режим — самостоятельный локальный сервер Streamable HTTP:

http://127.0.0.1:8765/mcp

Добавьте этот URL в настройки HTTP MCP-сервера своего клиента. Во многих клиентах используется:

{
  "mcpServers": {
    "notifications": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Конкретное имя поля транспорта зависит от клиента. Сервер поддерживает только loopback-адреса, проверяет HTTP Host и Origin; аутентификации локальных приложений в этой версии нет. Не публикуйте этот endpoint через прокси или туннель. Проверка состояния:

Invoke-RestMethod http://127.0.0.1:8765/health

Для клиентов, умеющих только stdio, команда запуска:

F:\Portfolio\notification-mcp\.venv\Scripts\notification-mcp.exe

Аргументы:

["--config", "F:\\Portfolio\\notification-mcp\\config.toml", "serve", "--transport", "stdio"]

При переносе проекта замените пути. С bot_token в конфиге окружение процесса настраивать не нужно. В stdio обработчик существует только пока жив клиент: после закрытия клиента записи сохраняются, но отправка возобновится только при следующем запуске. Одновременно запускать HTTP и stdio с одной базой нельзя. Для нескольких клиентов используйте один HTTP-сервер.

Рекомендуемое правило для агента:

Используй notify, когда требуется моё решение (action_required), работа готова к проверке (review_requested) или возникла ошибка, требующая внимания (error). Указывай проект/задачу в source, кратко объясняй нужное действие. Для одного события повторно используй тот же idempotency_key. queued означает принятие в очередь; не называй его доставкой.

MCP не отслеживает задачи самостоятельно: агент или вызывающее приложение должно вызвать инструмент.

Общий контракт и выбор канала

Аргументы notify:

{
  "message": "Реализация готова. Нужно проверить результат.",
  "event": "review_requested",
  "title": "Задача завершена",
  "source": "portfolio / задача-42",
  "url": "https://example.com/result",
  "idempotency_key": "portfolio:42:ready:v1"
}

Обязателен только message. События: info, action_required, review_requested, error. Ограничения: сообщение — 3000 символов, заголовок и источник — по 160, URL — 500. При выборе Telegram весь сформированный текст дополнительно ограничен 4096 единицами UTF-16. Текст отправляется без Markdown/HTML-разметки.

Пример выбора разных каналов настройками:

[routing]
default_channel = "local"

[routing.events]
action_required = "personal"
review_requested = "personal"
error = "personal"

[channels.local]
type = "file"
path = "var/events.jsonl"

[channels.personal]
type = "telegram"
bot_token = "ВСТАВЬТЕ_ТОКЕН_ОТ_BOTFATHER"
# Получатель выбирается через /start.

Изменения конфигурации применяются после перезапуска и влияют на новые уведомления. Для старых сохраняется снимок канала, включая получателя и идентификатор бота, без самого токена. Ротация токена того же бота поддерживается после перезапуска; другой бот не получает его очередь. Для уведомлений, поставленных старой версией без идентификатора бота, до завершения очереди оставляйте прежнюю переменную токена доступной. Существующая база обновляется автоматически. Все относительные пути считаются от расположения TOML, а не от текущей папки терминала.

Проверка очереди и повторов

Сохранение при остановленном сервере: остановите сервер, выполните команду ниже, сохраните notification.id из ответа, затем снова запустите сервер с тем же конфигом.

uv run --frozen notification-mcp --config config.local.toml notify --message 'Проверка сохранения очереди' --idempotency-key 'manual:restart:1'
uv run --frozen notification-mcp --config config.local.toml status ВСТАВЬТЕ_ID

До запуска сервера ожидается queued, после запуска — sent и строка в файле. Повтор той же команды с тем же ключом не создаёт второй записи.

Обрыв связи с Telegram: при работающем Telegram-сервере временно отключите сеть, поставьте уведомление через локальный MCP либо CLI с --config config.toml, затем восстановите связь до исчерпания попыток. В status ожидается queued с ошибкой соединения и следующей попыткой, затем sent. Для этого теста локальный HTTP MCP и CLI доступны и без интернета; облачная нейросеть при отключённой сети может быть недоступна.

Автоматические проверки без внешних отправок:

uv run --frozen pytest -q
uv run --frozen ruff check .
uv run --frozen ruff format --check .

Проверяются маршрутизация, валидация, сохранение и восстановление очереди, идемпотентность, ограничение попыток, таймауты, retry_after, изоляция каналов, ошибки Telegram через HTTP-заглушки, MCP handshake, вызовы инструментов и защита Host/Origin. Тесты не обращаются к Telegram. Также проверяются сохранение токена в конфиге, привязка /start, смена чата только владельцем, восстановление позиции polling после перезапуска и отсутствие токена в записях очереди.

Структура и расширение

src/notification_mcp/
  models.py       общие события и результаты
  config.py       настройки и маршруты
  channels.py     независимые адаптеры Telegram и файла
  telegram.py     получение /start и настройка получателя Telegram
  store.py        SQLite-очередь
  worker_lock.py  единственный обработчик для каждой базы
  service.py      постановка в очередь и повторные попытки
  server.py       MCP-инструменты и HTTP/stdio
  cli.py          запуск, локальная постановка и просмотр состояния

Новый канал: добавьте модели настроек/назначения в config.Channel и config.Destination, адаптер с validate и send, зарегистрируйте его в ADAPTER_TYPES и в фабрике отправителей NotificationService.running. notify, очередь и вызывающие приложения менять не требуется. Ошибки адаптеров должны использовать DeliveryError с безопасным текстом, признаком повторяемости и при необходимости минимальной задержкой retry_after.

SQLite, файлы назначения и lock-файл должны находиться на локальном диске. Автозапуск как служба, приём ответов на уведомления из Telegram, ручная очистка/архивация очереди и дополнительные каналы в текущую версию не входят. История сохраняется до обслуживания базы владельцем.

Основа

Проект использует официальный Python MCP SDK и FastMCP из него — тот же подход к MCP, что и у chigwell/telegram-mcp. Исходники chigwell не копировались; Telethon и Telegram-сессии не используются. Отправка реализована через Telegram Bot API.