Cokuygun – AI-Powered Travel Planner

Built during Wingie / Enuygun Wegathon 2025

An intelligent travel planning system that generates personalized, day-by-day itineraries using multi-agent orchestration powered by LangChain, LangGraph, and Enuygun MCP (Model Context Protocol).

---

Overview

Cokuygun is an AI-driven travel planner that creates optimized, preference-aware multi-day itineraries. The system combines:

• LangChain/LangGraph agents for intelligent orchestration and reasoning
• Enuygun MCP for real-time travel data (flights, hotels, activities, weather)
• Rule-based solver for constraint satisfaction and optimization
• React frontend with modern, responsive UI for seamless user experience

The platform was developed during the Wingie / Enuygun Wegathon 2025 hackathon, and this repository contains the final form of the project.

Key Features

• Multi-Day Itinerary Generation: Create detailed day-by-day plans with activities, timing, and logistics
• Intelligent Orchestration: LangChain-powered agents coordinate flight search, hotel selection, activity recommendations, and weather forecasting
• Real-Time Data via MCP: Fetch live flight prices, availability, weather forecasts, and points of interest through standardized MCP tools
• Preference-Aware Planning: Budget levels (LOW/MID/HIGH/LUXURY), travel styles (relaxed/balanced/packed), interests, dietary restrictions, mobility needs
• Revision & Day-End Feedback: Modify plans on-the-fly; adjust next day's intensity based on traveler feedback (tired / normal / energetic)
• Bilingual Support: Turkish and English UI with i18n
• Timeline Awareness: Handles flight check-in, boarding, airport transfers, and transit buffers automatically

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          User Interface                              │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Frontend (React + TypeScript + Tailwind + shadcn-ui)        │  │
│  │  • Trip form (city, dates, preferences)                      │  │
│  │  • Generated plan display (markdown + interactive UI)        │  │
│  │  • Revision interface                                        │  │
│  │  • Day-end survey (feedback collection)                      │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────┬───────────────────────────────────────────┘
                           │ HTTP/REST
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     API Layer (Node + Fastify)                       │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Routes:                                                      │  │
│  │  • POST /api/plan/generate     → orchestrate new plan        │  │
│  │  • POST /api/plan/revise       → modify existing plan        │  │
│  │  • POST /api/survey/dayEnd     → process feedback            │  │
│  │  • GET  /api/profile           → user preferences            │  │
│  └───────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Services:                                                    │  │
│  │  • planner.ts        → rule-based plan builder               │  │
│  │  • mcpBridge.ts      → MCP client wrapper                    │  │
│  │  • mcpClient.remote.ts → remote MCP connection               │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────┬───────────────────────────────────────────┘
                           │ spawn Python subprocess / HTTP
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                Python Agents (LangChain + LangGraph)                 │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  travel_agent.py (Master Orchestrator)                        │  │
│  │  • Coordinates all satellite agents                           │  │
│  │  • Generates/revises/day-end plans                            │  │
│  │  • OpenAI GPT-4o-mini for reasoning                           │  │
│  │  • Context squeezing (≤4k tokens input, ≤1.2k output)         │  │
│  │  • PII masking for logs                                       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Satellite Agents:                                            │  │
│  │  • flight_agent.py    → flight search + MCP integration       │  │
│  │  • hotel_agent.py     → hotel/stays recommendations           │  │
│  │  • activities_agent.py → POI and activity suggestions         │  │
│  │  • bus_agent.py       → ground transportation                 │  │
│  │  • master_agent.py    → user profile integration              │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────┬───────────────────────────────────────────┘
                           │ HTTP (MCP JSON-RPC)
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│              MCP Server (Node + Express + stdio bridge)              │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  HTTP Server (http-server.ts)                                 │  │
│  │  • POST /tools/search_flights                                 │  │
│  │  • POST /tools/search_stays                                   │  │
│  │  • POST /tools/search_activities                              │  │
│  │  • POST /tools/weather                                        │  │
│  │  • POST /tools/search_ground_transport                        │  │
│  │  • POST /tools/maps_search, /tools/get_route                  │  │
│  └───────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  MCP Server (server.ts – stdio mode)                          │  │
│  │  • Tool definitions and JSON-RPC handlers                     │  │
│  │  • Integrates with real Enuygun APIs or mock data             │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

