Async MCP server с job queue: почему polling, а не блокирующий вызов
Наивный MCP-сервер держит соединение, пока идёт работа, — и долгие операции упираются в таймауты. Async MCP server кладёт их в очередь задач и сразу отдаёт job ID: браузерная автоматизация, ML-инференс и обход страниц масштабируются горизонтально, а клиент опрашивает статус по ID.
Проблема
Наивный MCP-сервер делает работу синхронно: агент вызывает tool — ждёт ответа. Для быстрых операций норма. Для долгих (анализ сайта браузерной автоматизацией, ML-инференс, обход страниц) — блокировка: таймауты на стороне клиента, нет горизонтального масштабирования, один тяжёлый запрос держит соединение открытым. Анализ сайта Playwright'ом занимает десятки секунд; MCP-клиент столько не ждёт.
Методика
Разнести submit и результат: async job queue с poll-by-ID.
-
1. Submit возвращает job ID мгновенно
(
202), не блокируя. Статус опрашивается отдельным вызовомGET /job/:id. -
2. Playwright в контейнере делает фактический анализ
(design tokens: цвета, типографика, спейсинг, компоненты) — изолированно, headless, с
--no-sandboxпод контейнерного пользователя;node_modulesхоста явно исключён из образа. - 3. BullMQ поверх Redis — персистентность задач, ретраи и ограничение конкурентности. Не самописная очередь: ретраи, backoff и ретенция — из коробки.
- 4. MCP-сервер на 3001 отдельно от REST на 3000: мультипротокол (HTTP / HTTPS / stdio) под разные сценарии деплоя и интеграцию с Cursor.
Очередь — это не «Redis как хранилище», а конфиг с осознанными дефолтами:
// config/queue.ts — defaultJobOptions
{
attempts: 3, // 3 попытки на job, не one-shot
backoff: { type: 'exponential', delay: 2000 }, // 2s → 4s → 8s
removeOnComplete: { age: 3600, count: 1000 }, // успешные: 1ч или 1000 шт
removeOnFail: { age: 86400 }, // упавшие: 24ч (для разбора)
}
export const maxConcurrentJobs =
parseInt(process.env.MAX_CONCURRENT_ANALYSES || '5', 10);
5 — не магия: один
Playwright-Chromium в headless стоит ~150–250 МБ RSS плюс CPU на рендер; пять параллельных
браузеров — верхняя граница, которую держит скромная одноядерная VM без свопа и OOM-kill.
Меняется одной переменной среды под железо. Ретраящийся job занимает
слот всё это время — при attempts: 3
и backoff это надо закладывать в ёмкость.
Воркер — тонкий, вся логика в job-процессоре; graceful shutdown обязателен, иначе SIGTERM убивает браузер посреди анализа:
// src/worker.ts
const worker = new Worker('website-analysis',
async (job) => { await processWebsiteAnalysis(job); },
{ ...queueConfig, concurrency: maxConcurrentJobs });
worker.on('failed', (job, err) =>
logger.error({ jobId: job?.id, error: { message: err?.message, code: (err as any)?.code } },
'Analysis job failed'));
process.on('SIGTERM', async () => { await worker.close(); process.exit(0); });
Внутри анализа — бюджет времени, а не один таймаут.
networkidle капается 30
секундами, на остаток общего бюджета падаем в более мягкий
load:
const networkIdleTimeout = Math.min(ANALYSIS_TIMEOUT, 30000); // ANALYSIS_TIMEOUT=60000
try {
await page.goto(url, { waitUntil: 'networkidle', timeout: networkIdleTimeout });
} catch {
logger.warn(logContext, 'networkidle timeout, falling back to load');
await page.goto(url, { waitUntil: 'load', timeout: ANALYSIS_TIMEOUT - networkIdleTimeout });
}
networkidle на
аналитике/трекерах не наступает никогда — глухой таймаут был бы ложным failure. Fallback на
load вытягивает такие сайты,
теряя часть поздней подгрузки. Ошибки при этом разведены по смыслу, а не свалены в «failed»:
Website load timeout (страница
не уложилась в бюджет),
Website inaccessible
(net::ERR_*), и bot-protection
(cloudflare/captcha) — на последнее warn, но продолжаем:
часть токенов извлечь можно и с заглушки. Экстракция ограничена
MAX_ELEMENTS=10000, чтобы
тяжёлый DOM не выел память и время.
Жизненный цикл job и что на самом деле значит 404
POST /analyze → 202 {"job_id": "abc123"}
GET /job/abc123 → 200 {"status": "in-progress"}
GET /job/abc123 → 200 {"status": "completed", "result_location": "..."}
GET /job/abc123 → 404 # спустя ~5с после завершения
Важная деталь, в которой легко соврать:
404 возвращается
не по факту чтения. Status-эндпоинт на
GET ничего не удаляет — он
читает ключ job:status:<id>
из Redis. Удаляет ключ job-процессор, таймером через 5 секунд
после терминального статуса:
await updateJobStatus(jobId, 'completed', { result_location: designSystemPath });
setTimeout(() => deleteJobStatus(jobId), 5000); // окно на забор результата
То есть в окне 5с можно поллить сколько угодно раз и стабильно получать
200 completed.
404 = «job завершился больше
~5с назад или не существовал». Это не «забери с первого
раза» — это «забери в течение окна».
Артефакт
github.com/dobryakov/design-system-mcp (TypeScript, Docker/Compose, BullMQ, Playwright E2E, Jest — unit / integration / e2e разнесены). 8★ / 4 forks — единственный репо серии с независимой валидацией сообществом.
Production-разводка сервисов:
# docker-compose.yml
services:
redis:
image: redis:7-alpine
volumes: [ redis-data:/data ] # очередь переживает рестарт
healthcheck: { test: ["CMD", "redis-cli", "ping"] }
api:
build: .
ports: [ "${PORT:-3000}:3000", "${MCP_PORT:-3001}:3001" ] # REST + MCP раздельно
environment:
- MAX_CONCURRENT_ANALYSES=${MAX_CONCURRENT_ANALYSES:-5}
- REDIS_URL=${REDIS_URL:-redis://redis:6379}
depends_on: { redis: { condition: service_healthy } }
volumes: { redis-data: {} }
Где ломается
-
Окно ретенции статуса — таймер, а не read-triggered.
5 секунд захардкожены. Клиент, который поллит с интервалом >5с (медленная сеть,
throttling), пропустит терминальный статус целиком и
увидит только
404, не отличив «готово» от «не было». Это дизайн-смелл: удаление должно бы зависеть от факта доставки, а не от стенных часов.
Митигация (что уже есть в коде): authoritative-запись живёт не в этом ключе. BullMQ держит job —removeOnComplete {age: 3600}(успешные — час),removeOnFail {age: 86400}(упавшие — сутки). Эфемерный status-ключ — это convenience-кэш поверх очереди; устойчивый клиент читает состояние job из BullMQ, где оно переживает окно. В проде я бы либо расширял окно до порядка poll-интервала клиента, либо отдавал терминальный статус из BullMQ, а 5-секундный ключ оставлял только оптимизацией «горячего» пути. - Stateless-контракт vs удобство потребителя. Сервер сознательно не копит состояние результата в status-ключе — простота и отсутствие утечки памяти на брошенных job. Плата — контракт «забери в окне». Выбор осознанный: для агента-потребителя (Cursor поллит плотно) окна хватает; для интеграции с редким поллингом — читать из очереди. Не «баг», а явная граница, под которую проектируется клиент.
-
Max 5 concurrent + ретраи.
Защита от OOM, но при всплеске job встают в очередь, а каждый ретраящийся
(
attempts: 3, exp backoff) держит слот до победы или исчерпания попыток. Нужен backpressure-контракт на стороне клиента и мониторинг глубины очереди.
Что мониторить, чтобы поймать деградацию по сигналу, а не по жалобе: (1) глубинаwaitingв BullMQ → всплеск = упёрлись в concurrency; (2) частотаfailed-событий воркера и число записей вremoveOnFail-хвосте (они для того и живут 24ч); (3) доля warnnetworkidle timeout, falling back to load→ целевые сайты тяжелеют; (4) исчерпаниеmaxRetriesPerRequest: 3на Redis-коннекте → здоровье Redis. - Bot-protection не блокирует, а деградирует молча. На cloudflare/captcha — warn и продолжаем, отдавая частичные токены. Риск: «успешный» результат по заглушке. Митигация: флаг в результате о сработавшем bot-индикаторе, чтобы потребитель отличал полную экстракцию от частичной.
Для кого и почему
Паттерн «async submit + poll + осознанный stateless-trade-off» — архитектурный, не туториальный. Разговор здесь не про «как сделать очередь», а про то, где проходят границы: ретенция статуса, ёмкость под ретраи, деградация вместо отказа. 8★ дают независимое подтверждение, что тема резонирует с технической аудиторией — сильнейший по внешней валидации пункт серии.
Читать дальше
Об авторе
Григорий Добряков — fractional / interim eng + AI leadership
Хотите выстроить MCP-инфраструктуру под долгие операции?
Проектирование async job queue, stateless trade-off и backpressure-контракта для агентного workflow в вашей команде.
Обсудить fractional-аудит Написать на почтуДругие разборы
Серия инженерных разборов: реальная задача → методика → работающий артефакт → честный разбор, где он ломается.
К серии →