travel helper

Travel Helper--开发人员文档

廉价往返航班（瑞安航空API）+酒店（Trivago MCP）+天气和目的地（GeoTemp MCP）。

本文件适用于 开发者：瑞安航空API、Trivago MCP服务器和GeoTemp MCP服务器的技术细节，以及如何运行和扩展堆栈。

______________________________________________________________________

目录

1. 概述
2. 要求和设置
3. 瑞安航空API
4. Trivago MCP服务器
5. GeoTemp MCP服务器
6. 如何跑步
7. 项目布局
8. 在渲染上部署

______________________________________________________________________

概述

应用程序：

1. 航班 -查询瑞安航空的公共服务API（无API密钥）往返 杜塞尔多夫-威泽（NRN）, 科隆（CGN），以及 多特蒙德（DTM）.出站： 星期三18:00后, 星期四17:00之后，或 周五11:00之后2-4晚后返回。
2. 酒店 --使用 Trivago MCP服务器 （流式HTTP）解析城市→ 位置，并为每次旅行的日期获取住宿。
3. 天气和目的地 --使用 GeoTemp旅行MCP服务器 （SSE）用于天气、景点、城市概况、相似/附近城市、旅行计划和数据集统计。

输出：人类可读文本，JSON(--json)，或HTML(--html).通过Gmail发送HTML报告的可选电子邮件。

______________________________________________________________________

要求和设置

• Python 3.10+ （需要 mcp Trivago/GeoTemp客户端）。
• 虚拟环境 （推荐）：

cd /path/to/travel_helper
python3 -m venv .venv-travel
source .venv-travel/bin/activate   # Windows: .venv-travel\Scripts\activate
pip install ryanair-py requests backoff "mcp[cli]"

• 瑞安航空：无API密钥；用途 https://services-api.ryanair.com/.
• Trivago MCP：公共终结点 https://mcp.trivago.com/mcp；没有授权。
• 地热MCP：公共终结点 https://mcp-travel-data.onrender.com/sse；没有授权。

如果 mcp 如果未安装，脚本仍会运行，但会跳过酒店和GeoTemp（仅限航班）。

______________________________________________________________________

瑞安航空API

源

该项目使用 瑞安皮 图书馆（或供应商 ryanair/)，称为瑞安航空 应用编程接口 直接。没有API密钥。

• 基础URL: https://services-api.ryanair.com/farfnd/v4/
• 使用的端点:

- 往返票价: roundTripFares\ 参数： departureAirportIataCode, outboundDepartureDateFrom, outboundDepartureDateTo, inboundDepartureDateFrom, inboundDepartureDateTo，以及可选的时间窗口和 currency.

技术细节

• 客户: ryanair.Ryanair(currency="EUR").
• 方法: get_cheapest_return_flights(source_airport, date_from, date_to, return_date_from, return_date_to, ...).
• 时间窗口 （由travel_helper使用）：

- 出境：周三≥18:00，周四≥17:00，或周五≥11:00(outboundDepartureTimeFrom / outboundDepartureTimeTo). - 入境：无限制（全天）。

• 返回结构：列表 (outbound, inbound, outbound_price) 其中每条腿都是 Flight-喜欢对象with departureTime, origin, destination, originFull, destinationFull, price, currency等等。

代码参考

• API包装: ryanair/ryanair.py — Ryanair.get_cheapest_return_flights(), get_cheapest_flights().
• 在应用程序中使用: travel_helper.py 构建日期范围（例如接下来的120天），按工作日/时间过滤出站，然后按价格排序，并选择N个最便宜的往返。
• 预订URL: _ryanair_booking_url() 构建德国瑞安航空往返选择URL(https://www.ryanair.com/de/de/trip/flights/select?...)用于手动预订。

速率限制和稳健性

• 图书馆使用 退避 用于在失败时重试。
• 没有明确的费率限制记录；在脚本中使用合理的请求间距。

______________________________________________________________________

Trivago MCP服务器

端点和传输

• 统一资源定位符: https://mcp.trivago.com/mcp
• 运输: 可流式传输的HTTP （基于HTTP的MCP）。Python客户端使用 mcp.client.streamable_http.streamable_http_client(TRIVAGO_MCP_URL).

使用的工具

应用程序中的流量

1. 位置分辨率\

对于每个目的地城市（例如从瑞安航空 destinationFull)，该应用程序会删除机场代码和电话 trivago-search-suggestions 使用城市名称（以及可选的回退查询）。它解析第一个 (ID, NS) 根据响应（JSON或正则表达式回退）。

1. 住宿搜索\

