Async MCP server с job queue: почему polling, а не блокирующий вызов | Григорий Добряков

Григорий Добряков

Howto · разбор

Разбор 04 GitHub · 8 stars · 4 forks

Async MCP server с job queue: почему polling, а не блокирующий вызов

Наивный MCP-сервер держит соединение, пока идёт работа, — и долгие операции упираются в таймауты. Async MCP server кладёт их в очередь задач и сразу отдаёт job ID: браузерная автоматизация, ML-инференс и обход страниц масштабируются горизонтально, а клиент опрашивает статус по ID.

CTO Head of AI Architect Tech Lead

Проблема

Наивный MCP-сервер делает работу синхронно: агент вызывает tool — ждёт ответа. Для быстрых операций норма. Для долгих (анализ сайта браузерной автоматизацией, ML-инференс, обход страниц) — блокировка: таймауты на стороне клиента, нет горизонтального масштабирования, один тяжёлый запрос держит соединение открытым. Анализ сайта Playwright'ом занимает десятки секунд; MCP-клиент столько не ждёт.

Методика

Разнести submit и результат: async job queue с poll-by-ID.

  1. 1. Submit возвращает job ID мгновенно (202), не блокируя. Статус опрашивается отдельным вызовом GET /job/:id.
  2. 2. Playwright в контейнере делает фактический анализ (design tokens: цвета, типографика, спейсинг, компоненты) — изолированно, headless, с --no-sandbox под контейнерного пользователя; node_modules хоста явно исключён из образа.
  3. 3. BullMQ поверх Redis — персистентность задач, ретраи и ограничение конкурентности. Не самописная очередь: ретраи, backoff и ретенция — из коробки.
  4. 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: {} }

Где ломается

Для кого и почему

Паттерн «async submit + poll + осознанный stateless-trade-off» — архитектурный, не туториальный. Разговор здесь не про «как сделать очередь», а про то, где проходят границы: ретенция статуса, ёмкость под ретраи, деградация вместо отказа. 8★ дают независимое подтверждение, что тема резонирует с технической аудиторией — сильнейший по внешней валидации пункт серии.

Об авторе

Григорий Добряков — fractional / interim eng + AI leadership

Хотите выстроить MCP-инфраструктуру под долгие операции?

Проектирование async job queue, stateless trade-off и backpressure-контракта для агентного workflow в вашей команде.

Обсудить fractional-аудит Написать на почту

Другие разборы

Серия инженерных разборов: реальная задача → методика → работающий артефакт → честный разбор, где он ломается.

К серии →