Italian Travel Search MCP Server

意大利旅行搜索

一个非官方、只读的 TypeScript 服务，通过 HTTP 和模型上下文协议接口提供意大利长途巴士和火车实时搜索。

该项目将各运营商特有的站点目录、请求格式、票价结构和多程响应统一封装在一个共享的应用核心中。Italo 定价会初始化匿名技术会话和临时规划资源；不包含客户登录、票价选择、座位预订和付款功能。

重要

本项目与 Itabus、Autoservizi Salemi、Autolinee Federico、MarinoBus 或 FlixBus 无关，也未获得其认可。运营商名称和商标归其所有者所有。在启用实时适配器之前，请确认你的使用符合运营商条款、适用法律以及任何必要的授权。本仓库不授予数据提取或再分发权利。

功能

• 为不同预订平台上的地点和行程提供统一的响应模型。
• 为 5 家巴士运营商和 2 家火车运营商提供实时适配器。
• 一个运营商失败、另一个成功时，仍返回部分结果。
• 通过本地 stdio 或 /mcp 上的无状态 Streamable HTTP 提供 MCP，兼容旧版巴士工具，并提供单独的铁路工具。
• 直接通过 Trenitalia 和 Italo 的实时预订 API 搜索车站和行程。
• 提供官方链接，方便在运营商网站上手动继续搜索。
• 搜索遵循指定的出发日期；城市搜索会保留所有 Itabus 站点，并在可用时显示实际停靠点名称和地址。
• 铁路警告会指出报价中未包含的市内换乘。
• 返回结构化、按运营商区分的错误，而不会泄露上游响应。
• 对上游请求设置有限超时，并限制异步报价轮询次数。
• 地点缓存 1 小时，行程缓存 60 秒。
• 可选择启用不可变行程分页，使用 5 分钟的内存快照，由 HTTP 和 MCP 共用。
• 每个客户端在内存中限流为每分钟 60 个请求。
• 使用合成样本进行离线测试；测试套件绝不会访问运营商网站。
• 运行时依赖精简：官方 MCP SDK 和 Zod。

支持的运营商

运营商 ID	运营商	集成方式	地点	行程
itabus	Itabus	Demandware 端点	实时	实时
salemi	Autoservizi Salemi	Albatross 租户	实时	实时
federico	Autolinee Federico	Albatross 租户	实时	实时
marinobus	MarinoBus	Albatross 租户	实时	实时
flixbus	FlixBus	FlixBus 全球搜索 API	实时	实时

各运营商公开行为及其限制详见下方的巴士和火车 API 指南。

火车站、行程、价格和余票情况直接来自 Trenitalia 和 Italo 的预订 API。无需下载时刻表、数据集或大量存储空间，也无需运行初始化命令。如果某家运营商出错，其错误会与另一家运营商的结果一并报告。ViaggiaTreno 和 Italo 实时看板／独立状态查询互不依赖；Italo 报价会话会尽力清理。

要求

• Node.js 22.18 或更高版本
• npm

快速开始

git clone https://github.com/Alexxanddr/italian-travel-search.git
cd italian-travel-search
npm install
cp .env.example .env
npm start

服务器默认监听 http://127.0.0.1:3000。

curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/providers
curl http://127.0.0.1:3000/train-providers
curl 'http://127.0.0.1:3000/locations?query=Roma&provider=marinobus'

搜索行程时，请使用未来的实际日期：

curl 'http://127.0.0.1:3000/journeys?origin=Roma&destination=Milano&date=YYYY-MM-DD&adults=1&children=0&provider=marinobus'

YYYY-MM-DD 是占位符，运行命令前必须替换。

HTTP 接口

方法	路径	用途
GET	/health	进程存活状态
GET	/providers	适配器状态和运行原因
GET	/train-providers	列车运营商以及已配置的时刻表、价格和实时功能
GET	/locations	运营商地点搜索
GET	/journeys	规范化的单程行程搜索
GET	/train-locations	Trenitalia/Italo 车站搜索
GET	/train-journeys	实时铁路行程、可用情况和可为空的价格
GET	/train-status	启用时提供独立实时状态
GET	/station-board	启用时提供实时到达/出发信息
POST	/mcp	无状态 MCP Streamable HTTP 端点

/locations 和 /journeys 接受可选的 provider 参数。如果未提供，则会独立查询所有运营商，并在保留成功数据的同时返回按运营商区分的错误。

