Project for the Object-Oriented Technologies (TO) course
AGH University of Science and Technology
Group 6
The goal of this project is to build a backend system for querying public transport data for the city of Kraków, based on GTFS Static and GTFS Realtime feeds.
The system evolves across milestones:
- M1: basic server + GTFS Realtime
- M2: GTFS Static + routing logic
- M3: Model Context Protocol (MCP) server with AI-oriented tooling and E2E validation
The project root directory contains a docker-compose.yml file.
docker compose up -dThis starts:
- PostgreSQL database
- all required infrastructure services
The application is a standard Spring Boot project.
You can start it:
- directly from an IDE (run
ToZtpApplication) - with the active Spring profile of your choice (e.g.
dev,test)
This project exposes its functionality via a Model Context Protocol (MCP) server using stdio communication (JSON-RPC over stdin/stdout).
The server follows the MCP specification: https://modelcontextprotocol.io/specification/draft/basic/lifecycle
Supported protocol version:
2024-11-05
Each JSON message must be sent separately as a single line.
The client announces protocol version and capabilities.
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {} } }This confirms the client is ready.
{ "jsonrpc": "2.0", "method": "notifications/initialized" }This returns all MCP tools exposed by the server.
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }Lists unique stop names using cursor-based pagination.
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "listStops", "arguments": { "limit": 5 } } }You can add the lastStopName argument to continue listing from the given stop.
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "listStops", "arguments": { "limit": 10, "lastStopName": "AKF / PK" } } }The returned hasNext will be true if there are more stops ahead to be listed and will turn false when you get to the last few alphabetically. You can see that with:
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "listStops", "arguments": { "limit": 5, "lastStopName": "Żmujdzka" } } }Returns up to 3 direct connections that depart the soonest, taking real-time delays into account.
{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "findFastestConnections", "arguments": { "fromStop": "Teatr Bagatela", "toStop": "Bronowice Małe" } } }Optional parameters:
date(yyyy-MM-dd)time(HH:mm or HH:mm:ss)
Returns next 5 departures for a given stop and line, including real-time delays.
{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "listNextDepartures", "arguments": { "stopName": "Teatr Bagatela", "lineNumber": "4" } } }- Basic Spring Boot server
- GTFS Realtime (TripUpdates) parsing using Protocol Buffers
- REST endpoint returning:
- random stop
- random vehicle
- random departure time
- Full GTFS Static parsing:
- stops, routes, trips, stop_times
- calendar and calendar_dates
- Database persistence for fast querying
- Automatic GTFS Static refresh
- Routing logic for:
- direct connections only
- calendar rules and exceptions
- GTFS Realtime delays
- MCP server based on Spring AI MCP
- MCP tools providing:
- listing all unique stop names (cursor-based pagination)
- finding 3 fastest connections between two stops
- listing next 5 departures for a given stop and line
- Real-time delay handling integrated into MCP responses
- Clean separation between:
- domain logic
- MCP layer
- DTOs
- External E2E MCP client communicating via stdio
- E2E testing approach:
- application started as an external process
- MCP client sends JSON-RPC commands
- no mocking of repositories or services
- Szymon Barczyk
- Jan Dyląg
- Wojciech Dąbek