Italian Bus Search MCP Server

Italian Bus Search

An unofficial, read-only TypeScript service that searches multiple Italian coach operators through HTTP and Model Context Protocol interfaces.

The project hides provider-specific station catalogs, request formats, fare structures, and multi-leg responses behind one shared application core. It never performs login, booking, seat selection, or payment operations.

[!IMPORTANT] This project is not affiliated with or endorsed by Itabus, Autoservizi Salemi, Autolinee Federico, MarinoBus, or FlixBus. Provider names and trademarks belong to their owners. Before enabling a live adapter, confirm that your use complies with the provider's terms, applicable law, and any required authorization. This repository does not grant data-extraction or redistribution rights.

Features

• One response model for locations and journeys across different booking platforms.
• Live adapters for five operators.
• Partial results when one provider fails and another succeeds.
• A local stdio MCP server with structured, read-only tools.
• Official links for continuing a search manually on provider sites.
• Structured, provider-scoped errors instead of leaked upstream responses.
• Five-second upstream timeouts.
• One-hour location caches and 60-second journey caches.
• Per-client in-memory rate limiting at 60 requests per minute.
• Offline tests with synthetic fixtures; the test suite never contacts provider sites.
• A small runtime dependency surface: the official MCP SDK and Zod.

Supported providers

Provider behavior and the evidence behind each integration are recorded in Provider research.

Requirements

• Node.js 22.18 or newer
• npm

Quick start

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

The server listens on http://127.0.0.1:3000 by default.

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'

For journey searches, use a real future date:

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 is a placeholder and must be replaced before running the command.

HTTP interface

/locations and /journeys accept an optional provider parameter. Without it, all providers are queried independently and successful data is preserved alongside provider-scoped errors.

The complete parameter, response, status, and error contract is in HTTP interface.

MCP server

The simplest MCP configuration runs the published package directly with npx:

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

Alternatively, build and start the local stdio server:

npm run build
npm run mcp:built

It exposes list_providers, search_locations, and search_journeys. A host model can turn “find buses from Rome to Milan on 15 November” into the location and journey tool calls, then show normalized options with official links for manual purchase.

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

See MCP interface for the authoritative tool contract, limits, errors, and development command.

Architecture

The application has four layers:

1. HTTP and MCP adapters validate their transport-specific requests;
2. shared validation and SearchService orchestrate searches and partial results;
3. each provider adapter translates a remote protocol into domain types;
4. the domain module owns normalized data and error contracts.

Provider adapters implement one shared interface, so callers do not know whether a result came from Itabus Demandware or an Albatross tenant. See Architecture for modules, seams, data flow, caches, and test strategy.

Development

npm run dev
npm run mcp
npm run check

npm run check runs the complete offline test suite, TypeScript type checking, and the configured lint check. To add an operator, follow Adding a provider; do not infer a new integration from HTML alone or copy credentials into fixtures.

Deployment

The default server deliberately binds to loopback and keeps rate-limit and cache state in process memory. Read Operations before placing it behind a reverse proxy or running multiple replicas.

Project documentation

• HTTP interface — authoritative endpoint and error contract.
• MCP interface — authoritative tools, results, limits, and stdio contract.
• Architecture — modules, seams, flows, and design decisions.
• Adding a provider — research, implementation, and verification checklist.
• Operations — configuration, deployment constraints, and failure handling.
• Provider research — primary-source evidence and known limitations.
• Glossary — stable project terminology.
• Contributing — local workflow and pull-request expectations.
• Security policy — private vulnerability reporting and supported versions.
• Agent instructions — compact routing instructions for coding agents.

Scope and limitations

• Searches are one-way only.
• Availability is a provider-reported signal, not a seat or price guarantee.
• Prices and schedules can change between search and purchase.
• Caches and rate limits reset when the process restarts and are not shared across replicas.
• Upstream interfaces are unofficial and can change without notice.
• Both interfaces intentionally exclude accounts, bookings, payments, and CAPTCHA handling.

Always complete and confirm a purchase on the official provider site linked by bookingUrl.

Contributing and security

Contributions are welcome; start with CONTRIBUTING.md. Report vulnerabilities privately according to SECURITY.md, not through a public issue.

License

Source code is available under the MIT License. The license covers this repository's code, not third-party data, provider trademarks, or access rights to upstream systems.