Volkswagen Vehicle Configuration

naftiko: "1.0.0-alpha1"

info:
  label: "Volkswagen Vehicle Configuration"
  description: >-
    Unified capability for the Volkswagen OKAPI vehicle configurator workflow.
    Enables browsing the VW Group product catalog across global markets,
    configuring vehicles with options, validating buildability, and retrieving
    order information, WLTP emissions, and vehicle images. Used by automotive
    retailers, configurator apps, and digital sales platforms.
  tags:
    - Volkswagen
    - Automotive
    - Vehicle Configuration
    - Product Data
    - Configurator
    - Sales
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VOLKSWAGEN_OKAPI_TOKEN: VOLKSWAGEN_OKAPI_TOKEN

capability:
  consumes:
    - import: volkswagen-okapi
      location: ./shared/volkswagen-okapi.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: volkswagen-config-api
      description: "Unified REST API for VW vehicle configuration and product data."
      resources:
        - path: /v1/countries
          name: countries
          description: "List supported markets."
          operations:
            - method: GET
              name: list-countries
              description: "List countries where VW OKAPI is available."
              call: "volkswagen-okapi.list-countries"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalog/{countryCode}/brands
          name: brands
          description: "VW Group brands in a market."
          operations:
            - method: GET
              name: list-brands-by-country
              description: "List brands available in the country."
              call: "volkswagen-okapi.list-brands-by-country"
              with:
                countryCode: "rest.countryCode"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalog/{countryCode}/brands/{brandId}/models
          name: models
          description: "Models by brand and market."
          operations:
            - method: GET
              name: list-models-by-brand
              description: "List models for a brand."
              call: "volkswagen-okapi.list-models-by-brand"
              with:
                countryCode: "rest.countryCode"
                brandId: "rest.brandId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalog/{countryCode}/models/{modelId}/types
          name: types
          description: "Vehicle types by model."
          operations:
            - method: GET
              name: list-types-by-model
              description: "List vehicle types."
              call: "volkswagen-okapi.list-types-by-model"
              with:
                countryCode: "rest.countryCode"
                modelId: "rest.modelId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalog/{countryCode}/types/{typeId}/options
          name: options
          description: "Configurable options for a type."
          operations:
            - method: GET
              name: list-options-by-type
              description: "List configurable options."
              call: "volkswagen-okapi.list-options-by-type"
              with:
                countryCode: "rest.countryCode"
                typeId: "rest.typeId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/configuration/{countryCode}/check
          name: buildability
          description: "Validate a vehicle configuration."
          operations:
            - method: POST
              name: check-buildability
              description: "Check if configuration is buildable."
              call: "volkswagen-okapi.check-buildability"
              with:
                countryCode: "rest.countryCode"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/configuration/{countryCode}/order
          name: order
          description: "Get order data for configuration."
          operations:
            - method: POST
              name: get-order-information
              description: "Get price and specs for a configuration."
              call: "volkswagen-okapi.get-order-information"
              with:
                countryCode: "rest.countryCode"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/configuration/{countryCode}/wltp
          name: wltp
          description: "WLTP emissions data."
          operations:
            - method: POST
              name: get-wltp-data
              description: "Get WLTP fuel and emissions data."
              call: "volkswagen-okapi.get-wltp-data"
              with:
                countryCode: "rest.countryCode"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/configuration/{countryCode}/images
          name: images
          description: "Vehicle images for configuration."
          operations:
            - method: POST
              name: get-configuration-images
              description: "Get vehicle image URLs."
              call: "volkswagen-okapi.get-configuration-images"
              with:
                countryCode: "rest.countryCode"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: volkswagen-config-mcp
      transport: http
      description: "MCP server for AI-assisted VW vehicle configuration and product lookup."
      tools:
        - name: list-vw-markets
          description: "List all countries where Volkswagen OKAPI vehicle configuration is available."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.list-countries"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-vw-brands
          description: "List VW Group brands (Volkswagen, Audi, SEAT, Skoda, CUPRA, etc.) available in a market."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.list-brands-by-country"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: browse-vehicle-models
          description: "Browse vehicle models for a VW Group brand in a specific market."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.list-models-by-brand"
          with:
            countryCode: "tools.countryCode"
            brandId: "tools.brandId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: explore-vehicle-types
          description: "Explore trim levels and engine variants for a vehicle model."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.list-types-by-model"
          with:
            countryCode: "tools.countryCode"
            modelId: "tools.modelId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-type-options
          description: "Get all configurable options for a vehicle type (colors, wheels, interiors, packages)."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.list-options-by-type"
          with:
            countryCode: "tools.countryCode"
            typeId: "tools.typeId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: validate-car-config
          description: "Check if a combination of selected options forms a buildable vehicle."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.check-buildability"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: fix-car-config
          description: "Fix an invalid configuration by finding the nearest buildable option combination."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.recover-configuration"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-available-config-choices
          description: "Get which options are available, unavailable, or required for the current configuration."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.get-configuration-options"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-car-emissions
          description: "Get WLTP fuel consumption and CO2 emissions data for a vehicle configuration."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.get-wltp-data"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-car-images
          description: "Get image URLs showing the configured vehicle with selected exterior color and options."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.get-configuration-images"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-car-price-and-specs
          description: "Get full pricing, standard equipment list, and technical specifications for a configuration."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "volkswagen-okapi.get-order-information"
          with:
            countryCode: "tools.countryCode"
          outputParameters:
            - type: object
              mapping: "$."