Rutter Commerce Operations

naftiko: "1.0.0-alpha1"

info:
  label: "Rutter Commerce Operations"
  description: >-
    Unified workflow for managing commerce operations across platforms like Shopify,
    WooCommerce, Amazon, BigCommerce, and Magento. Enables operations teams to
    read and manage orders, products, customers, and fulfillments through a single
    interface regardless of the underlying commerce platform.
  tags:
    - B2B
    - Commerce
    - E-Commerce
    - Orders
    - Products
    - Unified API
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      RUTTER_CLIENT_ID: RUTTER_CLIENT_ID
      RUTTER_CLIENT_SECRET: RUTTER_CLIENT_SECRET

capability:
  consumes:
    - import: rutter
      location: ./shared/unified-api.yaml

  exposes:
    - type: rest
      port: 8081
      namespace: rutter-commerce-ops-api
      description: "Unified REST API for commerce operations across e-commerce platforms."
      resources:
        - path: /v1/orders
          name: orders
          description: "Commerce orders"
          operations:
            - method: GET
              name: list-orders
              description: "List orders from connected commerce platform"
              call: "rutter.list-orders"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                cursor: "rest.query.cursor"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-order
              description: "Create a new order in connected commerce platform"
              call: "rutter.create-order"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders/{orderId}
          name: order
          description: "Single order"
          operations:
            - method: GET
              name: get-order
              description: "Get a specific order by ID"
              call: "rutter.get-order"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                orderId: "rest.path.orderId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders/{orderId}/fulfillments
          name: fulfillments
          description: "Order fulfillments"
          operations:
            - method: POST
              name: fulfill-order
              description: "Mark an order as fulfilled"
              call: "rutter.fulfill-order"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                orderId: "rest.path.orderId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/products
          name: products
          description: "Product catalog"
          operations:
            - method: GET
              name: list-products
              description: "List products from connected commerce platform"
              call: "rutter.list-products"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-product
              description: "Create a new product in connected commerce platform"
              call: "rutter.create-product"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/products/{productId}
          name: product
          description: "Single product"
          operations:
            - method: GET
              name: get-product
              description: "Get a specific product by ID"
              call: "rutter.get-product"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                productId: "rest.path.productId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-product
              description: "Update a product in connected commerce platform"
              call: "rutter.update-product"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                productId: "rest.path.productId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/customers
          name: customers
          description: "Customer data"
          operations:
            - method: GET
              name: list-customers
              description: "List customers from connected platform"
              call: "rutter.list-customers"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/customers/{customerId}
          name: customer
          description: "Single customer"
          operations:
            - method: GET
              name: get-customer
              description: "Get a specific customer by ID"
              call: "rutter.get-customer"
              with:
                X-Rutter-Version: "rest.header.x-rutter-version"
                access_token: "rest.query.access_token"
                customerId: "rest.path.customerId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9091
      namespace: rutter-commerce-ops-mcp
      transport: http
      description: "MCP server for AI-assisted commerce operations across e-commerce platforms."
      tools:
        - name: list-orders
          description: "List orders from connected commerce platform (Shopify, WooCommerce, Amazon)"
          hints:
            readOnly: true
            openWorld: true
          call: "rutter.list-orders"
          with:
            access_token: "tools.access_token"
            cursor: "tools.cursor"
            updated_at_min: "tools.updated_at_min"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-order
          description: "Get a specific order by ID from connected commerce platform"
          hints:
            readOnly: true
            openWorld: false
          call: "rutter.get-order"
          with:
            access_token: "tools.access_token"
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-order
          description: "Create a new order in the connected commerce platform"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "rutter.create-order"
          with:
            access_token: "tools.access_token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: fulfill-order
          description: "Mark an order as fulfilled with tracking information"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "rutter.fulfill-order"
          with:
            access_token: "tools.access_token"
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-products
          description: "List products from connected commerce platform"
          hints:
            readOnly: true
            openWorld: true
          call: "rutter.list-products"
          with:
            access_token: "tools.access_token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-product
          description: "Get a specific product by ID from connected commerce platform"
          hints:
            readOnly: true
            openWorld: false
          call: "rutter.get-product"
          with:
            access_token: "tools.access_token"
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-product
          description: "Create a new product in the connected commerce platform"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "rutter.create-product"
          with:
            access_token: "tools.access_token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-product
          description: "Update an existing product in the connected commerce platform"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "rutter.update-product"
          with:
            access_token: "tools.access_token"
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-customers
          description: "List customers from connected commerce or accounting platform"
          hints:
            readOnly: true
            openWorld: true
          call: "rutter.list-customers"
          with:
            access_token: "tools.access_token"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-customer
          description: "Get a specific customer by ID from connected platform"
          hints:
            readOnly: true
            openWorld: false
          call: "rutter.get-customer"
          with:
            access_token: "tools.access_token"
            customerId: "tools.customerId"
          outputParameters:
            - type: object
              mapping: "$."