Skip to main content
Glama
deenesjakoruzh
svyatrunov

tutu-compass

by svyatrunov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

🧭 Компас — a negotiation travel agent for trips across Russia

An agent that a family from Yekaterinburg writes to in a single phrase:

"We want to go to the sea, 45,000 for three, with a child, without long connections."

— and it itself finds the contradiction between budget and connections, shows the fork right on the timeline, asks what to sacrifice, remembers the answers, and keeps Plan B ready for every fragile leg of the route.

Project for the Tutu MCP AI hackathon, August 18–21, 2026. Works on top of Tutu MCP (planes, trains, commuter trains, buses, hotels).

Fork: budget vs. 'without a train' — the agent asks what to sacrifice

Start screen: map with prices to nearby cities

Click on a city: nearest flights and prices without a single LLM token

Leg failure: 'before → after', Plan B applied instantly

The same agent as an MCP App: interactive widget in the Claude chat

From left to right: the start exploration map (clicks on cities don't spend tokens — only Tutu MCP); the city card with flights and ±day; switching to Plan B after a failure; MCP widget (SEP-1865).

How this differs from "yet another ticket search"

Regular search

Компас

A form with ten fields

One phrase in natural language

"Nothing found"

"It's impossible to fit the budget and a connection < 1 h at the same time — what will we sacrifice?"

Best option by formula

Fork with an honest trade-off and memory of your choice

Tickets ran out — start over

Plan B is precomputed, switching is instant

Related MCP server: FlightHunter MCP

Quick Start

git clone https://github.com/svyatrunov/tutu-compass.git && cd tutu-compass
npm install
cp deploy/.env.example apps/server/.env

Fill in OPENROUTER_API_KEY in apps/server/.env and run:

npm run dev

Frontend — http://localhost:5173, API — http://localhost:8787 (Vite proxies /api).

Demo without internet and without keys — on recorded fixtures:

DEMO_MODE=replay npm run dev

Production entirely in Docker:

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

Компас as an MCP server

The same agent is available as the MCP tool plan_trip — one call instead of manual orchestration of the 16 raw Tutu tools. Endpoint: http://localhost:8787/mcp after npm run dev (Streamable HTTP; on your own server — https://<домен>/mcp). To quickly view the widget without an MCP host: http://localhost:8787/api/dev/widget-preview. In hosts with MCP Apps support (Claude, Claude Desktop, VS Code Copilot, Goose), the result is rendered as an interactive timeline right in the chat (SEP-1865); other MCP clients receive text + structured JSON. Dialog memory — via sessionId in the tool arguments. The web version is the primary channel and does not depend on the MCP channel: both live in one process on top of the same agent/* core.

Channel check: npm run smoke:mcpapp against a running server.

Useful Commands

Command

What it does

npm run mcp:discover

Captures the actual specification of the Tutu tools → docs/MCP-NOTES.md

npm run fixtures:record

Records MCP responses into fixtures/recorded for replay

npm test

Unit tests for conflicts and Plan B + contract tests for MCP schemas

npm run smoke

E2E run of the demo scenario against a running server

npm run lint / npm run typecheck

ESLint / TypeScript strict

Documentation

Document

Purpose

docs/AGENT-BRIEF.md

Start here. Self-contained reference for evaluation: flow, stack, benchmarks, self-assessment by hackathon tracks

docs/SYSTEM-MAP.md

System map: 16 Tutu tools → our modules → channels + quick answers to jury questions

docs/ROADMAP.md

Working plan up to code freeze, ranked by "points per hour"

docs/MCP-FEEDBACK.md

12 structured suggestions for the Tutu MCP specification — with reproducible findings

docs/ARCHITECTURE.md

Diagram, agent loop, conflict detection

docs/ASSUMPTIONS.md

An honest list: what is actually from MCP and what is imitation

docs/MCP-NOTES.md

Actual (not declared) Tutu MCP specification

docs/EVALS.md

Model strategy and benchmark findings log

docs/PITCH.md

Pitch points and timing

Where to look at the code by hackathon criteria

Criterion

Where to look

Functional depth

agent/orchestrator.ts — agent loop

Innovation

agent/conflicts.ts — conflict as a provable fact, without a single LLM call

UX/UI

components/Timeline — conflict node and Plan B dashed line

Stability

mcp/client.ts — cache, retry, fixture replay

Architecture

docs/ARCHITECTURE.md

Honesty

docs/ASSUMPTIONS.md — what is actually from MCP and what is imitation

Code quality

tsconfig.base.json (strict + noUncheckedIndexedAccess), ESLint, CI

Repository Rules

  • Secrets only via env. .env is in .gitignore, .env.example — in the repository.

  • The LLM never generates route data: prices, flights, and links come only from MCP, the model only selects among them by id. This is protection against hallucinations on top of real data.

License

MIT — see LICENSE.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers