naftiko: 1.0.0-alpha2
info:
  label: WooCommerce Store Management
  description: Unified store management capability combining the WooCommerce REST API and Store API for complete eCommerce
    operations. Used by store administrators and operations teams to manage products, process orders, manage customers, and
    run sales reports. Combines backend admin operations with frontend storefront browsing.
  tags:
  - eCommerce
  - Operations
  - Orders
  - Products
  - Store Management
  - WooCommerce
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    WOOCOMMERCE_CONSUMER_KEY: WOOCOMMERCE_CONSUMER_KEY
    WOOCOMMERCE_CONSUMER_SECRET: WOOCOMMERCE_CONSUMER_SECRET
capability:
  consumes:
  - type: http
    namespace: woo-rest
    baseUri: https://example.com/wp-json/wc/v3
    description: WooCommerce REST API v3 for complete store management.
    authentication:
      type: basic
      username: '{{WOOCOMMERCE_CONSUMER_KEY}}'
      password: '{{WOOCOMMERCE_CONSUMER_SECRET}}'
    resources:
    - name: products
      path: /products
      description: Manage WooCommerce products.
      operations:
      - name: list-products
        method: GET
        description: List all products with optional filtering and pagination.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: per_page
          in: query
          type: integer
          required: false
          description: Items per page.
        - name: status
          in: query
          type: string
          required: false
          description: Filter by product status.
        - name: category
          in: query
          type: string
          required: false
          description: Filter by product category ID.
        - name: search
          in: query
          type: string
          required: false
          description: Search term.
        outputRawFormat: json
        outputParameters:
        - name: products
          type: array
          value: $.
      - name: create-product
        method: POST
        description: Create a new WooCommerce product.
        inputParameters: []
        body:
          type: json
          data:
            name: '{{tools.name}}'
            type: '{{tools.type}}'
            status: '{{tools.status}}'
            regular_price: '{{tools.regular_price}}'
        outputRawFormat: json
        outputParameters:
        - name: product
          type: object
          value: $.
      - name: get-product
        method: GET
        description: Get a single product by ID.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Product ID.
        outputRawFormat: json
        outputParameters:
        - name: product
          type: object
          value: $.
      - name: update-product
        method: PUT
        description: Update an existing product.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Product ID.
        body:
          type: json
          data:
            regular_price: '{{tools.regular_price}}'
            status: '{{tools.status}}'
        outputRawFormat: json
        outputParameters:
        - name: product
          type: object
          value: $.
      - name: delete-product
        method: DELETE
        description: Delete a product.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Product ID.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orders
      path: /orders
      description: Manage WooCommerce orders.
      operations:
      - name: list-orders
        method: GET
        description: List all orders with optional filtering.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: per_page
          in: query
          type: integer
          required: false
          description: Items per page.
        - name: status
          in: query
          type: string
          required: false
          description: Filter by order status.
        - name: customer
          in: query
          type: integer
          required: false
          description: Filter by customer ID.
        - name: after
          in: query
          type: string
          required: false
          description: Filter orders after date (ISO 8601).
        outputRawFormat: json
        outputParameters:
        - name: orders
          type: array
          value: $.
      - name: create-order
        method: POST
        description: Create a new order.
        inputParameters: []
        body:
          type: json
          data:
            payment_method: '{{tools.payment_method}}'
            billing: '{{tools.billing}}'
            line_items: '{{tools.line_items}}'
        outputRawFormat: json
        outputParameters:
        - name: order
          type: object
          value: $.
      - name: get-order
        method: GET
        description: Get a single order by ID.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Order ID.
        outputRawFormat: json
        outputParameters:
        - name: order
          type: object
          value: $.
      - name: update-order
        method: PUT
        description: Update an order status or data.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Order ID.
        body:
          type: json
          data:
            status: '{{tools.status}}'
        outputRawFormat: json
        outputParameters:
        - name: order
          type: object
          value: $.
    - name: customers
      path: /customers
      description: Manage WooCommerce customers.
      operations:
      - name: list-customers
        method: GET
        description: List all customers.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: per_page
          in: query
          type: integer
          required: false
          description: Items per page.
        - name: search
          in: query
          type: string
          required: false
          description: Search by email or name.
        outputRawFormat: json
        outputParameters:
        - name: customers
          type: array
          value: $.
      - name: get-customer
        method: GET
        description: Get a single customer by ID.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Customer ID.
        outputRawFormat: json
        outputParameters:
        - name: customer
          type: object
          value: $.
    - name: coupons
      path: /coupons
      description: Manage WooCommerce discount coupons.
      operations:
      - name: list-coupons
        method: GET
        description: List all coupons.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: search
          in: query
          type: string
          required: false
          description: Search by coupon code.
        outputRawFormat: json
        outputParameters:
        - name: coupons
          type: array
          value: $.
      - name: create-coupon
        method: POST
        description: Create a new discount coupon.
        inputParameters: []
        body:
          type: json
          data:
            code: '{{tools.code}}'
            discount_type: '{{tools.discount_type}}'
            amount: '{{tools.amount}}'
        outputRawFormat: json
        outputParameters:
        - name: coupon
          type: object
          value: $.
    - name: reports
      path: /reports/sales
      description: Retrieve WooCommerce sales reports.
      operations:
      - name: get-sales-report
        method: GET
        description: Get sales report summary for a date range.
        inputParameters:
        - name: period
          in: query
          type: string
          required: false
          description: 'Report period: week, month, last_month, year.'
        - name: date_min
          in: query
          type: string
          required: false
          description: Start date (ISO 8601).
        - name: date_max
          in: query
          type: string
          required: false
          description: End date (ISO 8601).
        outputRawFormat: json
        outputParameters:
        - name: report
          type: object
          value: $.
  - type: http
    namespace: woo-store
    baseUri: https://example.com/wp-json/wc/store/v1
    description: WooCommerce Store API v1 for public storefront operations.
    resources:
    - name: products
      path: /products
      description: Browse the public product catalog.
      operations:
      - name: list-store-products
        method: GET
        description: List published products available for purchase.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        - name: per_page
          in: query
          type: integer
          required: false
          description: Items per page.
        - name: search
          in: query
          type: string
          required: false
          description: Search term.
        - name: category
          in: query
          type: string
          required: false
          description: Filter by category slug.
        - name: on_sale
          in: query
          type: boolean
          required: false
          description: Return only on-sale products.
        outputRawFormat: json
        outputParameters:
        - name: products
          type: array
          value: $.
      - name: get-store-product
        method: GET
        description: Get a single product by ID.
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: Product ID.
        outputRawFormat: json
        outputParameters:
        - name: product
          type: object
          value: $.
    - name: cart
      path: /cart
      description: Manage the current shopper's cart.
      operations:
      - name: get-cart
        method: GET
        description: Get the current shopper's cart contents.
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: cart
          type: object
          value: $.
      - name: add-to-cart
        method: POST
        description: Add an item to the cart.
        inputParameters: []
        body:
          type: json
          data:
            id: '{{tools.product_id}}'
            quantity: '{{tools.quantity}}'
        outputRawFormat: json
        outputParameters:
        - name: cart_item
          type: object
          value: $.
      - name: remove-cart-item
        method: DELETE
        description: Remove an item from the cart.
        inputParameters:
        - name: key
          in: path
          type: string
          required: true
          description: Cart item key.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: checkout
      path: /checkout
      description: Submit the checkout and place an order.
      operations:
      - name: submit-checkout
        method: POST
        description: Submit checkout details and place an order.
        inputParameters: []
        body:
          type: json
          data:
            payment_method: '{{tools.payment_method}}'
            billing_address: '{{tools.billing_address}}'
            shipping_address: '{{tools.shipping_address}}'
        outputRawFormat: json
        outputParameters:
        - name: order
          type: object
          value: $.
    - name: categories
      path: /products/categories
      description: Browse product categories.
      operations:
      - name: list-categories
        method: GET
        description: List all product categories.
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number.
        outputRawFormat: json
        outputParameters:
        - name: categories
          type: array
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: woo-management-api
    description: Unified REST API for complete WooCommerce store management.
    resources:
    - path: /v1/products
      name: products
      description: Full product catalog management.
      operations:
      - method: GET
        name: list-products
        description: List all products with filtering.
        call: woo-rest.list-products
        with:
          page: rest.page
          per_page: rest.per_page
          status: rest.status
          search: rest.search
        outputParameters:
        - type: array
          mapping: $.
      - method: POST
        name: create-product
        description: Create a new product.
        call: woo-rest.create-product
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orders
      name: orders
      description: Order lifecycle management.
      operations:
      - method: GET
        name: list-orders
        description: List orders with filtering by status and customer.
        call: woo-rest.list-orders
        with:
          page: rest.page
          status: rest.status
          customer: rest.customer
        outputParameters:
        - type: array
          mapping: $.
      - method: POST
        name: create-order
        description: Create a new order.
        call: woo-rest.create-order
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/customers
      name: customers
      description: Customer management.
      operations:
      - method: GET
        name: list-customers
        description: List customers.
        call: woo-rest.list-customers
        with:
          search: rest.search
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/storefront/products
      name: storefront-products
      description: Public storefront product browsing.
      operations:
      - method: GET
        name: browse-products
        description: Browse storefront products.
        call: woo-store.list-store-products
        with:
          search: rest.search
          category: rest.category
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/reports/sales
      name: reports
      description: Sales reports and analytics.
      operations:
      - method: GET
        name: get-sales-report
        description: Get sales report for a period.
        call: woo-rest.get-sales-report
        with:
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: woo-management-mcp
    transport: http
    description: MCP server for AI-assisted WooCommerce store management.
    tools:
    - name: list-products
      description: List WooCommerce products with optional filtering by status, category, or keyword.
      hints:
        readOnly: true
      call: woo-rest.list-products
      with:
        page: tools.page
        per_page: tools.per_page
        status: tools.status
        search: tools.search
      outputParameters:
      - type: array
        mapping: $.
    - name: get-product
      description: Get detailed information about a specific WooCommerce product.
      hints:
        readOnly: true
      call: woo-rest.get-product
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: create-product
      description: Create a new WooCommerce product with pricing and inventory details.
      hints:
        readOnly: false
      call: woo-rest.create-product
      outputParameters:
      - type: object
        mapping: $.
    - name: update-product
      description: Update a WooCommerce product's details, pricing, or status.
      hints:
        readOnly: false
        idempotent: true
      call: woo-rest.update-product
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-orders
      description: List WooCommerce orders filtered by status, customer, or date range.
      hints:
        readOnly: true
      call: woo-rest.list-orders
      with:
        page: tools.page
        per_page: tools.per_page
        status: tools.status
        customer: tools.customer
      outputParameters:
      - type: array
        mapping: $.
    - name: get-order
      description: Get complete details of a specific WooCommerce order including items and billing.
      hints:
        readOnly: true
      call: woo-rest.get-order
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: update-order-status
      description: Update the status of a WooCommerce order (e.g., processing, completed, refunded).
      hints:
        readOnly: false
        idempotent: true
      call: woo-rest.update-order
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-customers
      description: List WooCommerce customers, optionally searching by name or email.
      hints:
        readOnly: true
      call: woo-rest.list-customers
      with:
        search: tools.search
        page: tools.page
      outputParameters:
      - type: array
        mapping: $.
    - name: get-customer
      description: Get a specific customer's profile and order history.
      hints:
        readOnly: true
      call: woo-rest.get-customer
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-sales-report
      description: Get WooCommerce sales analytics for a time period.
      hints:
        readOnly: true
      call: woo-rest.get-sales-report
      with:
        period: tools.period
        date_min: tools.date_min
        date_max: tools.date_max
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-storefront-products
      description: Browse the public WooCommerce storefront product catalog.
      hints:
        readOnly: true
      call: woo-store.list-store-products
      with:
        search: tools.search
        category: tools.category
        on_sale: tools.on_sale
      outputParameters:
      - type: array
        mapping: $.
    - name: list-coupons
      description: List WooCommerce discount coupons.
      hints:
        readOnly: true
      call: woo-rest.list-coupons
      with:
        search: tools.search
      outputParameters:
      - type: array
        mapping: $.