随着 (id, ns) 以及行程日期（到达=出发日期，出发=返回日期），它调用 trivago-accommodation-search 随着 adults 和 rooms （来自CLI，默认值2和1）。结果按每晚价格排序，前N位按每次行程保留。

客户端模块

• 文件: trivago/fetch_hotels_mcp.py
• 函数:

- get_location_suggestion(session, query) -> (id, ns) | None --电话 trivago-search-suggestions. - search_accommodations(session, location_id, location_ns, arrival, departure, adults=2, rooms=1) -> list[dict] --电话 trivago-accommodation-search.

• 响应解析：同时处理两者 structuredContent 以及文本内容块；支持Go风格和JSON响应（例如。 output:[...]).酒店条目会显示以下字段 Accommodation Name, Price Per Stay, Price Per Night, Accommodation URL, Review Rating.

独立运行

python -m trivago.fetch_hotels_mcp "Berlin" --arrival 2026-03-15 --departure 2026-03-18 --adults 2 --rooms 1
# Optional: --json for raw JSON, --max 10 for result count

依赖项

• mcp （支持流式传输HTTP）： pip install "mcp[cli]".
• 无Trivago API密钥；公共MCP端点按原样使用。

______________________________________________________________________

GeoTemp MCP服务器

端点和传输

• 统一资源定位符: https://mcp-travel-data.onrender.com/sse
• 运输: SSE（服务器发送事件）。客户端使用 mcp.client.sse.sse_client(GEOTEMP_MCP_URL) 以及MCP ClientSession 在SSE流上。

数据集（高级）

• 384个城市, 115个国家, 29项活动得分 （例如。 beach_holiday, city_break, swimming).
• 天气、景点、城市特色和活动评分为13个工具提供了动力。

工具（共13个）

活动名称（精确字符串）

被...使用 search_by_activity, multi_activity_search, plan_trip （除其他外）：

adventure_sports, beach_holiday, city_break, cultural_sightseeing, cycling, diving, family_friendly, fishing, food_tourism, golf, hiking, nightlife, photography, rock_climbing, romantic_getaway, running_jogging, sailing, shopping, skiing, snorkeling, spa_wellness, surfing, swimming, water_sports, wildlife_viewing, wine_tasting, winter_sports, yoga_retreat.

客户端模块

• 文件: geotemp/geotemp_fetch_mcp.py
• 模式：所有功能都是 async 并采取一个 ClientSession 作为第一个论点；他们叫 session.call_tool(tool_name, params) 并从结果中解析JSON(content[0].text 或 structuredContent).
• 例子:

- get_weather(session, city_name, start_date, end_date, month=None) --每月或日期范围的天气。 - get_attractions(session, city_name, category=None, limit=10). - get_city_profile(session, city_name). - find_best_month(session, city_name, prefer_warm=True, ...). - find_similar_cities(session, city_name, limit=10). - find_nearby_destinations(session, city_name=..., radius_km=500, limit=15) 或 latitude=..., longitude=.... - get_seasonal_calendar(session, city_name). - plan_trip(session, month, activities=..., max_budget_usd=..., continent=..., limit=15). - compare_cities(session, city_names, month=None). - search_destinations(session, continent=..., country=..., limit=20). - search_by_activity(session, activity, month=..., min_score=60, limit=15). - multi_activity_search(session, activities, month=..., min_score=40, limit=15). - get_dataset_stats(session).

在travel_helper中使用

• 每个目的地（每次行程）：旅行日期的天气、景点、城市概况、最佳月份、类似城市、附近目的地、季节日历。这些汇总在 travel_data 并以文本和HTML呈现。
• 每次运行一次: get_dataset_stats, plan_trip （例如欧洲，第一个月）， compare_cities （前5个目的地）， search_destinations, search_by_activity （例如。 city_break), multi_activity_search （例如。 beach_holiday + swimming).结果显示在全球“数据集”、“旅行想法”、“目的地比较”、“更多目的地”、“顶级城市度假”、“海滩和游泳”部分。

依赖项

• mcp （SSE客户）： pip install "mcp[cli]"。没有公共GeoTemp SSE终结点的API密钥。

______________________________________________________________________

旅行助手MCP服务器（基于文件）

A. 本地MCP服务器 上面写着 data/travel_helper.json （JSON由 travel_helper.py)并公开了列出和搜索交易的工具——没有Trivago/GeoTemp API，数据来自文件。

• 包裹: mcp_travel_helper/ （跑步 python -m mcp_travel_helper).
• 数据: data/travel_helper.json （默认路径；用覆盖 TRAVEL_HELPER_JSON).
• 工具: travel_deals_list, travel_deals_search, travel_deals_destination, travel_deals_cheapest, travel_deals_flights_for_destination.

