Italian Bus and Rail Search MCP Server

意大利巴士搜索

一个非官方、只读的 TypeScript 服务，通过 HTTP 和 Model Context Protocol 接口搜索多家意大利长途客车运营商。

本项目将各服务商特有的车站目录、请求格式、票价结构和多段行程响应封装在统一的应用核心后。它绝不执行登录、预订、选座或支付操作。

重要

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

功能

• 为不同预订平台上的地点和行程提供统一的响应模型。
• 为 4 家运营商提供实时适配器。
• 一家服务商失败、另一家成功时，仍返回部分结果。
• 提供本地 stdio MCP 服务，包含结构化的只读工具。
• 提供服务商官网链接，方便用户手动继续搜索。
• 返回结构化且限定服务商范围的错误，而非泄露上游响应。
• 上游请求超时时间为 5 秒。
• 地点缓存 1 小时，行程缓存 60 秒。
• 按客户端进行内存限流，每分钟 60 次请求。
• 使用合成样例进行离线测试；测试套件绝不会访问服务商网站。
• 运行时依赖精简：官方 MCP SDK 和 Zod。

支持的服务商

服务商 ID	运营商	集成方式	地点	行程
itabus	Itabus	Demandware 端点	实时	实时
salemi	Autoservizi Salemi	Albatross 租户	实时	实时
federico	Autolinee Federico	Albatross 租户	实时	实时
marinobus	MarinoBus	Albatross 租户	实时	实时

服务商行为及各项集成的依据记录在服务商研究中。

要求

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

快速开始

git clone https://github.com/Alexxanddr/italian-bus-search.git
cd italian-bus-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/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	/locations	搜索服务商地点
GET	/journeys	规范化的单程行程搜索

/locations 和 /journeys 接受可选的 provider 参数。不指定时，系统会分别查询所有服务商，并在返回成功数据的同时保留各服务商对应的错误。

完整的参数、响应、状态和错误约定见 HTTP 接口。

MCP 服务

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

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

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

npm run build
npm run mcp:built

它提供 list_providers、search_locations 和 search_journeys。宿主模型可以将“查找 11 月 15 日从罗马到米兰的巴士”转换为地点和行程工具调用，然后展示规范化的选项及官网链接，供用户手动购票。

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

权威的工具约定、限制、错误和开发命令请参阅 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 推断新的集成，也不要将凭据复制到测试夹具中。

部署

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

项目文档

• HTTP 接口 — 权威的端点和错误约定。
• MCP 接口 — 权威的工具、结果、限制和 stdio 约定。
• 架构 — 模块、衔接点、流程和设计决策。
• 添加提供方 — 研究、实现和验证清单。
• 运维 — 配置、部署限制和故障处理。
• 提供方调研 — 一手资料证据和已知限制。
• 术语表 — 稳定的项目术语。
• 贡献指南 — 本地工作流和拉取请求要求。
• 安全策略 — 私下报告漏洞的方式和受支持的版本。
• Agent 说明 — 面向编码 Agent 的简明路由说明。

范围和限制

• 仅支持单程搜索。
• 可用性是提供方报告的信号，不代表座位或价格保证。
• 价格和时刻表可能在搜索和购买之间发生变化。
• 进程重启后，缓存和速率限制都会重置，且不会在多个副本之间共享。
• 上游接口未经官方认可，且可能随时变更。
• 两种接口都刻意排除账户、预订、付款和 CAPTCHA 处理。

请始终在 bookingUrl 链接的官方提供方网站上完成并确认购买。

贡献和安全

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

许可证

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