SpotHero Parking Mobility

naftiko: "1.0.0-alpha1"

info:
  label: "SpotHero Parking Mobility"
  description: >-
    Unified parking mobility workflow capability for SpotHero, enabling navigation apps,
    rideshare platforms, connected car dashboards, and event management systems to search,
    book, and manage parking reservations across North America's largest off-street parking network.
    Covers the full parking lifecycle from search to check-in and cancellation.
  tags:
    - SpotHero
    - Parking
    - Mobility
    - Navigation
    - Reservations
    - Transportation
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SPOTHERO_API_KEY: SPOTHERO_API_KEY

capability:
  consumes:
    - import: spothero
      location: ./shared/spothero-parking.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: parking-mobility-api
      description: "Unified REST API for parking mobility workflows."
      resources:
        - path: /v1/search
          name: parking-search
          description: "Search for available parking near a destination"
          operations:
            - method: GET
              name: search-parking
              description: "Search for available parking by location and time"
              call: "spothero.search-parking"
              with:
                latitude: "rest.latitude"
                longitude: "rest.longitude"
                address: "rest.address"
                starts: "rest.starts"
                ends: "rest.ends"
                radius: "rest.radius"
                vehicle_type: "rest.vehicle_type"
                sort: "rest.sort"
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/facilities/{facility_id}
          name: facility-details
          description: "Detailed information about a parking facility"
          operations:
            - method: GET
              name: get-facility
              description: "Get parking facility details, amenities, and directions"
              call: "spothero.get-facility"
              with:
                facility_id: "rest.facility_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/facilities/{facility_id}/availability
          name: facility-availability
          description: "Real-time parking availability at a facility"
          operations:
            - method: GET
              name: get-facility-availability
              description: "Check if parking is available at a facility for a time period"
              call: "spothero.get-facility-availability"
              with:
                facility_id: "rest.facility_id"
                starts: "rest.starts"
                ends: "rest.ends"
                vehicle_type: "rest.vehicle_type"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/facilities/{facility_id}/rates
          name: facility-rates
          description: "Pricing rates for a parking facility"
          operations:
            - method: GET
              name: get-facility-rates
              description: "Get hourly, daily, and event rates for a facility"
              call: "spothero.get-facility-rates"
              with:
                facility_id: "rest.facility_id"
                starts: "rest.starts"
                ends: "rest.ends"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/reservations
          name: reservations
          description: "Parking reservation management"
          operations:
            - method: GET
              name: list-reservations
              description: "List parking reservations with optional filters"
              call: "spothero.list-reservations"
              with:
                status: "rest.status"
                facility_id: "rest.facility_id"
                limit: "rest.limit"
                offset: "rest.offset"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-reservation
              description: "Book a parking reservation at a facility"
              call: "spothero.create-reservation"
              with:
                facility_id: "rest.facility_id"
                rate_id: "rest.rate_id"
                starts: "rest.starts"
                ends: "rest.ends"
                driver: "rest.driver"
                vehicle: "rest.vehicle"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/reservations/{reservation_id}
          name: reservation
          description: "Individual reservation operations"
          operations:
            - method: GET
              name: get-reservation
              description: "Get details for a specific reservation"
              call: "spothero.get-reservation"
              with:
                reservation_id: "rest.reservation_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: cancel-reservation
              description: "Cancel a parking reservation"
              call: "spothero.cancel-reservation"
              with:
                reservation_id: "rest.reservation_id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: parking-mobility-mcp
      transport: http
      description: "MCP server for AI-assisted parking search, booking, and management."
      tools:
        - name: search-parking
          description: "Search for available parking near a location or address for a given time period. Returns facility names, prices, availability, and amenities."
          hints:
            readOnly: true
            openWorld: true
          call: "spothero.search-parking"
          with:
            latitude: "tools.latitude"
            longitude: "tools.longitude"
            address: "tools.address"
            starts: "tools.starts"
            ends: "tools.ends"
            radius: "tools.radius"
            vehicle_type: "tools.vehicle_type"
            sort: "tools.sort"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-parking-facility
          description: "Get detailed information about a specific parking facility including address, amenities, operating hours, and entry/exit instructions."
          hints:
            readOnly: true
            openWorld: true
          call: "spothero.get-facility"
          with:
            facility_id: "tools.facility_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: check-parking-availability
          description: "Check real-time parking availability and pricing at a specific facility for a time period."
          hints:
            readOnly: true
            openWorld: true
          call: "spothero.get-facility-availability"
          with:
            facility_id: "tools.facility_id"
            starts: "tools.starts"
            ends: "tools.ends"
            vehicle_type: "tools.vehicle_type"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-parking-rates
          description: "Get hourly, daily, event, and monthly pricing rates for a parking facility."
          hints:
            readOnly: true
            openWorld: true
          call: "spothero.get-facility-rates"
          with:
            facility_id: "tools.facility_id"
            starts: "tools.starts"
            ends: "tools.ends"
          outputParameters:
            - type: object
              mapping: "$."

        - name: book-parking
          description: "Create a parking reservation at a facility. Returns confirmation code and barcode for facility access."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "spothero.create-reservation"
          with:
            facility_id: "tools.facility_id"
            rate_id: "tools.rate_id"
            starts: "tools.starts"
            ends: "tools.ends"
            driver: "tools.driver"
            vehicle: "tools.vehicle"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-reservation
          description: "Get full details for a parking reservation including status, barcode, and confirmation code."
          hints:
            readOnly: true
            openWorld: false
          call: "spothero.get-reservation"
          with:
            reservation_id: "tools.reservation_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-reservations
          description: "List parking reservations filtered by status, date range, or facility."
          hints:
            readOnly: true
            openWorld: false
          call: "spothero.list-reservations"
          with:
            status: "tools.status"
            facility_id: "tools.facility_id"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."

        - name: cancel-parking-reservation
          description: "Cancel a parking reservation. Refund eligibility depends on facility policy and cancellation timing."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "spothero.cancel-reservation"
          with:
            reservation_id: "tools.reservation_id"
          outputParameters:
            - type: object
              mapping: "$."