Award Flight Daily

Award Flight Daily MCP 服务

一个 FastMCP 服务，用于封装 Award Flight Daily 数据库（包含 25 个忠诚度计划的 1,230 万条奖励航班记录），并通过工具将其提供给 AI Agent。

概览

Award Flight Daily MCP 服务提供 7 个核心工具，用于搜索、分析和优化奖励旅行：

1. afd_search_award_flights - 搜索 1,200 多万条记录
2. afd_list_programs - 列出全部 25 个计划及其统计信息
3. afd_get_program_details - 深入了解单个计划
4. afd_get_route_availability - 查看航线日历
5. afd_find_sweet_spots - 查找最具价值的兑换
6. afd_check_transfer_partners - 查看信用卡转点比例
7. afd_get_market_stats - 查看数据库汇总统计信息

文件结构

mcp_server/
├── __init__.py                 # Package definition
├── config.py                   # Constants: programs, cabins, banks
├── server.py                   # FastMCP server entry point (7 tools registered)
├── db/
│   ├── __init__.py
│   └── queries.py             # DuckDB queries (read-only, parameterized)
├── models/
│   ├── __init__.py
│   ├── inputs.py              # 8 Pydantic input models with validators
│   └── responses.py           # Formatting helpers (JSON/Markdown)
└── tools/
    ├── __init__.py
    ├── search.py              # afd_search_award_flights
    ├── programs.py            # afd_list_programs, afd_get_program_details
    ├── routes.py              # afd_get_route_availability
    ├── sweet_spots.py         # afd_find_sweet_spots
    ├── transfers.py           # afd_check_transfer_partners
    └── analytics.py           # afd_get_market_stats

配置

所有环境和计划配置都位于 config.py 中：

• MCP_SERVER_NAME："awardflightdaily_mcp"
• DUCKDB_PATH：环境变量，默认值为 /data/award_flights.duckdb
• PROGRAMS：包含 25 个计划的字典（slug -> 全名）
• CABINS：客舱等级代码（Y/W/J/F）
• BANKS：7 个信用卡计划

安装与部署

要求

fastmcp>=1.0.0
pydantic>=2.0
duckdb==1.1.3

运行

Stdio 模式（本地）：

python -m mcp_server.server

HTTP 模式（远程）：

python -m mcp_server.server --http 8001

工具 API

1. 搜索奖励航班

SearchInput(
    origin="JFK",                      # Required: IATA code(s)
    destination="NRT",                 # Required: IATA code(s)
    date_from="2026-06-01",           # Required: YYYY-MM-DD
    date_to="2026-06-30",             # Required: YYYY-MM-DD
    cabin=CabinClass.BUSINESS,        # Optional: Y/W/J/F (default J)
    source="united,aeroplan",         # Optional: program filter
    direct_only=False,                # Optional: nonstop only
    max_miles=100000,                 # Optional: mileage cap
    min_seats=1,                      # Optional: min seats (default 1)
    limit=50,                         # Optional: results limit (default 50, max 200)
    offset=0,                         # Optional: pagination offset
    response_format=ResponseFormat.JSON # Optional: JSON or Markdown
)

返回：分页航班结果，包含里程、税费、座位数、航空公司和机型。

2. 列出计划

ListProgramsInput(
    response_format=ResponseFormat.JSON
)

返回：全部 25 个计划及其以下信息：

• 航班和航线总数
• 日期范围
• 各客舱可用数量（Y/W/J/F）

3. 计划详情

ProgramDetailInput(
    program="united",  # Required: program slug
    response_format=ResponseFormat.JSON
)

返回：单个计划的详细统计信息：

• 可用性总量
• 唯一航线和机场数
• 各客舱的平均和最低里程

4. 航线可用性

RouteInput(
    origin="JFK",
    destination="NRT",
    cabin=CabinClass.BUSINESS,
    source=None,  # Optional: filter by program
    response_format=ResponseFormat.JSON
)

返回：该航线所有日期的里程、税费及各计划的座位数。

5. 查找最具价值的兑换

SweetSpotInput(
    cabin=CabinClass.BUSINESS,
    origin=None,  # Optional
    destination=None,  # Optional
    limit=25,
    response_format=ResponseFormat.JSON
)

返回：按最低里程成本排序的最具价值航线。

6. 转点合作伙伴

TransferInput(
    bank="chase",      # Optional: bank slug
    program="united",  # Optional: program slug
    response_format=ResponseFormat.JSON
)

返回：信用卡 → 航空公司的转点对应关系，包含：

• 转点比例（例如“1:1”）
• 转点速度（例如“即时”“1-2 天”）

7. 市场统计信息

MarketStatsInput(
    response_format=ResponseFormat.JSON
)

返回：数据库汇总统计信息：

• 记录、计划和航线总数
• 机场覆盖范围
• 客舱可用性细分

输入验证

所有输入均使用 Pydantic 进行验证：

• IATA 代码：必须恰好包含 3 个字母字符
• 日期：仅接受 YYYY-MM-DD 格式
• 客舱：限制为 Y/W/J/F 枚举值
• Limit：1-200 条结果
• Offset：>= 0
• 最少座位数：1-9

无效输入会引发 ValidationError，并提供详细信息。

响应格式

JSON（默认）

包含分页元数据的完整结构化响应：

{
  "total": 1234,
  "count": 50,
  "offset": 0,
  "has_more": true,
  "cabin": "J",
  "results": [
    {
      "id": "...",
      "source": "united",
      "origin": "JFK",
      "destination": "NRT",
      "date": "2026-06-15",
      "mileage": 75000,
      "taxes": 11.20,
      "seats": 2,
      "direct": true,
      "airlines": "United",
      "equipment": "B787",
      "updated_at": "2026-03-26T12:34:56"
    }
  ]
}

Markdown

带格式的易读输出：

# Award Flight Search Results

**1234 flights found** | Cabin: Business | Showing 50

## JFK → NRT | 2026-06-15

- **75,000 miles** + $11.20 taxes | united
- Nonstop | 2 seats | United B787

...

数据库

所有查询均：

• 只读（DuckDB 处于只读模式）
• 使用参数化查询并进行适当转义
• 筛选 expired_at IS NULL（仅包含有效记录）
• 保证类型安全，日期使用 CAST(? AS DATE)

连接会在首次查询时延迟加载，并在之后重复使用。

设计原则

1. 避免臃肿 - 每个工具都放在独立模块中
2. 关注点分离 - 数据库查询、模型、工具和响应彼此分离
3. 类型安全 - 所有输入都使用 Pydantic 模型
4. 防御性设计 - 所有查询均使用参数化方式，输入均经过验证
5. 快速 - 使用只读 DuckDB、延迟连接，并通过 MCP 层缓存
6. 易于测试 - 使用纯函数，不产生副作用

错误处理

• 输入无效：Pydantic ValidationError，包含字段详情
• 数据库错误：返回错误消息字符串（不会产生 500 错误）
• 无结果：返回友好的“未找到航班”消息

MCP 层会处理错误向客户端的序列化。

未来增强

• 价格追踪（计算每英里的美元价值）
• 座位图集成
• 奖励表对比
• 常旅客累积里程比例
• 中途停留／转机优化
• 通过 MCP 设置提醒（未来：读写工具）