Shopify Headless Commerce

naftiko: "1.0.0-alpha1"

info:
  label: "Shopify Headless Commerce"
  description: >-
    Workflow capability for building headless Shopify commerce experiences.
    Combines product discovery, collection browsing, search, cart management,
    and customer account operations into a unified capability for front-end
    developers building custom storefronts with frameworks like Next.js, Nuxt,
    Remix, or Shopify Hydrogen.
  tags:
    - Commerce
    - Ecommerce
    - Headless
    - GraphQL
    - Storefront
    - Cart
    - Checkout
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SHOPIFY_STOREFRONT_ACCESS_TOKEN: SHOPIFY_STOREFRONT_ACCESS_TOKEN
      SHOPIFY_STORE_NAME: SHOPIFY_STORE_NAME

capability:
  consumes:
    - import: shopify-storefront
      location: ./shared/shopify-storefront.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: shopify-headless-commerce-api
      description: "Unified REST API for headless Shopify commerce experiences."
      resources:
        - path: /v1/products
          name: products
          description: Product catalog browsing and search
          operations:
            - method: GET
              name: get-products
              description: Browse all available products
              call: "shopify-storefront.get-products"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/products/{handle}
          name: product-detail
          description: Product detail page data
          operations:
            - method: GET
              name: get-product-by-handle
              description: Get full product details by URL handle
              call: "shopify-storefront.get-product-by-handle"
              with:
                handle: "rest.handle"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/collections
          name: collections
          description: Product collection catalog
          operations:
            - method: GET
              name: get-collections
              description: Browse product collections
              call: "shopify-storefront.get-collections"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/collections/{handle}/products
          name: collection-products
          description: Products within a collection
          operations:
            - method: GET
              name: get-collection-products
              description: List products in a specific collection
              call: "shopify-storefront.get-collection-products"
              with:
                handle: "rest.handle"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/search
          name: search
          description: Product search
          operations:
            - method: GET
              name: search-products
              description: Search products by keyword
              call: "shopify-storefront.search-products"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cart
          name: cart
          description: Cart creation
          operations:
            - method: POST
              name: create-cart
              description: Create a new shopping cart
              call: "shopify-storefront.create-cart"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cart/{id}
          name: cart-detail
          description: Cart retrieval
          operations:
            - method: GET
              name: get-cart
              description: Get cart contents and cost summary
              call: "shopify-storefront.get-cart"
              with:
                cart_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cart/{id}/lines
          name: cart-lines
          description: Cart line item management
          operations:
            - method: POST
              name: add-to-cart
              description: Add items to cart
              call: "shopify-storefront.add-to-cart"
              with:
                cart_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: remove-from-cart
              description: Remove items from cart
              call: "shopify-storefront.remove-from-cart"
              with:
                cart_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/customer
          name: customer
          description: Customer account
          operations:
            - method: GET
              name: get-customer
              description: Get authenticated customer data
              call: "shopify-storefront.get-customer"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: shopify-headless-commerce-mcp
      transport: http
      description: "MCP server for AI-assisted headless Shopify storefront development."
      tools:
        - name: get-products
          description: Browse all products available in the storefront catalog
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-products"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-product-by-handle
          description: Retrieve complete product details including variants and images by URL handle
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-product-by-handle"
          with:
            handle: "tools.handle"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-collections
          description: Browse product collections available in the storefront
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-collections"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-collection-products
          description: List all products within a specific collection by handle
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-collection-products"
          with:
            handle: "tools.handle"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-products
          description: Search the product catalog by keyword, title, tag, or type
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.search-products"
          with:
            search_query: "tools.search_query"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-cart
          description: Create a new shopping cart, optionally with initial product variant line items
          hints:
            readOnly: false
            destructive: false
          call: "shopify-storefront.create-cart"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cart
          description: Retrieve a shopping cart with line items and pricing totals
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-cart"
          with:
            cart_id: "tools.cart_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: add-to-cart
          description: Add one or more product variants to an existing cart
          hints:
            readOnly: false
            destructive: false
          call: "shopify-storefront.add-to-cart"
          with:
            cart_id: "tools.cart_id"
            lines: "tools.lines"
          outputParameters:
            - type: object
              mapping: "$."
        - name: remove-from-cart
          description: Remove specific line items from a shopping cart
          hints:
            readOnly: false
            destructive: true
          call: "shopify-storefront.remove-from-cart"
          with:
            cart_id: "tools.cart_id"
            line_ids: "tools.line_ids"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-customer
          description: Retrieve authenticated customer profile and recent order history
          hints:
            readOnly: true
            openWorld: true
          call: "shopify-storefront.get-customer"
          with:
            customer_access_token: "tools.customer_access_token"
          outputParameters:
            - type: object
              mapping: "$."