国内低价航班路线发现 MCP

这是一个本地运行的 Python MCP Server，用来比较中国大陆境内航班方案。你可以让 支持 MCP 的 AI 客户端搜索低价路线，再在准备购买时重新核验价格和可售状态。

项目当前的 MVP 使用意图是：

• 中国大陆境内民航路线；
• 单程；
• 1 名成人；
• 经济舱。

MVP 实际支持的出发/目的城市以随包静态表 src/flight_deals_mcp/data/airports.json 为准（当前约 30 个主要城市）， 不在表内的城市不会生成扩展候选。这是有意收窄的覆盖范围，不等于覆盖全部 大陆民航城市。

服务会向上游发送出发地、目的地、日期，并发送经济舱和单程等上游支持的约束。但是， 官方 @fly-ai/flyai-cli 1.0.16 所带 search_flight schema 不提供乘客人数参数。 因此，“1 名成人”目前是本项目固定的搜索意图，实际报价依赖上游默认语义，尚未经过 独立验证；购买页必须再次确认该价格确实适用于 1 名成人。项目不会向上游编造 adult_count 或其他不存在的字段。

它只提供两个 MCP 工具：

1. find_flight_options：查询直飞/官方联程基准，并尝试受约束的扩展策略；
2. verify_flight_option：在购买前重新查询所选方案，核对价格、可售状态、航段和链接。

本项目不会创建订单、收款、支付、出票、退改签，也不代替航空公司或售票平台的 最终页面。即使首次搜索刚完成，购买前也必须调用 verify_flight_option；只有外部 售票页当时显示的价格、库存和规则才是最终依据。

验收状态

自动化 MVP 与审查修复已完成。正式 Key 下 24/24 矩阵行已完成基准搜索、购买前 核验与 HTTPS 短链可达检查（baseline-only）。登录后购买页价格与单成人适用性仍未人工 确认，扩展策略未覆盖，因此未通过生产验收。状态矩阵见 docs\acceptance\manual-route-matrix.md。

它会尝试哪些策略

• 直飞/官方联程：低风险基准，以数据源返回的完整报价为准。
• 日期浮动：可搜索原日期前后各 1 天。
• 同城机场：比较同一城市不同机场的方案，注意地面交通时间和费用。
• 自拼中转：两张彼此独立的机票，可能更便宜，但没有联程保护；前序延误、 行李提取再托运和误机损失通常需要旅客自行承担。
• 隐藏城市：仅在 exploratory 且不托运行李时显示，并固定标为高风险。航变 可能绕过真实目的地，弃乘可能影响后续票联，航司可能重新计价，行李可能被运到 票面终点。它不是默认推荐，也不保证更便宜或可实际使用。

任何扩展策略都只是候选。coverage.completed、coverage.failed 和 coverage.skipped 会说明实际完成、失败和跳过了哪些搜索；部分结果不等于覆盖了 整个市场。

Windows PowerShell 安装

1. 准备环境

需要：

• Python 3.12；
• uv；
• 使用默认 official_cli 模式时，还需要 Node.js、npm 和官方 FlyAI CLI。

在 PowerShell 中确认命令可用：

python --version
uv --version
node --version
npm --version

进入项目目录并创建环境：

Set-Location 'D:\董鹏超\flight-deals-mcp'
uv sync

本文后续可直接复制的配置使用当前机器真实路径 D:\董鹏超\flight-deals-mcp 和 C:\Users\Administrator\.local\bin\uv.exe。移动项目或换一台电脑后，请用 (Get-Command uv).Source 查询 uv，并把所有绝对路径替换成新位置。

2. 安装并配置官方 FlyAI CLI

安装当前验证的官方 CLI 版本：

npm install --global '@fly-ai/flyai-cli@1.0.16'
flyai --help

推荐的稳定路径：official_cli + 正式 Key

FlyAI 官方快速开始建议配置正式 Key，以获得更充足的调用次数和更稳定的服务。本项目 也把“官方 CLI + 正式 Key”作为首选正式使用路径：

$env:FLYAI_API_KEY = '替换为你的正式 Key'
flyai config set FLYAI_API_KEY $env:FLYAI_API_KEY
$env:FLIGHT_PROVIDER_MODE = 'official_cli'