1. User Input: User fills out trip form (city, dates, preferences) in the React frontend
2. API Request: Frontend calls POST /api/plan/generate with trip parameters
3. Python Orchestrator: API spawns travel_agent.py (or calls it via subprocess/HTTP)
4. Agent Coordination: travel_agent.py orchestrates satellite agents:
   • flight_agent.py → calls MCP /tools/search_flights
   • activities_agent.py → calls MCP /tools/search_activities
   • Weather, hotels, ground transport similarly fetched via MCP
5. LLM Reasoning: Master orchestrator uses OpenAI GPT-4 to synthesize data into a coherent, preference-aware plan
6. Plan Generation: Output is markdown + JSON (days, slots, timing, costs)
7. Return to Frontend: API returns structured plan; frontend renders markdown and interactive UI

---

Tech Stack

Frontend

• React 18 + TypeScript
• Vite (build tool)
• Tailwind CSS + shadcn-ui (component library)
• React Router (navigation)
• Recharts (optional charts/graphs)
• i18n (Turkish/English support)

Backend (API)

• Node.js 18+ + TypeScript
• Fastify (web framework)
• Zod (schema validation)
• pnpm workspace (monorepo structure)
• Shared packages: @trip/shared (schemas/enums), @trip/solver (constraint solver)

MCP Server

• Node.js + TypeScript
• Express (HTTP wrapper)
• @modelcontextprotocol/sdk (MCP protocol)
• stdio transport (MCP server runs in stdio mode, wrapped by HTTP bridge)

Agents (Python)

• Python 3.10+
• LangChain + LangGraph (agent orchestration)
• langchain-openai (OpenAI GPT-4 integration)
• httpx (async HTTP client for MCP calls)
• python-dotenv (environment management)

---

Agents and Orchestrator

Master Orchestrator: travel_agent.py

The main orchestrator that:

• Coordinates all satellite agents (flight, hotel, activities, weather, bus)
• Synthesizes multi-source data into a unified day-by-day plan
• Uses LangChain ChatOpenAI for LLM calls
• Implements context squeezing (≤4k prompt tokens, ≤1.2k output tokens)
• Supports three modes:
  • generate: Create new plan from scratch
  • revise: Modify existing plan (for example, flight delay or preference change)
  • day_end: Adjust next day's tempo based on feedback (tired, normal, or energetic)
• Outputs markdown plan plus machine-readable JSON (<APPEND_JSON> block)

Satellite Agents

Agent	Purpose	MCP Tool(s) Used
flight_agent.py	Flight search and selection	search_flights
hotel_agent.py	Hotel/stay recommendations	search_stays
activities_agent.py	Points of interest, tours, museums	search_activities
bus_agent.py	Ground transportation (bus, train, transfer)	search_ground_transport
master_agent.py	User profile integration, preferences	(API calls, not MCP)

LangChain & LangGraph Usage

• LangChain: Used for LLM abstraction (ChatOpenAI), message formatting, and prompt engineering
• LangGraph: Originally used for workflow/state machine orchestration (for example, workflow.py)
• Agentic Patterns: Tool calling, context management, retry logic, structured output parsing

---

MCP Integration

Model Context Protocol (MCP) is used to provide real-time travel data to the agents.

MCP Server (backend/apps/mcp)

• HTTP Bridge: http-server.ts exposes MCP tools as REST endpoints (for example, POST /tools/search_flights)
• MCP Server: server.ts runs in stdio mode, handles JSON-RPC requests
• Tools: Defined in tools/ directory:
  • flights.ts – flight search
  • stays.ts – hotel search
  • activities.ts – activity search
  • weather.ts – weather forecast
  • ground.ts – bus/train/transfer search
  • maps.ts – map search, route calculation

---

Acknowledgements

This project was developed during Wingie / Enuygun Wegathon 2025, a hackathon focused on innovative travel tech solutions.

Key Technologies

• LangChain & LangGraph: For building intelligent, orchestrated AI agents
• Model Context Protocol (MCP): For standardized, tool-based data access
• Enuygun MCP: For real travel data APIs (flights, hotels, activities)

Contributors (team orbit)

• Tuğrap Efe Dikpınar
• Ahmet Mert Tezcan
• Alperen Sari
• Special thanks to Wingie / Enuygun for hosting the hackathon

Contact

tugrapefedikpinar@gmail.com

---

bizce cokuygun