Заезд

Ein Reise-Engine, der mit einem Anlass beginnt. Man weiß nicht, wohin man fahren soll, sondern warum: man möchte zu einer Konferenz zum eigenen Thema. Заезд findet die nächste Offline-Veranstaltung, berechnet den Hin- und Rückweg, ein Hotel in der Nähe des Veranstaltungsorts und den vollen Teilnahmepreis und zeigt bis zu drei erklärbare Pakete auf einem Bildschirm.

Die erste Vertikale sind IT-Konferenzen. Den Veranstaltungskatalog liefert confcal MCP, Transport und Unterkunft Tutu MCP, und alles setzt ein deterministischer Komponist zusammen, nicht ein Modell.

Was wo

Related MCP server: Travel Planner MCP Server

End-to-End-Szenario

Sie öffnen die Wurzel. Auf dem Bildschirm ist bereits eine zusammengestellte Reise, kein leeres Formular. Oben stehen Veranstaltung, Datum, Stadt, Veranstaltungsort und die Gehzeit dorthin vom nächstgelegenen Hotel. Darunter bis zu drei Karten: die Hinfahrt mit Zug- oder Flugnummer, das Hotel mit Preis für die gesamte Übernachtung und Entfernung zum Veranstaltungsort, die Rückfahrt, die Gesamtsumme als eine Zahl und darunter eine Rechenzeile, die aufgeht. Danach eine Stadtkarte mit Veranstaltungsort und Hotels, das Wetter für die Reisedaten, weitere Veranstaltungen zum Thema und eine Liste dessen, was nicht aufgenommen wurde und warum.

Sie klicken auf „Zahlungslinks zusammenstellen“ – es erscheint eine Checkliste mit zwei bis drei Tutu-Links. Die Beschriftung jeder einzelnen wird aus dem übernommen, was Tutu tatsächlich zurückgegeben hat: „Warenkorb öffnen“, wo ein Warenkorb geöffnet wird, und „Auswahlseite öffnen“, wo es keinen Warenkorb geben wird.

Dasselbe für den Agenten: find_event_trips mit Thema und Abfahrtsstadt gibt dieselbe Reise als Struktur zurück, get_trip_details öffnet das Paket, create_trip_checkout erstellt die Checkliste. Ein Host, der zeichnen kann, erhält denselben Bildschirm als MCP App.

Start aus dem Quellcode

npm install
ZAEZD_MODE=replay npm run dev

Es öffnet sich http://localhost:8080. Im Modus replay arbeitet das Produkt mit aufgezeichneten Antworten aus fixtures/ und geht nicht ins Netz: Man kann damit ohne Internet und ohne Schlüssel leben, und das Referenzdatum ist der Tag der Aufzeichnung. Der Live-Modus ist ZAEZD_MODE=live.

Vollständige Prüfung:

npm run verify

Das sind Synchronität der Regeln, Abgleich der dokumentierten Befehle, Typprüfung, Linter, Erstellung des Browser-Baums, ausführbare Gherkin-Szenarien und Unit-Tests. Alles offline.

Der Browser-Baum wird nicht aus ästhetischen Gründen vor den Szenarien erstellt. Ein Szenario fordert vom Server genau jenes boot.js an, das zum Host geht, und in einem sauberen Klon gibt es diese Datei noch nicht.

Start im Container

Das Image wird aus dem Repository gebaut und enthält im Inneren sowohl den Code als auch die Fixtures. Daher benötigt der Container im Modus replay weder Internet noch Geheimnisse.

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

Der Bildschirm erscheint unter http://127.0.0.1:8080. Ohne die Datei .env startet Compose nicht: Das ist beabsichtigt, damit niemand das Produkt mit fremden Standardwerten ausführt.

Ohne Compose dasselbe mit einem einzigen Befehl:

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

Einmalig, ohne Umgebungsdatei, nur um es anzusehen:

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

Umgebungsvariablen

Die vollständige Liste mit Kommentaren liegt in .env.example. Kurz:

Es gibt keinen einzigen Schlüssel oder Token: Beide Quellen sind offen. Der Wert von ZAEZD_PUBLIC_URL sollte ehrlich gesetzt werden – genau diese Adresse geht als Link auf den Bildschirm an den Agenten und gelangt in das CSP des Widgets. Wenn sie nicht mit der tatsächlichen übereinstimmt, bleibt das Board im Host leer.

Der Container trägt einen HEALTHCHECK auf /healthz, sodass docker ps nur dann healthy anzeigt, wenn die Anwendung tatsächlich antwortet.

Hinter einem Reverse-Proxy

