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

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

«Хотим к морю, 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.