Vehicle Data Workflow

naftiko: 1.0.0-alpha2
info:
  label: Vehicle Data Workflow
  description: Customer workflow capability for automotive vehicle data research and shopping. Combines Edmunds vehicle catalog
    (makes, models, styles), TMV pricing, media assets, and dealer inventory into a unified interface for car shoppers, dealer
    platforms, and automotive application developers.
  tags:
  - Automotive
  - Cars
  - Edmunds
  - Inventory
  - Pricing
  - Vehicles
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    EDMUNDS_API_KEY: EDMUNDS_API_KEY
capability:
  consumes:
  - type: http
    namespace: vehicle-api
    baseUri: https://api.edmunds.com/api
    description: Edmunds Vehicle API v2
    authentication:
      type: apikey
      key: api_key
      value: '{{env.EDMUNDS_API_KEY}}'
      placement: query
    resources:
    - name: makes
      path: /vehicle/v2/makes
      description: List all vehicle makes with optional year and state filtering
      operations:
      - name: list-makes
        method: GET
        description: Return all vehicle makes filtered by state and year
        inputParameters:
        - name: state
          in: query
          type: string
          required: false
          description: new, used, or future
        - name: year
          in: query
          type: integer
          required: false
          description: 4-digit model year
        - name: view
          in: query
          type: string
          required: false
          description: basic or full
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: models
      path: /vehicle/v2/makes/{makeNiceName}/models
      description: List vehicle models for a given make
      operations:
      - name: list-models
        method: GET
        description: Return all models for a vehicle make
        inputParameters:
        - name: makeNiceName
          in: path
          type: string
          required: true
          description: URL-friendly make name (e.g. toyota)
        - name: state
          in: query
          type: string
          required: false
          description: new, used, or future
        - name: year
          in: query
          type: integer
          required: false
          description: 4-digit model year
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: model-years
      path: /vehicle/v2/makes/{makeNiceName}/models/{modelNiceName}/years
      description: List available model years and styles for a make/model
      operations:
      - name: list-model-years
        method: GET
        description: Return all model years and trims for a make and model
        inputParameters:
        - name: makeNiceName
          in: path
          type: string
          required: true
          description: URL-friendly make name
        - name: modelNiceName
          in: path
          type: string
          required: true
          description: URL-friendly model name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: style
      path: /vehicle/v2/styles/{styleId}
      description: Get complete details for a vehicle style (trim)
      operations:
      - name: get-style
        method: GET
        description: Return complete vehicle style data including specs and pricing
        inputParameters:
        - name: styleId
          in: path
          type: integer
          required: true
          description: Edmunds style ID
        - name: view
          in: query
          type: string
          required: false
          description: basic or full
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tmv-price
      path: /vehicle/v2/price/tmv/simple
      description: Get True Market Value pricing for a vehicle style
      operations:
      - name: get-tmv-price
        method: GET
        description: Return TMV pricing for a vehicle style by zip code
        inputParameters:
        - name: styleId
          in: query
          type: integer
          required: true
          description: Edmunds style ID
        - name: zip
          in: query
          type: string
          required: true
          description: 5-digit US ZIP code
        - name: state
          in: query
          type: string
          required: false
          description: new or used
        - name: mileage
          in: query
          type: integer
          required: false
          description: Mileage for used vehicle pricing
        - name: condition
          in: query
          type: string
          required: false
          description: Outstanding, Clean, Average, or Rough
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: photos
      path: /vehicle/v2/media/{styleId}/photos
      description: Get vehicle photos for a style
      operations:
      - name: get-style-photos
        method: GET
        description: Return photo assets for a vehicle style in multiple sizes
        inputParameters:
        - name: styleId
          in: path
          type: integer
          required: true
          description: Edmunds style ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: inventory
      path: /vehicle/v2/inventory
      description: Search dealer inventory by make, model, and location
      operations:
      - name: search-inventory
        method: GET
        description: Search dealer inventory with make, model, year, and zip code filters
        inputParameters:
        - name: make
          in: query
          type: string
          required: true
          description: Make nice name (e.g. toyota)
        - name: model
          in: query
          type: string
          required: true
          description: Model nice name (e.g. camry)
        - name: year
          in: query
          type: integer
          required: false
          description: Model year
        - name: zip
          in: query
          type: string
          required: true
          description: 5-digit ZIP code
        - name: radius
          in: query
          type: integer
          required: false
          description: Search radius in miles
        - name: pageSize
          in: query
          type: integer
          required: false
          description: Results per page
        - name: pageNum
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: vehicle-data-api
    description: Unified REST API for vehicle data research and automotive shopping workflows.
    resources:
    - path: /v1/makes
      name: makes
      description: List vehicle makes
      operations:
      - method: GET
        name: list-makes
        description: List all vehicle makes with optional year and availability filtering
        call: vehicle-api.list-makes
        with:
          state: rest.state
          year: rest.year
          view: rest.view
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/makes/{makeNiceName}/models
      name: models
      description: List models for a vehicle make
      operations:
      - method: GET
        name: list-models
        description: List all models for a given vehicle make
        call: vehicle-api.list-models
        with:
          makeNiceName: rest.makeNiceName
          state: rest.state
          year: rest.year
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/makes/{makeNiceName}/models/{modelNiceName}/years
      name: model-years
      description: List model years and trim styles
      operations:
      - method: GET
        name: list-model-years
        description: List available years and trim styles for a make/model
        call: vehicle-api.list-model-years
        with:
          makeNiceName: rest.makeNiceName
          modelNiceName: rest.modelNiceName
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/styles/{styleId}
      name: style
      description: Get vehicle style details
      operations:
      - method: GET
        name: get-style
        description: Get complete specs, options, and pricing for a vehicle style
        call: vehicle-api.get-style
        with:
          styleId: rest.styleId
          view: rest.view
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pricing/tmv
      name: tmv-pricing
      description: Get True Market Value pricing
      operations:
      - method: GET
        name: get-tmv-price
        description: Get Edmunds TMV price for a vehicle style by zip code
        call: vehicle-api.get-tmv-price
        with:
          styleId: rest.styleId
          zip: rest.zip
          state: rest.state
          mileage: rest.mileage
          condition: rest.condition
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/styles/{styleId}/photos
      name: photos
      description: Get vehicle photos
      operations:
      - method: GET
        name: get-style-photos
        description: Get photo assets for a vehicle style
        call: vehicle-api.get-style-photos
        with:
          styleId: rest.styleId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/inventory
      name: inventory
      description: Search dealer inventory
      operations:
      - method: GET
        name: search-inventory
        description: Search dealer inventory by make, model, and location
        call: vehicle-api.search-inventory
        with:
          make: rest.make
          model: rest.model
          year: rest.year
          zip: rest.zip
          radius: rest.radius
          pageSize: rest.pageSize
          pageNum: rest.pageNum
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: vehicle-data-mcp
    transport: http
    description: MCP server for AI-assisted automotive vehicle research and shopping.
    tools:
    - name: list-makes
      description: List all vehicle makes available in the Edmunds catalog
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-api.list-makes
      with:
        state: tools.state
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: list-models
      description: List all models for a specific vehicle make
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-api.list-models
      with:
        makeNiceName: tools.makeNiceName
        state: tools.state
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: list-model-years
      description: List available model years and trim styles for a make and model
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-api.list-model-years
      with:
        makeNiceName: tools.makeNiceName
        modelNiceName: tools.modelNiceName
      outputParameters:
      - type: object
        mapping: $.
    - name: get-style
      description: Get complete vehicle style details including specs, options, and pricing
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-api.get-style
      with:
        styleId: tools.styleId
        view: tools.view
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tmv-price
      description: Get Edmunds True Market Value price for a vehicle style at a given zip code
      hints:
        readOnly: true
        openWorld: true
      call: vehicle-api.get-tmv-price
      with:
        styleId: tools.styleId
        zip: tools.zip
        state: tools.state
        mileage: tools.mileage
        condition: tools.condition
      outputParameters:
      - type: object
        mapping: $.
    - name: get-style-photos
      description: Get photo assets for a vehicle style in multiple sizes
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-api.get-style-photos
      with:
        styleId: tools.styleId
      outputParameters:
      - type: object
        mapping: $.
    - name: search-inventory
      description: Search dealer inventory near a zip code for a specific make, model, and year
      hints:
        readOnly: true
        openWorld: true
      call: vehicle-api.search-inventory
      with:
        make: tools.make
        model: tools.model
        year: tools.year
        zip: tools.zip
        radius: tools.radius
        pageSize: tools.pageSize
      outputParameters:
      - type: object
        mapping: $.