Transit Real-Time Mobility

naftiko: "1.0.0-alpha1"

info:
  label: "Transit Real-Time Mobility"
  description: >-
    Workflow capability for real-time public transit information and multimodal
    trip planning. Used by transit apps, signage systems, and first/last-mile
    mobility platforms to display live departure times, plan multimodal trips,
    and surface service alerts.
  tags:
    - Public Transit
    - Real-Time
    - Trip Planning
    - Multimodal
    - Mobility
    - GTFS
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TRANSIT_API_KEY: TRANSIT_API_KEY

capability:
  consumes:
    - import: transit
      location: ./shared/transit.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: real-time-transit-api
      description: "Unified REST API for real-time transit data and trip planning."
      resources:
        - path: /v1/departures
          name: departures
          description: "Real-time departure boards for transit stops"
          operations:
            - method: GET
              name: get-departures
              description: "Get live departure times for one or more stops"
              call: "transit.get-stop-departures"
              with:
                stop_codes: "rest.stop_codes"
                max_departures: "rest.max_departures"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/trips
          name: trips
          description: "Multimodal trip planning"
          operations:
            - method: GET
              name: plan-trip
              description: "Plan a multimodal trip from origin to destination"
              call: "transit.plan-trip"
              with:
                origin_lat: "rest.origin_lat"
                origin_lon: "rest.origin_lon"
                destination_lat: "rest.destination_lat"
                destination_lon: "rest.destination_lon"
                time: "rest.time"
                arrive_by: "rest.arrive_by"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/networks
          name: networks
          description: "Available transit networks"
          operations:
            - method: GET
              name: list-networks
              description: "List transit networks near a location"
              call: "transit.list-networks"
              with:
                lat: "rest.lat"
                lon: "rest.lon"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/stops
          name: stops
          description: "Transit stops and stations"
          operations:
            - method: GET
              name: list-stops
              description: "List stops for a transit network"
              call: "transit.list-stops"
              with:
                network_id: "rest.network_id"
                lat: "rest.lat"
                lon: "rest.lon"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/alerts
          name: alerts
          description: "Active service alerts and disruptions"
          operations:
            - method: GET
              name: get-alerts
              description: "Get active service alerts"
              call: "transit.get-service-alerts"
              with:
                network_ids: "rest.network_ids"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/vehicles
          name: vehicles
          description: "Nearby transit vehicles and shared mobility"
          operations:
            - method: GET
              name: get-nearby-vehicles
              description: "Get nearby vehicles and shared mobility options"
              call: "transit.get-nearby-vehicles"
              with:
                lat: "rest.lat"
                lon: "rest.lon"
                radius: "rest.radius"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: real-time-transit-mcp
      transport: http
      description: "MCP server for AI-assisted transit planning and real-time information."
      tools:
        - name: get-stop-departures
          description: "Get live departure times for transit stops to display on signage or in apps"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.get-stop-departures"
          with:
            stop_codes: "tools.stop_codes"
            max_departures: "tools.max_departures"
          outputParameters:
            - type: object
              mapping: "$."

        - name: plan-multimodal-trip
          description: "Plan a trip combining public transit, walking, bikes, and scooters"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.plan-trip"
          with:
            origin_lat: "tools.origin_lat"
            origin_lon: "tools.origin_lon"
            destination_lat: "tools.destination_lat"
            destination_lon: "tools.destination_lon"
            time: "tools.time"
            arrive_by: "tools.arrive_by"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-transit-networks
          description: "List available transit networks and agencies near a location"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.list-networks"
          with:
            lat: "tools.lat"
            lon: "tools.lon"
          outputParameters:
            - type: object
              mapping: "$."

        - name: find-nearby-stops
          description: "Find transit stops near a geographic location"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.list-stops"
          with:
            network_id: "tools.network_id"
            lat: "tools.lat"
            lon: "tools.lon"
            radius: "tools.radius"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-service-alerts
          description: "Get active transit service disruptions and alerts"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.get-service-alerts"
          with:
            network_ids: "tools.network_ids"
            route_ids: "tools.route_ids"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-nearby-vehicles
          description: "Get real-time positions of transit vehicles and shared mobility near a location"
          hints:
            readOnly: true
            openWorld: true
          call: "transit.get-nearby-vehicles"
          with:
            lat: "tools.lat"
            lon: "tools.lon"
            radius: "tools.radius"
          outputParameters:
            - type: object
              mapping: "$."