🧭 Компас — переговорный тревел-агент для путешествий по России
Агент, которому семья из Екатеринбурга пишет одной фразой:
«Хотим к морю, 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.
