entbappy/tripmate-ai-using-mcp

Purpose and Entry Points

TripMate AI converts a natural-language travel request into flights, hotel research, weather, and a day-by-day itinerary. The FastAPI process starts at app.py; the main multi-agent travel workflow resides in backend.py. Browser delivery is served through templates/index.html with assets in static/script.js and static/style.css.

API and Request Boundary

app.py exposes the health endpoint and the travel-submission API. It accepts the user message from the browser or an API consumer, delegates planning to backend.py, and returns the generated response. This is the primary synchronous HTTP boundary; agent/tool work below it is asynchronous where MCP clients are invoked.

LangGraph Planning Workflow

backend.py is the orchestration layer and system’s core control plane. It defines the LangGraph-driven sequence of specialized stages:

1. interpret the trip request and destination,

2. research flights,

3. research hotels,

4. obtain current weather/forecast,

5. synthesize a practical itinerary,

6. produce the final user-facing response.

The workflow uses LangChain/Groq-backed LLM agents for reasoning and consolidation, while treating retrieved travel facts as upstream context rather than directly coupling agents to provider APIs.

MCP Tool-Integration Boundary

mcp_client.py centralizes MCP transport and exposes async helpers used by the workflow for Tavily, AviationStack, weather, forecasts, and destination extraction. This isolates provider-specific invocation from backend.py and supports three MCP deployment forms:

• remote Tavily MCP endpoint,

• local stdio uvx aviationstack-mcp command,

• local custom weather server.

Relevant paths: mcp_client.py, custom_weather_mcp_server.py, backend.py.

Travel Data Providers

Flight research is backed by AviationStack through MCP; hotel ideas come from Tavily web search; weather is supplied through the project-owned MCP server backed by OpenWeather credentials. Legacy/direct integration modules may also support the tool layer: tools/flight_tool.py and tools/tavily_tool.py. Provider credentials and default origin are environment-driven, keeping secrets and deployment-specific values outside application code.

Weather MCP Service

custom_weather_mcp_server.py is a separately launched local MCP server process, invoked by the client over stdio. It provides weather and forecast capabilities to the weather stage without exposing OpenWeather calls directly to the main API process. Its process lifecycle and Python executable path must be compatible with the command configured in mcp_client.py.

State, Runtime, and Infrastructure

The runtime is Python 3.10+ with FastAPI, LangGraph/LangChain, and Groq LLM access. PostgreSQL persists conversation/workflow state, forming the durable-state boundary for requests beyond a single HTTP interaction. Required external dependencies are PostgreSQL, Groq, Tavily MCP, AviationStack MCP/API, OpenWeather, and local uvx for the AviationStack MCP command. Container deployment is represented by Dockerfile.