Gtfs MCP Server

Nasza aplikacja udostępnia MCP po HTTP, dlatego skorzystaliśmy z MCP Inspector.

Po włączeniu aplikacji należy w terminalu, w folderze projektu, wykonać: npx -y @modelcontextprotocol/inspector owtorzy się w przeglądarce mcp inspector.

Należy uzupełnić:

• Transportation type: Streamabale http
• URL: http://localhost:8080/mcp i kliknąć "Connect".

Następnie należy w Tools wybrać "List tools"

Aplikacja Spring Boot integrująca dane GTFS Realtime (położenie pojazdów) oraz GTFS Static (rozkłady jazdy) komunikacji miejskiej w Krakowie. Udostępnia API REST do pobierania losowych odjazdów oraz wyszukiwania najszybszych połączeń bezpośrednich.

---

Co robi aplikacja

Aplikacja realizuje dwa główne zadania:

1. Obsługa Danych Realtime (Kamień Milowy 1)

• Pobiera plik TripUpdates.pb (Protobuf) z API ZTP Kraków.
• Parsuje dane binarne do obiektów Java.
• Wykorzystuje mechanizm Cache (@Cacheable, @CachePut) dla wydajności i odciążenia serwera ZTP.
• Wystawia endpoint zwracający losowy, aktualny odjazd tramwaju/autobusu.

2. Wyszukiwarka Połączeń i Baza Danych (Kamień Milowy 2)

• Pobiera i przetwarza plik GTFS_KRK.zip (dane statyczne: przystanki, trasy, kalendarz, czasy przejazdów).
• Importuje dane do lokalnej bazy SQLite przy starcie aplikacji (zabezpieczenie przed duplikacją danych).
• Posiada wyszukiwarkę najszybszych połączeń bezpośrednich między dwoma przystankami.
• Uwzględnia:
  • Kalendarz kursowania (dni tygodnia + wyjątki z calendar_dates.txt).
  • Opóźnienia rzeczywiste (Realtime Delay) pobierane na żywo z modułu Realtime.

---

Architektura Aplikacji

graph LR
%% Aktorzy i Systemy Zewnętrzne
    Client((Użytkownik))
    AI_Client((Klient AI / MCP))
    ZTP_Real[("ZTP API<br/>(Realtime PB)")]
    ZTP_Static[("ZTP API<br/>(Static ZIP)")]
    DB[("Baza SQLite<br/>(trams.db)")]

%% Aplikacja
    subgraph "Aplikacja: trams_web"
        style Client fill:#1e88e5,color:white
        style AI_Client fill:#9c27b0,color:white
        style ZTP_Real fill:#546e7a,color:white
        style ZTP_Static fill:#546e7a,color:white
        style DB fill:#546e7a,color:white

    %% 1. Warstwa Prezentacji
        subgraph "Warstwa Prezentacji"
            DepController["DepartureController<br/>(/departure)"]
            ConnController["DirectConnectionController<br/>(/connections)"]
            McpTools["TramsMcpTools<br/>(MCP Server)"]
        end

    %% 2. Warstwa Biznesowa
        subgraph "Warstwa Biznesowa"
            RealService["GtfsRealtimeService"]
            ConnService["DirectConnectionService"]
            NextService["NextDepartureService"]
            CalendarService["GtfsCalendarService"]
            StopService["StopQueryService"]

            subgraph "Logika wyboru"
                PickerInt("«interface»<br/>DeparturePicker")
                PickerImpl["RandomDeparturePicker"]
            end
        end

    %% 3. Warstwa Dostępu do Danych
        subgraph "Warstwa Danych"
            GtfsClient["GtfsClient<br/>(Cache Realtime)"]
            StaticLoader["GtfsStaticLoader"]
            ImportService["GtfsStaticImportService"]
            Repositories["JPA Repositories"]
        end

    %% Relacje
        Client --> ConnController
        ConnController --> ConnService
        Client --> DepController
        DepController --> RealService

        AI_Client --> McpTools
        McpTools --> ConnService
        McpTools --> NextService
        McpTools --> RealService
        McpTools --> StopService

        ConnService --> Repositories
        ConnService --> CalendarService
        ConnService --> RealService

        NextService --> Repositories
        NextService --> CalendarService
        NextService --> RealService

        StopService --> Repositories

        RealService --> GtfsClient
        RealService --> PickerInt
        PickerInt -.-> PickerImpl

        Repositories -.-> DB
        GtfsClient -.-> ZTP_Real

        StaticLoader -.-> ZTP_Static
        StaticLoader --> ImportService
        ImportService --> Repositories
    end

