Flightticketmcp

🚀 航班機票MCP服務器

Flight Ticket MCP Server是一個基於模型上下文協議（MCP）的航空機票查詢服務器，它為AI助手提供標準化的航班即時動態查詢功能接口，有效連接AI助手與航空服務系統。

🚀 快速開始

前置要求

• Python 3.11 或更高版本
• pip 包管理器

基本安裝

# 克隆或下載項目
cd FlightTicketMCPServer

# 安裝依賴
pip install -r requirements.txt

啟動方式

1. 直接啟動（默認SSE模式）

# 使用主啟動文件（默認啟動SSE模式，監聽127.0.0.1:8000）
python flight_ticket_server.py

# 或者直接運行main.py
python main.py

2. 調試模式啟動

# 啟用調試模式，會輸出詳細日誌
set MCP_DEBUG=true
python flight_ticket_server.py

# Linux/macOS
export MCP_DEBUG=true
python flight_ticket_server.py

3. 不同傳輸協議啟動

SSE模式（默認）

# 直接啟動，使用默認SSE配置（127.0.0.1:8000）
python flight_ticket_server.py

stdio模式

# Windows
set MCP_TRANSPORT=stdio
python flight_ticket_server.py

# Linux/macOS
export MCP_TRANSPORT=stdio
python flight_ticket_server.py

HTTP模式

# Windows
set MCP_TRANSPORT=streamable-http
set MCP_HOST=127.0.0.1
set MCP_PORT=8000
python flight_ticket_server.py

# Linux/macOS
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
python flight_ticket_server.py

4. 環境變量配置

使用 .env 文件（推薦）

項目提供了 .env.example 文件作為配置模板：

1. 複製配置模板：

# 複製配置模板
cp .env.example .env

2. 編輯配置文件： 打開 .env 文件，根據需要修改配置值：

# MCP服務器配置
MCP_TRANSPORT=sse
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_SSE_PATH=/sse

# 日誌配置
LOG_LEVEL=INFO
LOG_FILE_PATH=logs/flight_server.log
LOG_MAX_SIZE=10
LOG_BACKUP_COUNT=5

# 開發配置
MCP_DEBUG=false

3. 配置說明：

• .env 文件包含敏感配置，不會被提交到版本控制
• .env.example 是安全的模板文件，可以提交到Git
• 環境變量優先級：系統環境變量 > .env文件 > 程序默認值

直接設置環境變量

如果不使用 .env 文件，也可以直接設置環境變量： 支持的環境變量：

5. 啟動驗證

啟動成功後，您會看到類似輸出：

Transport: sse
Logging enabled - logs will be saved to logs/ directory
Flight Ticket MCP Server starting...
Transport: sse
All tools registered successfully
Starting SSE transport on 127.0.0.1:8000/sse

6. 日誌文件

服務器啟動後會在 logs/ 目錄下生成以下日誌文件：

• flight_server.log - 一般日誌（INFO級別及以上）
• flight_server_error.log - 錯誤日誌（ERROR級別）
• flight_server_debug.log - 調試日誌（僅在調試模式下生成）

7. 停止服務器

• stdio模式: 按 Ctrl+C 停止
• HTTP/SSE模式: 按 Ctrl+C 或發送SIGTERM信號

✨ 主要特性

航班即時動態查詢

• 根據航班號和日期查詢航班詳細信息
• 即時航班動態和狀態信息
• 代碼共享航班號顯示
• 航班時刻表和機型信息
• 機場和航站樓信息
• 準點率統計
• 值機櫃臺和登機口信息
• 餐食和行李託運信息
• 天氣預報
• 聯繫電話信息

航班路線查詢

• 根據出發地、目的地和出發日期查詢可用航班
• 支持282個國內城市和機場代碼
• 智能城市名稱解析（支持城市名、機場代碼、完整格式）
• 即時航班價格和航班時刻信息
• 航空公司和機型信息
• 航站樓和登機口信息
• 價格統計和航空公司分佈
• 格式化輸出結果

📦 安裝指南

前置要求

• Python 3.11 或更高版本
• pip 包管理器

基本安裝

# 克隆或下載項目
cd FlightTicketMCPServer

# 安裝依賴
pip install -r requirements.txt

💻 使用示例

與Claude Desktop配置

1. 安裝完成後，將服務器添加到Claude Desktop配置文件中：

{
  "mcpServers": {
    "flight-ticket-server": {
      "command": "python",
      "args": ["D:\\FlightTicketMCPServer\\flight_ticket_server.py"],
      "env": {
        "MCP_TRANSPORT": "sse",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000"
      }
    }
  }
}

2. 配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

3. 重啟Claude Desktop以加載配置。

不同傳輸協議的配置

SSE模式（默認）

