VTEX Store Operations

naftiko: "1.0.0-alpha1"

info:
  label: "VTEX Store Operations"
  description: >-
    Unified workflow capability for VTEX store operators managing day-to-day commerce operations.
    Combines order management, logistics, and catalog capabilities for fulfillment teams,
    merchandising managers, and store operations staff who need to monitor, fulfill,
    and manage the complete order-to-delivery lifecycle.
  tags:
    - Commerce
    - Fulfillment
    - Order Management
    - Operations
    - VTEX
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VTEX_APP_KEY: VTEX_APP_KEY
      VTEX_APP_TOKEN: VTEX_APP_TOKEN

capability:
  consumes:
    - import: vtex-orders
      location: ./shared/orders.yaml
    - import: vtex-logistics
      location: ./shared/logistics.yaml
    - import: vtex-catalog
      location: ./shared/catalog.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: vtex-store-operations-api
      description: "Unified REST API for VTEX store operations covering orders, inventory, and catalog."
      resources:
        - path: /v1/orders
          name: orders
          description: "Order management"
          operations:
            - method: GET
              name: list-orders
              description: "List orders with filtering by status and date"
              call: "vtex-orders.list-orders"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/orders/{orderId}
          name: order
          description: "Single order operations"
          operations:
            - method: GET
              name: get-order
              description: "Get full order details"
              call: "vtex-orders.get-order"
              with:
                orderId: "rest.orderId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/orders/{orderId}/cancel
          name: cancel-order
          description: "Order cancellation"
          operations:
            - method: POST
              name: cancel-order
              description: "Cancel an order"
              call: "vtex-orders.cancel-order"
              with:
                orderId: "rest.orderId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/orders/{orderId}/invoices
          name: order-invoices
          description: "Order invoice management"
          operations:
            - method: POST
              name: send-invoice
              description: "Send invoice for a fulfilled order"
              call: "vtex-orders.send-invoice"
              with:
                orderId: "rest.orderId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/inventory/skus/{skuId}
          name: sku-inventory
          description: "SKU inventory levels"
          operations:
            - method: GET
              name: get-inventory
              description: "Get inventory levels for a SKU"
              call: "vtex-logistics.list-inventory-by-sku"
              with:
                skuId: "rest.skuId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/warehouses
          name: warehouses
          description: "Warehouse management"
          operations:
            - method: GET
              name: list-warehouses
              description: "List all configured warehouses"
              call: "vtex-logistics.list-warehouses"
              outputParameters:
                - type: array
                  mapping: "$."

        - path: /v1/products/{productId}
          name: product
          description: "Product catalog operations"
          operations:
            - method: GET
              name: get-product
              description: "Get product details"
              call: "vtex-catalog.get-product"
              with:
                productId: "rest.productId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/carriers
          name: carriers
          description: "Shipping carrier configuration"
          operations:
            - method: GET
              name: list-carriers
              description: "List available shipping carriers"
              call: "vtex-logistics.list-carriers"
              outputParameters:
                - type: array
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: vtex-store-operations-mcp
      transport: http
      description: "MCP server for AI-assisted VTEX store operations and fulfillment management."
      tools:
        - name: list-orders
          description: "List VTEX orders with optional filtering by status, date range, and other criteria"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-orders.list-orders"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-order
          description: "Get full details of a VTEX order including items, payment, and shipping status"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-orders.get-order"
          with:
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: cancel-order
          description: "Cancel a VTEX order"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "vtex-orders.cancel-order"
          with:
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: send-invoice
          description: "Send invoice notification for a fulfilled VTEX order to trigger shipping"
          hints:
            readOnly: false
            destructive: false
          call: "vtex-orders.send-invoice"
          with:
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-sku-inventory
          description: "Get current inventory levels for a SKU across all warehouses"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-logistics.list-inventory-by-sku"
          with:
            skuId: "tools.skuId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: update-sku-inventory
          description: "Update inventory quantity for a SKU at a specific warehouse"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "vtex-logistics.update-inventory"
          with:
            skuId: "tools.skuId"
            warehouseId: "tools.warehouseId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-warehouses
          description: "List all warehouses configured in the VTEX account"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-logistics.list-warehouses"
          outputParameters:
            - type: array
              mapping: "$."

        - name: get-product
          description: "Get product details from the VTEX catalog"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-catalog.get-product"
          with:
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-carriers
          description: "List all shipping carriers configured in the VTEX account"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-logistics.list-carriers"
          outputParameters:
            - type: array
              mapping: "$."