faregrid

faregrid

faregrid 是一个小型本地桥接程序，连接托管的 FlightPowers MCP 服务，该服务从 Google Flights 读取实时报价。 提供出发地和目的地，以及单个日期或整个日期范围， 它便会返回票价、航空公司、飞行时长、中转次数、 每个航班的可预订链接，以及历史价格区间，用于显示该航线的票价是 异常便宜还是昂贵。

此桥接程序不保存自己的票价数据。它会在本地提供上游服务的工具列表， 内容与从实时端点捕获的完全一致，并将每次工具调用转发到上游， 原样返回结果。捕获到的接口仅支持搜索：结果包含指向供应商自有预订流程的 buy_link，其中没有预订、购买或支付工具。

工具

• search_oneway_flights — 单程票价。必填： from_airport 和 to_airport（IATA 代码；目的地可以是多个代码，如 "BCN,LIS,ATH" 或 ["BCN","LIS","ATH"]）。可选：departure_date，或通过 departure_date_from / departure_date_to 指定日期范围、max_stops、airline_codes、exclude_airline_codes、出发和到达时段、currency（默认 "usd"）、max_price、seat_type、passengers、sort_by（默认 "best"）、limit（默认 10）、max_searches、use_fallback 和 verbose。一次调用即可搜索日期范围内的每种日期／目的地组合。
• search_roundtrip_flights — 往返票价，按往返航段配对计价，而非作为两张单程票分别计价。 必填：from_airport 和 to_airport。可选：与单程工具相同的出发日期或日期范围字段，以及 return_date 或 nights（行程天数，或类似 [5, 6, 7] 的列表）、max_departure_stops、max_return_stops、departure_airline_codes、return_airline_codes、returns_per_outbound，以及共享字段 currency、max_price、seat_type、passengers、sort_by、limit、max_searches、use_fallback 和 verbose。

票价会在几分钟内过期，因此当前价格始终来自新的搜索，而非先前的结果。

配置

• FLIGHTPOWERS_MCP_URL（可选）——覆盖上游端点。默认值为 https://flights.flightpowers.com/mcp。（此覆盖钩子是本次重建自行标注的还原。）
• FLIGHTPOWERS_API_KEY（可选）——设置后，每个上游请求都会携带 x-rapidapi-key: <key> 标头，使用调用者自己的 Google Flights Live API RapidAPI 密钥。未设置时，不会发送密钥标头，上游会应用其免费登录额度。绝不会发送 Authorization 标头。（此转发方式也是自行标注的还原；原始接口是在无密钥状态下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo name faregrid），再发送 notifications/initialized 通知，然后发送携带调用者参数且不作更改的 tools/call 请求。上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会随会话的每个后续请求发送；此会话会在进程存续期间重复使用。回复可能是普通 JSON，也可能是服务器发送事件；两种格式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或无法完成的请求——都会作为 isError 结果返回，其文本以 faregrid error: 开头（此错误呈现方式是本次重建自行标注的还原）。

CLI

每个工具也可以作为子命令使用，并接受一个 JSON 参数字符串：

npx @reneturcios/faregrid search_oneway_flights '{"from_airport":"TLV","to_airport":"BCN","departure_date":"2026-11-10"}'
npx @reneturcios/faregrid search_roundtrip_flights '{"from_airport":"TLV","to_airport":"BCN,LIS","departure_date_from":"2026-11-01","departure_date_to":"2026-11-07","nights":[3,4]}'
npx @reneturcios/faregrid --version

退出代码：成功时为 0，结果带有 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/faregrid mcp

MCP 客户端配置：

{
  "mcpServers": {
    "faregrid": {
      "command": "npx",
      "args": ["-y", "@reneturcios/faregrid", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/faregrid
docker run --rm ghcr.io/cloudcorprecords/faregrid --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数则会正常传递给命令行工具。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全通过模拟的 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT — 请参阅 LICENSE。