{
  "mcpServers": {
    "flight-ticket-server": {
      "command": "python",
      "args": ["D:\\FlightTicketMCPServer\\flight_ticket_server.py"],
      "env": {
        "MCP_TRANSPORT": "sse",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000",
        "MCP_SSE_PATH": "/sse"
      }
    }
  }
}

stdio模式

{
  "mcpServers": {
    "flight-ticket-server": {
      "command": "python",
      "args": ["D:\\FlightTicketMCPServer\\flight_ticket_server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP模式

{
  "mcpServers": {
    "flight-ticket-server": {
      "command": "python",
      "args": ["D:\\FlightTicketMCPServer\\flight_ticket_server.py"],
      "env": {
        "MCP_TRANSPORT": "streamable-http",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000",
        "MCP_PATH": "/mcp"
      }
    }
  }
}

示例操作

配置完成後，您可以要求Claude執行以下操作：

航班即時動態查詢

• "查詢CA3401航班2024年6月12日的即時動態"
• "查詢MU5678航班今天的詳細信息"
• "查看CZ1234航班明天的起飛時間和航站樓信息"

航班路線查詢

• "查詢重慶到廣州明天的航班"
• "搜索上海到北京後天的所有航班"
• "查看深圳飛成都2024年7月20日的航班價格"
• "北京到三亞的航班有哪些選擇"

📚 詳細文檔

API參考

航班即時動態查詢

searchFlightsByNumber(fnum, date)  # 根據航班號和日期查詢航班詳細信息和即時動態

輸入參數：

• fnum: 航班號 (如: CA3401)
• date: 航班起飛日期 (YYYY - MM - DD格式)

輸出信息：

• 航班號和代碼共享航班號
• 執飛航空公司
• 起飛和到達機場及航站樓
• 起飛和到達時間
• 執飛機型和飛行時長
• 航程距離和準點率
• 值機櫃臺和登機口
• 餐食和行李託運信息
• 天氣預報
• 聯繫電話

航班路線查詢

searchFlightRoutes(departure_city, destination_city, departure_date)  # 根據出發地、目的地和日期查詢可用航班

輸入參數：

• departure_city: 出發城市名稱或機場代碼 (如: "重慶", "CKG", "重慶(CKG)")
• destination_city: 目的地城市名稱或機場代碼 (如: "廣州", "CAN", "廣州(CAN)")
• departure_date: 出發日期 (YYYY - MM - DD格式)

輸出信息：

• 航班列表（包含航班號、航空公司、起飛到達時間、機場、航站樓、價格）
• 價格統計（最低價、最高價、平均價）
• 航空公司分佈統計
• 格式化的查詢結果輸出
• 支持的城市：282個國內城市和機場

支持的城市格式：

• 城市名：上海、北京、重慶、廣州等
• 機場代碼：SHA、BJS、CKG、CAN等
• 完整格式：上海(SHA)、北京(BJS)等

🔧 技術細節

技術架構

核心模塊 (Core)

• 航班數據處理

工具模塊 (Tools)

• 航班即時動態查詢工具

實用工具 (Utils)

• 數據驗證和格式化
• 日期時間處理
• API客戶端封裝

支持的傳輸協議

本服務器支持三種傳輸協議：

1. sse - Server - Sent Events（默認，適用於Web應用）
2. stdio - 標準輸入輸出（適用於Claude Desktop）
3. streamable - http - 可流式HTTP（適用於HTTP客戶端）

項目結構

FlightTicketMCPServer/
├── flight_ticket_server/
│   ├── core/              # 核心業務邏輯
│   ├── tools/             # MCP工具實現
│   ├── utils/             # 實用工具函數
│   └── main.py            # 服務器入口點
├── office_flight_ticket_server/  # 額外模塊
├── tests/                 # 測試文件
├── logs/                  # 日誌文件目錄
├── pyproject.toml         # 項目配置
├── requirements.txt       # 項目依賴
├── flight_ticket_server.py # 主啟動文件
├── mcp-config.json        # MCP配置示例
└── README.md              # 項目文檔

測試

# 運行所有測試
python -m pytest tests/ -v

# 運行基本功能測試
python -m pytest tests/test_basic.py -v

# 運行特定測試
python -m pytest tests/test_basic.py::TestFlightSearch::test_searchFlightsByNumber -v

日誌和調試

• 日誌文件位置：logs/ 目錄
• 啟用調試模式：設置 MCP_DEBUG=true
• 查看即時日誌：tail -f logs/flight_server.log

📄 許可證

MIT License - 查看 LICENSE 文件獲取詳細信息。

貢獻

歡迎提交Issue和Pull Request來改進這個項目。

支持

如果您遇到問題或有功能建議，請在GitHub上創建Issue。