Die docker-compose.yaml selbst weiß nichts von Proxy, Domains und Netzwerken – das sind Eigenschaften der Plattform, nicht des Produkts. All das wird in docker-compose.override.yaml gelegt; sie steht in der Gitignore und lebt nur auf der Maschine, die den Dienst ausrollt. Beispiel für 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

Die Namen des Entrypoints, des Zertifikats-Resolvers und des Netzwerks sind bei jedem anders, daher sind sie im Beispiel Platzhalter. Für nginx oder Caddy wird der Override anders sein; das Produkt ändert sich dadurch nicht: Es hört auf PORT und liefert /healthz.

An einen Agenten anbinden

Der Endpunkt <адрес>/mcp funktioniert über streamable HTTP und benötigt keinen Schlüssel. Lokal ist das http://localhost:8080/mcp, bei einem bereitgestellten Dienst Ihre Adresse aus ZAEZD_PUBLIC_URL.

Claude Desktop akzeptiert entfernte Server nicht direkt in claude_desktop_config.json; dort leben nur stdio-Befehle. Fügen Sie Заезд daher entweder über Settings, Connectors, Add custom connector hinzu oder tragen Sie einen proxierenden Start ein:

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

Claude Code und 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

Ein Host, der Widgets zeichnen kann, erhält denselben Bildschirm über die Ressource ui://zaezd/trip-board. Ein Host ohne Widgets erhält dieselbe Antwort als Text.

Architektur

Abhängigkeiten verlaufen nur nach unten.

Das Diagramm und zwei Sequenzen finden sich in docs/architecture.md, Entscheidungen mit Begründungen in docs/decisions.md.

Das Entscheidende: Daten, Preise und Machbarkeit berechnet der Code, nicht das Modell. Drei identische Live-Durchläufe durch das Modell ergaben drei verschiedene Anzahlen von Nächten und eine Preisstreuung um das Anderthalbfache. Deshalb lebt der Algorithmus in src/composer/dates.ts und ist durch eine Szenarientabelle abgedeckt.

Einschränkungen

Die Liste ist ehrlich; lesen Sie sie als Teil des Produkts.

• Ein Online-Event baut keine Reise, und ein Event in derselben Stadt auch nicht. In beiden Fällen sagt Заезд das direkt, statt einen leeren Bildschirm zu zeigen;

• Der Live-Katalog von confcal kennt 21 Städte, und Live-Offline-Events gibt es in etwa 15 davon. Leere Städte werden nicht versteckt; der Zähler wird auf dem Bildschirm angezeigt;

• Pro Anfrage wird eine Reise berechnet. Bis zu fünf weitere Veranstaltungen zum Thema werden als Liste gezeigt, aber nicht berechnet: Ein Fächer aus fünf Zusammenstellungen ist ein Spinner, kein Produkt;

• Die Wettervorhersage ist nur für 16 Tage im Voraus verfügbar. Danach verschwindet der Wetterblock einfach;

• Die Adresse des Veranstaltungsorts stammt aus dem Katalog und wird nie dazuerfunden. Wenn der Katalog sie nicht geliefert hat, sagt der Bildschirm das und setzt keine Markierung auf der Karte; die Antwort an den Agenten bittet darum, die Adresse in offenen Quellen zu suchen und dem Menschen zu sagen, dass die Adresse nicht aus dem Katalog stammt;

• Der Tutu-Multitransport zählt Erwachsene; Kinder- und Ermäßigungstarife gibt es in der Reise nicht;

• Der Flugticket-Link öffnet in einem kalten Browser die Suche, nicht den Warenkorb: Der Warenkorb wird nur in einem Browser mit einer lebenden Tutu-Sitzung angelegt. Deshalb sagt die Beschriftung eines solchen Buttons genau das;

• Es gibt keine Sitzplatzpläne im Wagen;

• Der Teilnahmepreis der Veranstaltung fließt nur dann in die Gesamtsumme ein, wenn der Katalog ihn als Zahl angegeben hat. Einen Textpreis wie „kostenlos für Studierende“ zeigt Заезд unverändert an und nimmt ihn nicht in die Summe auf;

• Im Modus replay sind die Zahlungslinks aus der Aufzeichnung zusammengestellt und höchstwahrscheinlich abgelaufen. Der Bildschirm und die Antwort an den Agenten warnen davor;

• Vom Katalog werden auf einmal acht Veranstaltungen abgefragt: Bei einer größeren Anzahl hört er mitten in der Antwort auf, den Stream zu liefern. Messung und Begründung stehen im Entscheidungsprotokoll.

Gemessen

Repository-Karte

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

Lizenz

MIT, siehe LICENSE.