🧭 Компас — переговорный тревел-агент для путешествий по России

Агент, которому семья из Екатеринбурга пишет одной фразой:

«Хотим к морю, 45 000 на троих, с ребёнком, без долгих пересадок»

— а он сам находит противоречие между бюджетом и пересадками, показывает развилку прямо на таймлайне, спрашивает чем пожертвовать, помнит ответы и держит наготове план Б на каждое хрупкое звено маршрута.

Проект для ИИ-хакатона Туту MCP, 18–21 августа 2026. Работает поверх Tutu MCP (самолёты, поезда, электрички, автобусы, отели).

Развилка: бюджет против «без поезда» — агент спрашивает, чем пожертвовать

Слева направо: стартовая карта-исследование (клики по городам не тратят токены — только Tutu MCP); плашка города с рейсами и ±день; переключение на план Б после сбоя; MCP-виджет (SEP-1865).

Чем это отличается от «ещё одного поиска билетов»

Обычный поиск	Компас
Форма с десятью полями	Одна фраза на естественном языке
«Ничего не найдено»	«Уложиться в бюджет и в пересадку < 1 ч одновременно нельзя — чем пожертвуем?»
Лучший вариант по формуле	Развилка с честным trade-off и памятью о вашем выборе
Билеты кончились — начинайте сначала	План Б просчитан заранее, переключение мгновенное

Быстрый старт

git clone https://github.com/svyatrunov/tutu-compass.git && cd tutu-compass

npm install

cp deploy/.env.example apps/server/.env

Заполните OPENROUTER_API_KEY в apps/server/.env и запустите:

npm run dev

Фронт — http://localhost:5173, API — http://localhost:8787 (Vite проксирует /api).

Демо без интернета и без ключей — на записанных фикстурах:

DEMO_MODE=replay npm run dev

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

cd deploy && cp .env.example .env && docker compose up -d --build

Компас как MCP-сервер

Тот же агент доступен как MCP-тул plan_trip — один вызов вместо ручной оркестрации 16 сырых тулов Туту. Endpoint: http://localhost:8787/mcp после npm run dev (Streamable HTTP; на своём сервере — https://<домен>/mcp). Быстро посмотреть виджет без MCP-хоста: http://localhost:8787/api/dev/widget-preview. В хостах с поддержкой MCP Apps (Claude, Claude Desktop, VS Code Copilot, Goose) результат рендерится интерактивным таймлайном прямо в чате (SEP-1865); остальные MCP-клиенты получают текст + структурированный JSON. Память диалога — через sessionId в аргументах тула. Веб-версия — основной канал и от MCP-канала не зависит: оба живут в одном процессе поверх одного ядра agent/*.

Проверка канала: npm run smoke:mcpapp против запущенного сервера.

Полезные команды

Команда	Что делает
`npm run mcp:discover`	Снимает фактическую спецификацию тулов Туту → `docs/MCP-NOTES.md`
`npm run fixtures:record`	Записывает ответы MCP в `fixtures/recorded` для реплея
`npm test`	Unit-тесты конфликтов и плана Б + contract-тесты схем MCP
`npm run smoke`	E2E-прогон демо-сценария против поднятого сервера
`npm run lint` / `npm run typecheck`	ESLint / TypeScript strict

Документация

Документ	Зачем
`docs/AGENT-BRIEF.md`	Начните отсюда. Самодостаточная справка для оценки: флоу, стек, бенчмарки, самооценка по трекам хакатона
`docs/SYSTEM-MAP.md`	Карта системы: 16 тулов Туту → наши модули → каналы + быстрые ответы на вопросы жюри
`docs/ROADMAP.md`	Рабочий план до code freeze, ранжирован по «баллам за час»
`docs/MCP-FEEDBACK.md`	12 структурированных предложений к спецификации Tutu MCP — с воспроизводимыми находками
`docs/ARCHITECTURE.md`	Схема, цикл агента, детекция конфликтов
`docs/ASSUMPTIONS.md`	Честный список: что реально из MCP, что имитация
`docs/MCP-NOTES.md`	Фактическая (не заявленная) спецификация Tutu MCP
`docs/EVALS.md`	Стратегия моделей и журнал находок бенчмарка
`docs/PITCH.md`	Тезисы и тайминг питча

Где смотреть код по критериям хакатона

Критерий	Где смотреть
Глубина функционала	`agent/orchestrator.ts` — цикл агента
Инновационность	`agent/conflicts.ts` — конфликт как доказуемый факт, без единого вызова LLM
UX/UI	`components/Timeline` — узел-конфликт и пунктир плана Б
Стабильность	`mcp/client.ts` — кэш, retry, реплей фикстур
Архитектура	`docs/ARCHITECTURE.md`
Честность	`docs/ASSUMPTIONS.md` — что реально из MCP, а что имитация
Качество кода	`tsconfig.base.json` (strict + `noUncheckedIndexedAccess`), ESLint, CI

Правила репозитория

Секреты только через env. .env в .gitignore, .env.example — в репозитории.
LLM никогда не генерирует данные маршрута: цены, рейсы и ссылки приходят только из MCP, модель лишь выбирает среди них по id. Это защита от галлюцинаций поверх реальных данных.

Лицензия

MIT — см. LICENSE.

tutu-compass