naftiko: 1.0.0-alpha2
info:
  label: Vizion Shipment Visibility Workflow
  description: Workflow capability for supply chain and logistics teams needing end-to-end container shipment visibility.
    Combines the Vizion Container Tracking API to manage subscriptions, monitor milestone events, and surface estimated and
    actual arrival/departure times. Supports both real-time webhook and polling-based integration patterns.
  tags:
  - Vizion
  - Container Tracking
  - Logistics
  - Ocean Freight
  - Shipping
  - Supply Chain
  - Webhooks
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VIZION_API_KEY: VIZION_API_KEY
capability:
  consumes:
  - type: http
    namespace: vizion
    baseUri: https://prod.vizionapi.com
    description: Vizion Container Tracking REST API.
    authentication:
      type: apikey
      key: X-API-Key
      value: '{{VIZION_API_KEY}}'
      placement: header
    resources:
    - name: references
      path: /references
      description: Container tracking subscription management.
      operations:
      - name: list-references
        method: GET
        description: List all active container tracking references.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-reference
        method: POST
        description: Subscribe to tracking updates for a container.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            container_id: '{{tools.container_id}}'
            carrier_code: '{{tools.carrier_code}}'
            callback_url: '{{tools.callback_url}}'
    - name: reference-detail
      path: /references/{reference_id}
      description: Individual container tracking reference.
      operations:
      - name: get-reference
        method: GET
        description: Get status and metadata for a specific reference.
        inputParameters:
        - name: reference_id
          in: path
          type: string
          required: true
          description: Reference ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-reference
        method: DELETE
        description: Cancel tracking and delete a container reference.
        inputParameters:
        - name: reference_id
          in: path
          type: string
          required: true
          description: Reference ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: reference-updates
      path: /references/{reference_id}/updates
      description: Tracking event updates for a reference (polling).
      operations:
      - name: list-reference-updates
        method: GET
        description: List all tracking milestone events for a container reference.
        inputParameters:
        - name: reference_id
          in: path
          type: string
          required: true
          description: Reference ID
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: per_page
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: vizion-shipment-api
    description: Unified REST API for container shipment visibility workflows.
    resources:
    - path: /v1/references
      name: references
      description: Container tracking subscriptions.
      operations:
      - method: GET
        name: list-references
        description: List all active container tracking references.
        call: vizion.list-references
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-reference
        description: Subscribe to tracking for a container.
        call: vizion.create-reference
        with:
          container_id: rest.container_id
          carrier_code: rest.carrier_code
          callback_url: rest.callback_url
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/references/{reference_id}
      name: reference-detail
      description: Individual container reference details.
      operations:
      - method: GET
        name: get-reference
        description: Get reference status and metadata.
        call: vizion.get-reference
        with:
          reference_id: rest.reference_id
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: delete-reference
        description: Cancel tracking and remove reference.
        call: vizion.delete-reference
        with:
          reference_id: rest.reference_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/references/{reference_id}/updates
      name: tracking-events
      description: Container tracking milestone events.
      operations:
      - method: GET
        name: list-tracking-events
        description: Retrieve all tracking events for a container.
        call: vizion.list-reference-updates
        with:
          reference_id: rest.reference_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: vizion-shipment-mcp
    transport: http
    description: MCP server for AI-assisted container shipment visibility and logistics workflows.
    tools:
    - name: list-container-subscriptions
      description: List all active container tracking subscriptions in the account.
      hints:
        readOnly: true
        idempotent: true
      call: vizion.list-references
      outputParameters:
      - type: object
        mapping: $.
    - name: track-container
      description: Subscribe to real-time tracking for a container. Provide the container ID and carrier SCAC code (e.g. MSCU
        for MSC, MAEU for Maersk). Optionally supply a webhook URL for push updates.
      hints:
        readOnly: false
        idempotent: false
      call: vizion.create-reference
      with:
        container_id: tools.container_id
        carrier_code: tools.carrier_code
        callback_url: tools.callback_url
      outputParameters:
      - type: object
        mapping: $.
    - name: get-container-status
      description: Get the current tracking status for a specific container reference, including whether it is actively receiving
        updates.
      hints:
        readOnly: true
        idempotent: true
      call: vizion.get-reference
      with:
        reference_id: tools.reference_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-shipment-milestones
      description: 'Retrieve all tracking milestone events for a container: loading, departure, transshipment, arrival, customs
        clearance, and delivery events.'
      hints:
        readOnly: true
        idempotent: true
      call: vizion.list-reference-updates
      with:
        reference_id: tools.reference_id
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-container-tracking
      description: Cancel tracking for a container and remove the reference. No further updates will be sent.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: vizion.delete-reference
      with:
        reference_id: tools.reference_id
      outputParameters:
      - type: object
        mapping: $.