看 mcp_tovel_helper/README.md 用于工具描述和光标/VS代码MCP配置。 码头工人: mcp_tovel_helper/ci/README.md --在容器中构建和运行MCP服务器。

______________________________________________________________________

如何跑步

一次性（推荐：使用venv）

# From project root
source .venv-travel/bin/activate   # or .venv-travel\Scripts\activate on Windows

# Human-readable (default: 10 cheapest round trips, 3 hotels per trip)
python travel_helper.py

# JSON (e.g. for pipelines / OpenClaw)
python travel_helper.py --json

# HTML report (writes travel_helper.html)
python travel_helper.py --html

# Flights only (no Trivago / no GeoTemp)
python travel_helper.py --no-hotels

# Tuning
python travel_helper.py --num-cheapest-trips 5 --adults 2 --rooms 1 --days-ahead 120

CLI选项（摘要）

电子邮件（Gmail）

export GMAIL_USER=your@gmail.com
export GMAIL_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
python travel_helper.py --html --email recipient@example.com

计划运行（GitHub操作）

工作流每天在以下位置运行 德国时间上午7点 （UTC时间6:00）（参见 )与：

• --num-cheapest-trips 100 --days-ahead 90 --html

生成的HTML报告作为工件上传（保留14天）。要手动运行，请执行以下操作： 行动 → 日常旅行助手 → 运行工作流。若要通过电子邮件从工作流中获取报告，请添加仓库机密 GMAIL_USER 和 GMAIL_APP_PASSWORD 并取消注释 env 工作流中的块。

故障排除

• “未安装Trivago MCP” --在同一环境中安装： pip install "mcp[cli]"需要Python 3.10+。
• 无酒店/HTTPS错误 --使用带有正确SSL的Python构建（例如OpenSSL 1.1.1+）。使用具有以下特性的项目venv运行 mcp 安装。
• GeoTemp不可用 --如果GeoTemp导入失败（例如丢失 mcp 或SSE），该应用程序仍仅在航班和Trivago上运行；GeoTemp部分被省略。

______________________________________________________________________

项目布局

travel_helper/
├── travel_helper.py       # Main script: Ryanair + Trivago + GeoTemp orchestration
├── data/
│   └── travel_helper.json # Generated JSON (consumed by mcp_travel_helper)
├── mcp_travel_helper/     # MCP server: reads data/travel_helper.json, exposes deal tools (stdio + streamable-http)
│   ├── server.py
│   ├── __main__.py
│   ├── README.md
│   └── ci/                # Docker: Dockerfile and sample data for MCP server image
│       ├── Dockerfile
│       ├── .dockerignore
│       └── README.md
├── geotemp/               # GeoTemp MCP client (SSE, 13 tools)
│   └── geotemp_fetch_mcp.py
├── trivago/
│   └── fetch_hotels_mcp.py # Trivago MCP client (Streamable HTTP; suggestions + accommodation search)
├── ryanair/               # Ryanair API client (or use ryanair-py from PyPI)
│   ├── ryanair.py
│   ├── SessionManager.py
│   └── ...
├── README.md              # User/developer docs (this file in repo)
├── setup.py               # Optional package setup
└── travel_helper.html     # Generated report (optional)

______________________________________________________________________

摘要

所有三个外部服务都集成在 travel_helper.py；Trivago和GeoTemp是可选的，如果未安装MCP堆栈，则会正常降级。Travel Helper MCP服务器是一个单独的进程，用于读取生成的JSON。

______________________________________________________________________

在渲染上部署

这 旅游交易助理 （Flask应用程序在 travel_assistant.py)可以作为web服务部署在 渲染。每次向链接分支推送时，渲染构建和部署(自动部署).

一键或蓝图

1. 连接仓库 在 渲染仪表板: New → Web服务，然后连接您的GitHub/GitLab/Bitbucket仓库。
2. 使用蓝图 （推荐）： New → 蓝图，然后指向此仓库中的Render。它将读 render.yaml 并使用正确的构建和启动命令创建web服务。
3. 或手动设置:

- 构建命令： pip install -r requirements.txt - 启动命令： gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 4 travel_assistant:app

环境变量

在服务中设置这些 环境 （渲染仪表板→ 您的服务→ 环境）：

Python版本

Render使用中的版本 .python-version （例如。 3.11.2)或 PYTHON_VERSION 环境变量。看 设置Python版本.

备注

• 应用程序绑定到 0.0.0.0 港口从 PORT 环境变量(渲染端口绑定).
• 助理启动本地 mcp_tovel_helper 后台线程中的服务器；没有 data/travel_helper.json （或为空），交易列表将为空，直到您运行 travel_helper.py 并上传JSON或点 TRAVEL_HELPER_JSON 保存到持久文件。