完整契约分为巴士 API和列车 API，共同行为汇总在HTTP API中。

MCP 服务

最简单的 MCP 配置是通过 npx 直接运行已发布的软件包：

{
  "mcpServers": {
    "italian-travel-search": {
      "command": "npx",
      "args": ["-y", "italian-travel-search@latest"]
    }
  }
}

或者，构建并启动本地 stdio 服务：

npm run build
npm run mcp:built

现有的巴士工具 list_providers、search_locations 和 search_journeys 保持兼容。地点和行程搜索接受可选的 offset/limit；持续将 offset 增加 limit，直到 truncated 为 false，即可获取所有分页。铁路功能新增 list_train_providers、search_train_locations、search_train_journeys、get_train_status 和 get_station_board。Trenitalia 和 Italo 的价格与实时适配器已启用；Italo 实时工具仍采用未验证日期语义。

对于完整行程搜索，首先使用 snapshot: true，然后仅使用返回的 searchId、offset 和 limit 继续搜索。这样可确保各分页的 价格、错误、顺序和总数完全一致。ID 过期后需要重新搜索。HTTP 也支持 相同的可选流程；请参阅稳定分页。

{
  "mcpServers": {
    "italian-travel-search": {
      "command": "node",
      "args": ["/absolute/path/to/italian-travel-search/dist/mcp/stdio.js"]
    }
  }
}

对于容器或远程 MCPHub 部署，请启动 HTTP 进程，并将客户端指向 http://italian-travel-search:3000/mcp。容器镜像为 ghcr.io/alexxanddr/italian-travel-search:latest。无需初始化数据集或使用持久卷。

权威的工具契约、限制、错误和开发命令请参阅 MCP 接口。

架构

应用分为四层：

1. HTTP 和 MCP 适配器验证各自传输方式的请求；
2. 共享验证和 SearchService 负责协调搜索和部分结果；
3. 各运营商适配器将远程协议转换为领域类型；
4. 领域模块负责规范化数据和错误契约。

运营商适配器实现了统一接口，因此调用方无需知道结果来自 Itabus Demandware 还是 Albatross 租户。有关模块、边界、数据流、缓存和测试策略，请参阅架构。

开发

npm run dev
npm run mcp
npm run check

npm run check 会运行完整的离线测试套件、TypeScript 类型检查和已配置的 lint 检查。要添加运营商，请遵循添加运营商；不要仅凭 HTML 推断新的集成，也不要将凭据复制到测试数据中。

部署

默认服务会刻意绑定到 loopback，并将速率限制和缓存状态保存在进程内存中。在将其置于反向代理之后或运行多个副本之前，请阅读运维。

项目文档

• HTTP API — 共同行为和错误约定。
• Bus API — 巴士服务提供方、地点、行程和示例。
• Train API — 铁路时刻表、实时价格/状态、来源信息和示例。
• MCP 接口 — 权威的工具、结果、限制和传输约定。
• 架构 — 模块、边界、流程和设计决策。
• 添加服务提供方 — 调研、实现和验证清单。
• 运维 — 配置、部署限制和故障处理。
• 术语表 — 稳定的项目术语。
• 贡献指南 — 本地工作流和拉取请求要求。
• 安全政策 — 私下报告漏洞和受支持的版本。
• Agent 指南 — 面向编码 Agent 的简要路由说明。

范围和限制

• 搜索仅支持单程。
• 可用性是服务提供方报告的信号，并不保证有座位或价格不变。
• 搜索和购买之间，价格和时刻表可能发生变化；铁路结果会提供实时观测信息和来源元数据。为保持兼容，保留旧字段名 timetableSource。
• 进程重启后，缓存和速率限制会重置，并且不会在多个副本间共享。
• 上游接口未经官方认可，且可能随时更改。
• 两种接口均有意排除账户、预订、付款和 CAPTCHA 处理。

请始终通过 bookingUrl 链接的服务提供方官方网站完成并确认购买。

贡献和安全

欢迎贡献；请从 CONTRIBUTING.md 开始。请按照 SECURITY.md 私下报告漏洞，不要通过公开议题报告。

许可证

源代码采用 MIT License。该许可证适用于此代码仓库中的代码，不涵盖第三方数据、服务提供方商标或访问上游系统的权利。