Award Flight Daily

Award Flight Daily MCP サーバー

Award Flight Daily データベース（25 のロイヤルティプログラムにわたる 1,230 万件の特典航空券レコード）をラップし、ツールを介して AI エージェントに公開する FastMCP サーバーです。

概要

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
)

返却値：1 つのプログラムの詳細統計：

• 空席数の合計
• 固有のルートと空港
• 客室クラス別の平均マイル数と最小マイル数

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. 関心の分離 - DB クエリ、モデル、ツール、レスポンスを分離
3. 型安全性 - すべての入力に Pydantic モデルを使用
4. 堅牢性 - すべてのクエリをパラメーター化し、入力にバリデーターを適用
5. 高速性 - 読み取り専用の DuckDB、遅延接続、MCP レイヤーによるキャッシュ
6. テスト容易性 - 純粋関数を使用し、副作用を排除

エラー処理

• 無効な入力：フィールドの詳細を含む Pydantic ValidationError
• データベースエラー：エラーメッセージ文字列を返します（500 エラーは発生しません）
• 検索結果なし：「フライトが見つかりません」というわかりやすいメッセージ

MCP レイヤーが、エラーのクライアント向けシリアライズを処理します。

今後の拡張

• 価格追跡（マイルの価値計算）
• シートマップ連携
• 特典チャートの比較
• マイレージプログラムの獲得率
• ストップオーバー／乗り継ぎの最適化
• MCP によるアラート設定（将来的に読み書きツールを提供）