Уведомления: логи и прогресс

Инструмент, который собирает отчёт по проекту, может работать минуту. Всё это время хост не знает, жив ли сервер, а пользователь смотрит на крутящийся индикатор. Уведомления решают эту проблему: сервер может по ходу дела сообщать «обработано 40 из 120 задач», не дожидаясь конца. К концу урока вы будете знать, чем уведомление отличается от запроса, как работает прогресс, что такое протокольное логирование, и какое из этого стоит применять сегодня.

Что такое уведомление

В JSON-RPC 2.0 есть три вида сообщений: запрос, ответ и уведомление. Уведомление — это запрос без id. Раз нет id, ответить на него невозможно, и получатель не должен пытаться. Это «выстрелил и забыл»:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": { "progressToken": "job-17", "progress": 40, "total": 120 }
}

Уведомления ходят в обе стороны, но в этом уроке нас интересуют те, что идут от сервера к клиенту. В ревизии 2026-07-28 они делятся на два класса. Уведомления, привязанные к запросу, — прогресс и логи — доставляются на том же потоке, что и ответ на этот запрос, и только до него. Уведомления об изменениях — «список инструментов изменился», «ресурс обновился» — доставляются на отдельном долгоживущем потоке, который клиент открывает запросом subscriptions/listen. Мы сосредоточимся на первом классе.

Прогресс

Прогресс — единственное уведомление, которое клиент должен явно запросить. Если хост хочет получать обновления по конкретному вызову, он кладёт в запрос токен:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "build_report",
    "arguments": { "sprint": "2026-09" },
    "_meta": { "progressToken": "job-17" }
  }
}

_meta — поле для метаданных, которое есть у любого запроса. Токен выбирает клиент; он должен быть строкой или числом и уникальным среди активных запросов. Дальше сервер может (но не обязан) слать уведомления с этим токеном:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "job-17",
    "progress": 40,
    "total": 120,
    "message": "Собираю задачи спринта"
  }
}

Правила простые. progress обязан расти от уведомления к уведомлению, даже если total неизвестен. total необязателен — когда сервер не знает, сколько всего работы, он его не указывает. Оба числа могут быть дробными. message — человекочитаемая строка для интерфейса. После завершения запроса уведомления с его токеном должны прекратиться. И обе стороны должны ограничивать частоту: уведомление на каждую из десяти тысяч строк — это не прогресс, а флуд.

Есть ещё одно тонкое свойство. Спецификация разрешает клиенту сбрасывать таймаут запроса при получении прогресса: раз пришло уведомление, сервер работает. Но общий максимальный таймаут клиент всё равно обязан соблюдать. Так что прогресс — это ещё и способ не быть убитым за медленную работу, но не индульгенция на бесконечную.

Прогресс в SDK

Серверу нужен объект Context. Объявите параметр с такой аннотацией в инструменте — SDK найдёт его по типу и подставит; в схему инструмента он не попадёт:

from mcp.server import MCPServer
from mcp.server.mcpserver import Context

mcp = MCPServer("reports")


@mcp.tool()
async def build_report(sprint: str, ctx: Context) -> str:
    """Собрать отчёт по спринту."""
    tasks = await load_tasks(sprint)
    total = len(tasks)
    for i, task in enumerate(tasks, start=1):
        await analyze(task)
        await ctx.report_progress(i, total, f"Задача {task.key}")
    return render(tasks)

report_progress(progress, total=None, message=None) — единственный метод, который вам нужен. Если клиент не прислал токен, вызов ничего не делает, так что проверять это самостоятельно не нужно.

На стороне клиента прогресс запрашивается для каждого вызова отдельно — колбэком в call_tool:

async def on_progress(progress: float, total: float | None, message: str | None) -> None:
    print(f"{progress}/{total}: {message}")

result = await client.call_tool("build_report", {"sprint": "2026-09"}, progress_callback=on_progress)

SDK сам сгенерирует токен и положит его в _meta.

Логи через протокол

Второй вид уведомлений — notifications/message. Сервер отправляет сообщение с уровнем важности, необязательным именем логгера и произвольными JSON-данными:

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "warning",
    "logger": "tracker",
    "data": { "message": "Трекер отвечает медленно", "latency_ms": 4200 }
  }
}

Уровни взяты из syslog: debug, info, notice, warning, error, critical, alert, emergency. Как клиент фильтрует, зависит от ревизии. В 2025-11-25 клиент один раз отправлял запрос logging/setLevel, и сервер дальше слал всё, что не ниже уровня. В 2026-07-28 фильтр стал частью запроса: клиент кладёт io.modelcontextprotocol/logLevel в _meta конкретного запроса, и только для этого запроса сервер может слать логи — на том же потоке, до ответа. Нет ключа в _meta — нет логов.

Вот что важно понимать: эти логи никогда не попадают в модель. Их получает клиент и может показать в панели, сохранить или проигнорировать. Модель видит только то, что инструмент вернул.

В SDK v2 методы ctx.info(), ctx.debug(), ctx.warning(), ctx.error() и общий ctx.log(level, data, logger_name=...) сохранились, но помечены как устаревшие и при вызове выдают MCPDeprecationWarning. На стороне клиента их принимает logging_callback, причём на современном протоколе нужно ещё указать log_level в конструкторе Client, иначе клиент ничего не запросит и ничего не получит.

Почему логирование устарело, а прогресс нет

С ревизии 2026-07-28 логирование через протокол помечено устаревшим (SEP-2577). Рекомендованная замена — обычный logging Python: в stdio-сервере он пишет в stderr, который хост может собрать, а для продакшена — OpenTelemetry. Логика такая: логи нужны оператору сервера, а не пользователю хоста, и тащить их через протокол в хост — не та точка назначения. Ещё одна причина: на HTTP-транспорте с несколькими экземплярами сервера «канал к клиенту» перестал быть чем-то определённым.

Прогресс — другое дело. Он нужен именно пользователю хоста, привязан к конкретному запросу и не требует от сервера ничего помнить. Поэтому он остался и остаётся основным способом показать, что долгая операция идёт.

Практический вывод для нового сервера: ctx.report_progress() для прогресса, logging.getLogger(__name__) для логов. Методы ctx.info() и его братья — только если вы сознательно поддерживаете старые хосты и вам нужно, чтобы сообщения были видны в их интерфейсе.

Уведомления об изменениях

Ради полноты — второй класс. Когда у сервера меняется набор инструментов (например, после логина пользователя стали доступны новые), он может сообщить об этом клиенту уведомлением notifications/tools/list_changed, и клиент перезапросит tools/list. Есть аналоги для промптов и ресурсов, а также notifications/resources/updated для конкретного ресурса.

В 2026-07-28 такие уведомления не приходят сами: клиент открывает подписку запросом subscriptions/listen с фильтром (toolsListChanged: true и так далее), сервер подтверждает её и дальше шлёт только запрошенное. В SDK на стороне сервера это await ctx.notify_tools_changed(). Нам это понадобится в уроке про состояние, когда речь пойдёт о нескольких экземплярах сервера.