Заезд

Движок поездок, который начинается с повода. Человек не знает, куда ехать, он знает, зачем: хочет на конференцию по своей теме. Заезд находит ближайшее офлайн-событие, считает дорогу туда и обратно, отель рядом с площадкой и полную цену участия, и показывает до трёх объяснимых пакетов на одном экране.

Первая вертикаль - ИТ-конференции. Каталог событий даёт confcal MCP, транспорт и жильё - Tutu MCP, а собирает всё детерминированный композитор, а не модель.

Что где

Related MCP server: trip-planner-mcp

Сквозной сценарий

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

Нажимаете "Собрать ссылки на оплату" - появляется чек-лист из двух-трёх ссылок Туту. Подпись каждой берётся из того, что Туту реально вернул: "Открыть корзину" там, где откроется корзина, и "Открыть страницу выбора" там, где корзины не будет.

То же самое агенту: find_event_trips с темой и городом отправления возвращает ту же поездку структурой, get_trip_details раскрывает пакет, create_trip_checkout собирает чек-лист. Хост, который умеет рисовать, получает тот же экран как MCP App.

Запуск из исходников

npm install
ZAEZD_MODE=replay npm run dev

Откроется http://localhost:8080. В режиме replay продукт работает на записанных ответах из fixtures/ и не ходит в сеть: с ним можно жить без интернета и без ключей, а опорной датой служит день записи. Живой режим - ZAEZD_MODE=live.

Проверка целиком:

npm run verify

Это синхронность правил, сверка документированных команд, типизация, линтер, сборка браузерного дерева, исполняемые сценарии на Gherkin и юнит-тесты. Всё офлайн.

Браузерное дерево собирается до сценариев не для красоты. Один сценарий запрашивает у сервера тот самый boot.js, который уезжает в хост, и на чистом клоне этого файла ещё нет.

Запуск в контейнере

Образ собирается из репозитория и внутри содержит и код, и фикстуры, поэтому в режиме replay контейнеру не нужен ни интернет, ни секреты.

cp .env.example .env      # и отредактируйте
docker compose up -d --build

Экран поднимется на http://127.0.0.1:8080. Без файла .env compose не стартует: это намеренно, чтобы никто не запустил продукт на чужих значениях по умолчанию.

Без compose то же самое одной командой:

docker build -t zaezd .
docker run -d --name zaezd -p 127.0.0.1:8080:8080 --env-file .env zaezd

Разово, без файла окружения, чтобы просто посмотреть:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e ZAEZD_MODE=replay -e ZAEZD_PUBLIC_URL=http://localhost:8080 zaezd

Переменные окружения

Полный список с комментариями лежит в .env.example. Коротко:

Ключей и токенов нет ни одного: оба источника открытые. Значение ZAEZD_PUBLIC_URL важно задать честно - именно этот адрес уезжает агенту как ссылка на экран и попадает в CSP виджета, и если он не совпадает с реальным, доска внутри хоста останется пустой.

Контейнер несёт HEALTHCHECK на /healthz, так что docker ps показывает healthy только когда приложение действительно отвечает.

За обратным прокси

Сам docker-compose.yaml ничего не знает про прокси, домены и сети - это свойства площадки, а не продукта. Всё это кладётся в docker-compose.override.yaml, он в гитигноре и живёт только на той машине, которая разворачивает сервис. Пример для Traefik:

services:
  zaezd:
    ports: !reset []          # наружу светит прокси, а не контейнер
    environment:
      ZAEZD_PUBLIC_URL: https://zaezd.example.com
    labels:
      traefik.enable: 'true'
      traefik.http.routers.zaezd.rule: Host(`zaezd.example.com`)
      traefik.http.routers.zaezd.entrypoints: https
      traefik.http.routers.zaezd.tls: 'true'
      traefik.http.routers.zaezd.tls.certresolver: letsencrypt
      traefik.http.services.zaezd.loadbalancer.server.port: '8080'
    networks: [proxy]

networks:
  proxy:
    external: true

Имена точки входа, резолвера сертификатов и сети у всех разные, поэтому в примере они подставные. Для nginx или Caddy override будет другим, продукт от этого не меняется: он слушает PORT и отдаёт /healthz.

Подключить к агенту

Эндпоинт <адрес>/mcp работает по streamable HTTP и не требует ключа. Локально это http://localhost:8080/mcp, на развёрнутом сервисе - ваш адрес из ZAEZD_PUBLIC_URL.

Claude Desktop не принимает удалённые серверы прямо в claude_desktop_config.json, там живут только stdio-команды, поэтому либо добавьте Заезд через Settings, Connectors, Add custom connector, либо пропишите проксирующий запуск:

{
  "mcpServers": {
    "zaezd": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"] }
  }
}

Claude Code и Codex CLI:

claude mcp add --transport http zaezd http://localhost:8080/mcp
codex mcp add zaezd --url http://localhost:8080/mcp

Qwen Code:

qwen mcp add --transport http zaezd http://localhost:8080/mcp

Хост, который умеет рисовать виджеты, получит тот же экран через ресурс ui://zaezd/trip-board. Хост без виджетов получит тот же ответ текстом.

Архитектура

Зависимости идут только вниз.

Схема и две последовательности - в docs/architecture.md, решения с обоснованиями - в docs/decisions.md.

Ключевое: даты, цены и выполнимость считает код, а не модель. Три одинаковых живых прогона через модель дали три разных числа ночей и разброс цены в полтора раза. Поэтому алгоритм живёт в src/composer/dates.ts и покрыт таблицей сценариев.

Ограничения

Список честный, читайте его как часть продукта.

• Онлайн-событие поездку не строит, и событие в вашем же городе тоже. В обоих случаях Заезд говорит об этом прямо, а не показывает пустой экран;

• живой каталог confcal знает 21 город, а живые офлайн-события есть примерно в 15 из них. Пустые города не прячутся, счётчик показан на экране;

• за один запрос считается одна поездка. Ещё до пяти событий по теме показываются списком, но не считаются: веер из пяти сборок - это спиннер, а не продукт;

• прогноз погоды доступен только на 16 дней вперёд. Дальше блок погоды просто исчезает;

• адрес площадки берётся из каталога и никогда не додумывается. Если каталог его не дал, экран говорит об этом и не ставит метку на карте, а агента ответ просит поискать адрес в открытых источниках и сказать человеку, что адрес не из каталога;

• мультитранспорт Туту считает взрослых, детских и льготных тарифов в поездке нет;

• ссылка на авиабилет в холодном браузере открывает поиск, а не корзину: корзина заводится только в браузере с живой сессией Туту. Поэтому подпись такой кнопки об этом и говорит;

• схемы мест в вагоне нет;

• цена участия в событии складывается в итог только если каталог написал её числом. Текстовую цену вроде "бесплатно для студентов" Заезд показывает как есть и в сумму не берёт;

• в режиме replay ссылки на оплату собраны из записи и, скорее всего, протухли. Экран и ответ агенту об этом предупреждают;

• у каталога за раз запрашивается восемь событий: на большем числе он перестаёт отдавать поток посреди ответа. Замер и обоснование в журнале решений.

Измерено

Карта репозитория

specs/      спецификация продукта, она же источник правды
features/   исполняемые сценарии на Gherkin и шаги к ним
tests/      юнит-тесты чистого слоя
src/        код продукта по слоям
fixtures/   записанные ответы источников
scripts/    record.ts и вспомогательные утилиты
docs/       руководство пользователя, архитектура, журнал решений

Лицензия

MIT, см. LICENSE.