%% Style
    classDef spring fill:#4f8014,stroke:#333,stroke-width:1px;

    class DepController,ConnController,McpTools,RealService,ConnService,NextService,CalendarService,GtfsClient,StaticLoader,ImportService,Repositories,PickerInt,PickerImpl,StopService spring;

---

Kluczowe komponenty

Moduł Realtime (Losowy odjazd)

• Controller: DepartureController – obsługa HTTP (GET /departure) i delegowanie do serwisu.
• Service: GtfsRealtimeService – pobiera feed z GtfsClient i wybiera odjazd przez DeparturePicker.
• Client: GtfsClient – pobieranie TripUpdates.pb, parsowanie protobuf, cache (@Cacheable) i odświeżanie (@Scheduled + @CachePut).
• Strategy: DeparturePicker (interfejs) oraz RandomDeparturePicker (implementacja losowania odjazdu).
• Domain: Departure – rekord domenowy zwracany przez API.
• Exceptions:
  • DepartureNotFoundException → HTTP 404
  • GtfsConnectionException → HTTP 500

Moduł Static & Connections (Wyszukiwarka)

• Controller: DirectConnectionController – obsługa HTTP (GET /connections).
• Service: DirectConnectionService – łączy dane statyczne (rozkład), sprawdza kalendarz (GtfsCalendarService) i dodaje opóźnienia (Realtime).
• Loader: GtfsStaticLoader – pobiera plik ZIP przy starcie aplikacji.
• Repository: StopTimeRepository – wykonuje natywne zapytanie SQL (Self-Join) szukające połączeń.

---

API Endpoints

1. Losowy Odjazd

GET /departure

Zwraca losowy odjazd jako obiekt Departure.

200 OK (gdy znaleziono odjazd):

{
  "routeId": "52",
  "tripId": "123456",
  "stopId": "1234",
  "departureTime": "2025-12-15T10:30:00Z"
}

404 NOT FOUND
Gdy w danych GTFS nie ma żadnych odjazdów spełniających warunek (brak departure.time).
Rzucany jest DepartureNotFoundException.

500 INTERNAL SERVER ERROR
Gdy nie udało się pobrać lub sparsować feedu (np. problem sieciowy, niepoprawne dane).
Rzucany jest GtfsConnectionException.

2. Wyszukiwarka Połączeń (Najszybsze)

Zwraca najszybsze bezpośrednie połączenie między dwoma przystankami.

Parametry:

• from: Nazwa przystanku początkowego (np. "Teatr Bagatela")
• to: Nazwa przystanku końcowego (np. "Bronowice")

200 OK (gdy znaleziono połączenie):

{
  "lineNumber": "173",
  "fromStopName": "Muzeum Narodowe",
  "toStopName": "Przybyszewskiego",
  "departureTime": "2026-01-07T14:35:00",
  "arrivalTime": "2026-01-07T14:42:00",
  "delaySeconds": 120
}

400 BAD REQUEST Gdy podano nieistniejącą nazwę przystanku. Rzucany jest InvalidStopException.

404 NOT FOUND
Gdy nie znaleziono żadnego bezpośredniego połączenia. Rzucany jest ConnectionNotFoundException.

500 INTERNAL SERVER ERROR Błąd serwera.