official_cli 是项目默认模式，所以最后一行可以省略。flyai config set 会把 Key 交给官方 CLI 的本地配置管理；不要把真实 Key 写进 README、Git 或聊天记录。配置后 重启 MCP 客户端，确保它能从 PATH 找到 flyai/flyai.cmd。

无 Key 的 official_cli 体验路径

本机探测表明，安装官方 CLI 后，不设置 FLYAI_API_KEY 也可能获得体验调用。它不是 官方稳定服务承诺，能力、次数、稳定性和返回范围都可能受限，只适合本地试用。默认 设置仍是：

$env:FLIGHT_PROVIDER_MODE = 'official_cli'

Windows 上官方 CLI 有时会先输出业务成功 JSON（status: 0），随后在 Node.js 退出 阶段返回退出码 1。本项目会接受该成功业务载荷，同时把非零退出信息保留为警告；若 业务 status 不是 0，仍会按失败处理。

实验性、未实测：direct_mcp

direct_mcp 是实验性、未实测的标准 Bearer-Key 直连路径，不是当前推荐或已验收的 生产路径。该代码路径要求从 FlyAI 官方控制台取得正式 Key：

$env:FLIGHT_PROVIDER_MODE = 'direct_mcp'
$env:FLYAI_API_KEY = '替换为你的正式 Key'
$env:FLYAI_MCP_URL = 'https://flyai.open.fliggy.com/mcp'

没有正式 FLYAI_API_KEY 时，direct_mcp 会拒绝启动。本项目尚未用正式 Key 对该 Bearer 路径做实时验证；优先使用上面的官方 CLI 正式 Key 流程。不要从 CLI 中提取或 复制私有签名、内置凭据或未公开请求头。

3. 在终端试启动

uv run flight-deals-mcp

这是 stdio Server，启动后安静等待 MCP 客户端发送协议消息是正常现象。不要在同一 终端向它输入普通聊天文字；按 Ctrl+C 可停止。

Codex stdio 配置

Codex 使用 CLI 注册 MCP，或读取 config.toml 的 [mcp_servers.<id>]，不使用 Claude Desktop 风格的 mcpServers JSON。

方式一：Codex CLI

在 PowerShell 中运行以下完整命令：

codex mcp add flight-deals --env FLIGHT_PROVIDER_MODE=official_cli -- 'C:\Users\Administrator\.local\bin\uv.exe' --directory 'D:\董鹏超\flight-deals-mcp' run flight-deals-mcp

这里让 uv --directory 把 Server 工作目录固定到项目目录。正式 Key 应先通过 flyai config set FLYAI_API_KEY ... 交给官方 CLI，不要直接写进命令历史。

方式二：Codex config.toml

把下面配置加入 Codex 的 config.toml：

[mcp_servers.flight-deals]
command = 'C:\Users\Administrator\.local\bin\uv.exe'
args = ["run", "flight-deals-mcp"]
cwd = 'D:\董鹏超\flight-deals-mcp'
startup_timeout_sec = 90
tool_timeout_sec = 90

[mcp_servers.flight-deals.env]
FLIGHT_PROVIDER_MODE = "official_cli"

搜索服务自身总预算为 60 秒，因此启动和工具超时均设为 90 秒，避免客户端先于 Server 结束调用。保存后完全退出并重启 Codex；它应只发现 find_flight_options 和 verify_flight_option 两个工具。

Claude Desktop / 通用 JSON stdio 配置

以下是使用 mcpServers 的客户端常见结构，包括 Claude Desktop 风格配置。它是完整、 有效的 JSON，反斜杠必须写成 \\：

{
  "mcpServers": {
    "flight-deals": {
      "command": "C:\\Users\\Administrator\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "D:\\董鹏超\\flight-deals-mcp",
        "run",
        "flight-deals-mcp"
      ],
      "env": {
        "FLIGHT_PROVIDER_MODE": "official_cli"
      }
    }
  }
}

Codex 不使用上述 JSON；Codex 请使用前一节的 CLI 或 TOML。其他客户端的具体配置文件 位置由客户端决定。换机器后用下面命令取得 uv.exe 的实际绝对路径：

(Get-Command uv).Source

保存配置后完全退出并重启 MCP 客户端。客户端应只发现两个工具。

推荐使用方式

