naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    VTEX_APP_KEY: VTEX_APP_KEY
    VTEX_APP_TOKEN: VTEX_APP_TOKEN
capability:
  consumes:
  - type: http
    namespace: vtex-orders
    baseUri: https://{accountName}.vtexcommercestable.com.br
    description: VTEX Orders API for managing order lifecycle and fulfillment.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{VTEX_APP_KEY}}'
      placement: header
    resources:
    - name: orders
      path: /api/oms/pvt/orders
      description: Order management operations
      operations:
      - name: list-orders
        method: GET
        description: List Orders
        inputParameters:
        - name: f_status
          in: query
          type: string
          required: false
          description: Filter by order status
        - name: orderBy
          in: query
          type: string
          required: false
          description: Order results by field
        - 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: get-order
        method: GET
        description: Get Order by ID
        inputParameters:
        - name: orderId
          in: path
          type: string
          required: true
          description: Order identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cancel-order
        method: POST
        description: Cancel Order
        inputParameters:
        - name: orderId
          in: path
          type: string
          required: true
          description: Order identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: send-invoice
        method: POST
        description: Send Invoice
        inputParameters:
        - name: orderId
          in: path
          type: string
          required: true
          description: Order identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            type: '{{tools.invoiceType}}'
            invoiceNumber: '{{tools.invoiceNumber}}'
            invoiceValue: '{{tools.invoiceValue}}'
  - type: http
    namespace: vtex-logistics
    baseUri: https://{accountName}.vtexcommercestable.com.br
    description: VTEX Logistics API for warehouse, inventory, and shipping management.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{VTEX_APP_KEY}}'
      placement: header
    resources:
    - name: warehouses
      path: /api/logistics/pvt/configuration/warehouses
      description: Warehouse management
      operations:
      - name: list-warehouses
        method: GET
        description: List Warehouses
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
      - name: get-warehouse
        method: GET
        description: Get Warehouse by ID
        inputParameters:
        - name: warehouseId
          in: path
          type: string
          required: true
          description: Warehouse identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: inventory
      path: /api/logistics/pvt/inventory/skus
      description: Inventory management operations
      operations:
      - name: list-inventory-by-sku
        method: GET
        description: List Inventory by SKU
        inputParameters:
        - name: skuId
          in: path
          type: string
          required: true
          description: SKU identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-inventory
        method: PUT
        description: Update Inventory by SKU and Warehouse
        inputParameters:
        - name: skuId
          in: path
          type: string
          required: true
          description: SKU identifier
        - name: warehouseId
          in: path
          type: string
          required: true
          description: Warehouse identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            quantity: '{{tools.quantity}}'
    - name: carriers
      path: /api/logistics/pvt/configuration/carriers
      description: Shipping carrier management
      operations:
      - name: list-carriers
        method: GET
        description: List All Carriers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
  - type: http
    namespace: vtex-catalog
    baseUri: https://{accountName}.vtexcommercestable.com.br
    description: VTEX Catalog API for managing products, SKUs, categories and brands.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{VTEX_APP_KEY}}'
      placement: header
    resources:
    - name: categories
      path: /api/catalog_system/pub/category/tree
      description: Product category tree management
      operations:
      - name: get-category-tree
        method: GET
        description: Get Category Tree
        inputParameters:
        - name: categoryLevels
          in: path
          type: integer
          required: false
          description: Number of levels to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: products
      path: /api/catalog/pvt/product
      description: Product management operations
      operations:
      - name: create-product
        method: POST
        description: Create Product
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            Name: '{{tools.name}}'
            CategoryId: '{{tools.categoryId}}'
            BrandId: '{{tools.brandId}}'
      - name: get-product
        method: GET
        description: Get Product by ID
        inputParameters:
        - name: productId
          in: path
          type: integer
          required: true
          description: Product identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: skus
      path: /api/catalog/pvt/stockkeepingunit
      description: SKU management operations
      operations:
      - name: create-sku
        method: POST
        description: Create SKU
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            ProductId: '{{tools.productId}}'
            Name: '{{tools.name}}'
            IsActive: '{{tools.isActive}}'
      - name: get-sku
        method: GET
        description: Get SKU by ID
        inputParameters:
        - name: skuId
          in: path
          type: integer
          required: true
          description: SKU identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.