naftiko: 1.0.0-alpha2
info:
  label: Vehicle Maintenance Workflow
  description: Customer workflow capability for vehicle maintenance management. Combines VIN decoding, OEM maintenance schedule
    retrieval, service item lookup, NHTSA recall checks, and TSB lookups into a unified interface for fleet operators, repair
    shops, and consumer maintenance reminder applications.
  tags:
  - Automotive
  - Fleet Management
  - Maintenance
  - Recalls
  - Vehicles
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VEHICLE_DATABASES_API_KEY: VEHICLE_DATABASES_API_KEY
capability:
  consumes:
  - type: http
    namespace: vehicle-databases
    baseUri: https://api.vehicledatabases.com/v1
    description: Vehicle Databases Maintenance API v1
    authentication:
      type: apikey
      key: X-API-Key
      value: '{{env.VEHICLE_DATABASES_API_KEY}}'
      placement: header
    resources:
    - name: vehicle-lookup
      path: /vehicle
      description: Look up vehicles by make, model, and year
      operations:
      - name: lookup-vehicle
        method: GET
        description: Find vehicles matching make, model, and year with engine options
        inputParameters:
        - name: make
          in: query
          type: string
          required: true
          description: Vehicle make
        - name: model
          in: query
          type: string
          required: true
          description: Vehicle model
        - name: year
          in: query
          type: integer
          required: true
          description: 4-digit model year
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vin-decode
      path: /vin/{vin}
      description: Decode a VIN to vehicle details
      operations:
      - name: decode-vin
        method: GET
        description: Decode a 17-character VIN to make, model, year, engine, and trim
        inputParameters:
        - name: vin
          in: path
          type: string
          required: true
          description: 17-character Vehicle Identification Number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: maintenance-schedule
      path: /maintenance/{vehicleId}
      description: Get OEM maintenance schedule for a vehicle
      operations:
      - name: get-maintenance-schedule
        method: GET
        description: Return complete OEM maintenance schedule with all service intervals
        inputParameters:
        - name: vehicleId
          in: path
          type: string
          required: true
          description: Vehicle identifier from lookup or VIN decode
        - name: mileage
          in: query
          type: integer
          required: false
          description: Current mileage to filter upcoming services
        - name: includeItems
          in: query
          type: boolean
          required: false
          description: Include service items in response
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: service-items
      path: /services/{vehicleId}
      description: Get service items for a vehicle at a specific mileage
      operations:
      - name: list-service-items
        method: GET
        description: Return service items with fluid specs and parts for a mileage interval
        inputParameters:
        - name: vehicleId
          in: path
          type: string
          required: true
          description: Vehicle identifier
        - name: mileage
          in: query
          type: integer
          required: true
          description: Service interval mileage
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: recalls
      path: /recalls/{vehicleId}
      description: Get NHTSA recall data for a vehicle
      operations:
      - name: get-recalls
        method: GET
        description: Return NHTSA safety recalls with component, risk, and remedy information
        inputParameters:
        - name: vehicleId
          in: path
          type: string
          required: true
          description: Vehicle identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tsbs
      path: /tsb/{vehicleId}
      description: Get technical service bulletins for a vehicle
      operations:
      - name: get-tsbs
        method: GET
        description: Return OEM TSBs with symptoms, diagnosis, and remedy procedures
        inputParameters:
        - name: vehicleId
          in: path
          type: string
          required: true
          description: Vehicle identifier
        - name: category
          in: query
          type: string
          required: false
          description: TSB category filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: vehicle-maintenance-api
    description: Unified REST API for vehicle maintenance management workflows.
    resources:
    - path: /v1/vehicles
      name: vehicles
      description: Look up vehicles by make, model, and year
      operations:
      - method: GET
        name: lookup-vehicle
        description: Find vehicles with engine options by make, model, and year
        call: vehicle-databases.lookup-vehicle
        with:
          make: rest.make
          model: rest.model
          year: rest.year
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/vehicles/vin/{vin}
      name: vin-decode
      description: Decode a VIN to vehicle details
      operations:
      - method: GET
        name: decode-vin
        description: Decode a 17-character VIN to full vehicle specification
        call: vehicle-databases.decode-vin
        with:
          vin: rest.vin
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/maintenance/{vehicleId}
      name: maintenance
      description: Get OEM maintenance schedule
      operations:
      - method: GET
        name: get-maintenance-schedule
        description: Get complete OEM maintenance schedule with service intervals
        call: vehicle-databases.get-maintenance-schedule
        with:
          vehicleId: rest.vehicleId
          mileage: rest.mileage
          includeItems: rest.includeItems
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/services/{vehicleId}
      name: services
      description: Get service items for a maintenance interval
      operations:
      - method: GET
        name: list-service-items
        description: List service items with fluid specs for a specific mileage
        call: vehicle-databases.list-service-items
        with:
          vehicleId: rest.vehicleId
          mileage: rest.mileage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/recalls/{vehicleId}
      name: recalls
      description: Check NHTSA safety recalls
      operations:
      - method: GET
        name: get-recalls
        description: Get NHTSA recall information for a vehicle
        call: vehicle-databases.get-recalls
        with:
          vehicleId: rest.vehicleId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tsb/{vehicleId}
      name: tsbs
      description: Get technical service bulletins
      operations:
      - method: GET
        name: get-tsbs
        description: Get OEM technical service bulletins for a vehicle
        call: vehicle-databases.get-tsbs
        with:
          vehicleId: rest.vehicleId
          category: rest.category
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: vehicle-maintenance-mcp
    transport: http
    description: MCP server for AI-assisted vehicle maintenance management.
    tools:
    - name: lookup-vehicle
      description: Look up vehicles by make, model, and year to get vehicle identifiers
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.lookup-vehicle
      with:
        make: tools.make
        model: tools.model
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: decode-vin
      description: Decode a 17-character VIN to identify make, model, year, engine, and trim
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.decode-vin
      with:
        vin: tools.vin
      outputParameters:
      - type: object
        mapping: $.
    - name: get-maintenance-schedule
      description: Get the complete OEM maintenance schedule for a vehicle, optionally filtered by current mileage
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.get-maintenance-schedule
      with:
        vehicleId: tools.vehicleId
        mileage: tools.mileage
        includeItems: tools.includeItems
      outputParameters:
      - type: object
        mapping: $.
    - name: list-service-items
      description: Get service items, fluid specifications, and part numbers for a vehicle at a specific mileage interval
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.list-service-items
      with:
        vehicleId: tools.vehicleId
        mileage: tools.mileage
      outputParameters:
      - type: object
        mapping: $.
    - name: get-recalls
      description: Check for NHTSA safety recalls affecting a specific vehicle
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.get-recalls
      with:
        vehicleId: tools.vehicleId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-tsbs
      description: Get OEM technical service bulletins (TSBs) for a vehicle, optionally filtered by category
      hints:
        readOnly: true
        openWorld: false
      call: vehicle-databases.get-tsbs
      with:
        vehicleId: tools.vehicleId
        category: tools.category
      outputParameters:
      - type: object
        mapping: $.