先请 AI 调用搜索工具，例如：

搜索 2026-08-12 北京到杭州，前后可浮动 1 天，不托运行李，最长 10 小时， 风险偏好 balanced。

当你选中一个 option_id 后，再明确要求：

购买前用刚才的 search_id 和 option_id 重新核验。

核验会重新访问数据源，不会把缓存中的旧价格冒充实时价格。随后仍要自行打开最新 HTTPS 购买链接，确认报价适用于 1 名成人，并核对航班、日期、机场、经济舱、行李、 退改规则和总价，再决定是否购买。上游没有乘客人数入参，所以这一步不能省略。

数据与缓存在哪里

• 机场与候选目的地静态数据随 Python 包发布，源码位于 src\flight_deals_mcp\data\airports.json 和 src\flight_deals_mcp\data\onward_destinations.json。
• 搜索快照使用 SQLite，默认写到进程工作目录下的 .local\flight-deals.db。
• 上面的 Codex TOML 通过 cwd、CLI/JSON 通过 uv --directory D:\董鹏超\flight-deals-mcp 固定工作目录，因此当前缓存位置为 D:\董鹏超\flight-deals-mcp\.local\flight-deals.db。
• 普通搜索缓存默认有效 5 分钟；过期快照只用于购买前核验时定位旧方案和比较变化， 当前报价仍会重新查询。

缓存包含搜索条件和航班报价。它不应包含姓名、身份证、手机号或支付数据，但路线和 日期仍可能反映个人出行意图，请不要上传、提交或随意共享 .local 目录。

常见问题

客户端提示找不到 uv

运行 (Get-Command uv).Source，把输出的绝对路径复制到 TOML 或 JSON 的 command， 或 Codex CLI 命令的可执行文件位置。确认该文件存在，保存后重启客户端。

提示 flyai CLI is not installed

默认模式需要官方 CLI。重新执行：

npm install --global '@fly-ai/flyai-cli@1.0.16'
Get-Command flyai

若 PowerShell 能找到但客户端仍找不到，请完全退出并重启客户端；必要时确认客户端 进程的 PATH 包含 npm 全局命令目录。

提示 FLYAI_API_KEY is required

你选择了实验性的 direct_mcp。若必须试验该路径，请配置正式 Key；首选做法是改回 official_cli，安装官方 CLI，再运行 flyai config set FLYAI_API_KEY $env:FLYAI_API_KEY。

没有结果、只有部分策略或发生超时

先看 coverage 和 warnings。免 Key 体验可能有额度、能力或稳定性限制；上游无 结果只表示“当前数据源未发现”，不代表市场上不存在。可以缩小日期浮动、稍后重试， 或按官方推荐为 official_cli 配置正式 Key。

修改配置后仍使用旧环境变量

MCP 客户端通常只在启动 Server 时读取 env。保存 TOML/JSON 或修改 Codex MCP 注册 后彻底退出客户端，再重新打开。不要只关闭一个聊天窗口。

SQLite 被占用或缓存异常

先停止所有正在使用本项目的 MCP Server。缓存只是短时搜索快照；需要重置时，可先 备份再删除项目下的 .local\flight-deals.db，下次启动会自动重建。

测试与构建

在项目根目录运行：

uv run pytest -v
uv run ruff check .
uv build

只运行产品验收层：

uv run pytest tests/test_acceptance.py -v

构建产物会出现在 dist。人工路线核对模板与当前执行状态见 docs\acceptance\manual-route-matrix.md。自动化命令和单条烟雾测试通过不表示 24 条路线已经完成人工核对，也不表示已通过生产验收。

安全与隐私

• Key 只通过环境变量或本地安全配置注入，不写入源码、测试、日志或 MCP 输出。
• 含真实 Key 的客户端配置也属于秘密，不要提交到 Git 或发给他人。
• 服务不收集乘机人身份信息，不接收支付信息，也没有下单能力。
• 购买链接必须通过 HTTPS 模型校验，但 HTTPS 不等于页面一定可靠；仍需核对域名和 页面内容。
• 不绕过验证码、登录、限流或平台访问控制。
• 默认只使用本地 stdio，不监听公网端口。
• 分享日志或缓存前先检查路线、日期、链接和上游错误信息是否会暴露个人行程或凭据。