naftiko: 1.0.0-alpha2

info:
  label: "Volkswagen Vehicle Configuration"
  description: >-
    Self-contained capability for the Volkswagen OKAPI vehicle configurator
    workflow. Browses the VW Group product catalog across global markets,
    configures vehicles with options, validates buildability, and retrieves
    order information, WLTP emissions, and configuration 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-05"

binds:
  - namespace: env
    keys:
      VOLKSWAGEN_OKAPI_TOKEN: VOLKSWAGEN_OKAPI_TOKEN

capability:
  consumes:
    - type: http
      namespace: volkswagen-okapi
      baseUri: https://productdata.volkswagenag.com/v3
      description: "Volkswagen OKAPI product data and configuration API."
      authentication:
        type: bearer
        token: "{{VOLKSWAGEN_OKAPI_TOKEN}}"
      resources:
        - name: countries
          path: /countries
          description: "List supported markets."
          operations:
            - name: list-countries
              method: GET
              description: "List all countries where OKAPI vehicle configuration is available."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: brands
          path: /catalog/{countryCode}/brands
          description: "VW Group brands by market."
          operations:
            - name: list-brands-by-country
              method: GET
              description: "List VW Group brands available in a country."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
                  description: "ISO 3166-2 market code (e.g. DE, GB, US)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: models
          path: /catalog/{countryCode}/brands/{brandId}/models
          description: "Models by brand and market."
          operations:
            - name: list-models-by-brand
              method: GET
              description: "List vehicle models for a brand in a market."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
                - name: brandId
                  in: path
                  type: string
                  required: true
                  description: "Brand UUID."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: types
          path: /catalog/{countryCode}/models/{modelId}/types
          description: "Vehicle types by model."
          operations:
            - name: list-types-by-model
              method: GET
              description: "List vehicle types (trims, engine variants) for a model."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
                - name: modelId
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: options
          path: /catalog/{countryCode}/types/{typeId}/options
          description: "Configurable options for a vehicle type."
          operations:
            - name: list-options-by-type
              method: GET
              description: "List all configurable options for a vehicle type."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
                - name: typeId
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

        - name: buildability
          path: /operation/{countryCode}/check
          description: "Validate a vehicle configuration."
          operations:
            - name: check-buildability
              method: POST
              description: "Check whether a configuration is buildable."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

        - name: recover
          path: /operation/{countryCode}/recover
          description: "Recover a buildable configuration."
          operations:
            - name: recover-configuration
              method: POST
              description: "Return nearest valid configuration for an unbuildable selection."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

        - name: configure
          path: /operation/{countryCode}/configure
          description: "Get available options for current config."
          operations:
            - name: get-configuration-options
              method: POST
              description: "List available, unavailable, and required options."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

        - name: wltp
          path: /operation/{countryCode}/wltp
          description: "WLTP emissions data for a configuration."
          operations:
            - name: get-wltp-data
              method: POST
              description: "Get WLTP fuel consumption and CO2 emissions for a configuration."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

        - name: images
          path: /operation/{countryCode}/images
          description: "Vehicle images for a configuration."
          operations:
            - name: get-configuration-images
              method: POST
              description: "Get image URLs for the configured vehicle."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

        - name: order
          path: /operation/{countryCode}/order
          description: "Order information for a configuration."
          operations:
            - name: get-order-information
              method: POST
              description: "Get pricing, standard equipment, and technical data."
              inputParameters:
                - name: countryCode
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
              body:
                type: json
                data:
                  typeId: "{{tools.typeId}}"
                  selectedOptions: "{{tools.selectedOptions}}"

  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: "$."