Shippo Shipping Fulfillment

naftiko: "1.0.0-alpha1"

info:
  label: "Shippo Shipping Fulfillment"
  description: >-
    Unified shipping fulfillment workflow combining address validation, multi-carrier
    rate shopping, label generation, and package tracking. Designed for ecommerce
    developers and operations teams needing end-to-end shipping automation.
  tags:
    - Shipping
    - Ecommerce
    - Labels
    - Tracking
    - Logistics
    - Fulfillment
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SHIPPO_API_TOKEN: SHIPPO_API_TOKEN

capability:
  consumes:
    - import: shippo
      location: ./shared/shippo.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: shippo-fulfillment-api
      description: "Unified REST API for end-to-end shipping fulfillment with multi-carrier support."
      resources:
        - path: /v1/addresses
          name: addresses
          description: "Manage and validate shipping addresses"
          operations:
            - method: GET
              name: list-addresses
              description: "List all addresses"
              call: "shippo.list-addresses"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-address
              description: "Create a new shipping address"
              call: "shippo.create-address"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/addresses/{id}/validate
          name: address-validation
          description: "Validate a shipping address"
          operations:
            - method: GET
              name: validate-address
              description: "Validate address deliverability"
              call: "shippo.validate-address"
              with:
                AddressId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/shipments
          name: shipments
          description: "Create shipments and retrieve carrier rates"
          operations:
            - method: GET
              name: list-shipments
              description: "List all shipments"
              call: "shippo.list-shipments"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-shipment
              description: "Create a shipment to compare carrier rates"
              call: "shippo.create-shipment"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/shipments/{id}/rates
          name: rates
          description: "Get carrier shipping rates"
          operations:
            - method: GET
              name: get-rates
              description: "Get available rates for a shipment"
              call: "shippo.get-shipment-rates"
              with:
                ShipmentId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/labels
          name: labels
          description: "Purchase and manage shipping labels"
          operations:
            - method: GET
              name: list-labels
              description: "List all purchased labels"
              call: "shippo.list-transactions"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: purchase-label
              description: "Purchase a shipping label"
              call: "shippo.purchase-label"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/tracking/{carrier}/{tracking-number}
          name: tracking
          description: "Track shipments across carriers"
          operations:
            - method: GET
              name: track-shipment
              description: "Get real-time tracking status"
              call: "shippo.get-tracking-status"
              with:
                Carrier: "rest.carrier"
                TrackingNumber: "rest.tracking-number"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/refunds
          name: refunds
          description: "Request label refunds"
          operations:
            - method: POST
              name: request-refund
              description: "Request a label refund"
              call: "shippo.create-refund"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/carriers
          name: carriers
          description: "Manage carrier account connections"
          operations:
            - method: GET
              name: list-carriers
              description: "List connected carrier accounts"
              call: "shippo.list-carrier-accounts"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: shippo-fulfillment-mcp
      transport: http
      description: "MCP server for AI-assisted shipping fulfillment and logistics operations."
      tools:
        - name: validate-shipping-address
          description: "Validate that a shipping address is deliverable by carriers"
          hints:
            readOnly: true
            openWorld: true
          call: "shippo.validate-address"
          with:
            AddressId: "tools.address_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-shipping-address
          description: "Create a new shipping address for use in shipments"
          hints:
            readOnly: false
          call: "shippo.create-address"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-shipment
          description: "Create a new shipment from origin to destination to get available carrier rates"
          hints:
            readOnly: false
          call: "shippo.create-shipment"
          with:
            address_from: "tools.address_from"
            address_to: "tools.address_to"
            parcels: "tools.parcels"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-shipping-rates
          description: "Get available carrier rates for a shipment including price and transit time"
          hints:
            readOnly: true
          call: "shippo.get-shipment-rates"
          with:
            ShipmentId: "tools.shipment_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: purchase-shipping-label
          description: "Purchase a shipping label from a selected carrier rate"
          hints:
            readOnly: false
          call: "shippo.purchase-label"
          with:
            rate_id: "tools.rate_id"
            label_file_type: "tools.label_file_type"
          outputParameters:
            - type: object
              mapping: "$."
        - name: track-package
          description: "Get real-time tracking status for a shipped package"
          hints:
            readOnly: true
            openWorld: true
          call: "shippo.get-tracking-status"
          with:
            Carrier: "tools.carrier_code"
            TrackingNumber: "tools.tracking_number"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-shipments
          description: "List all shipments with optional status filter"
          hints:
            readOnly: true
          call: "shippo.list-shipments"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-purchased-labels
          description: "List all purchased shipping labels with tracking status"
          hints:
            readOnly: true
          call: "shippo.list-transactions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: request-label-refund
          description: "Request a refund for a purchased but unused shipping label"
          hints:
            readOnly: false
            destructive: false
          call: "shippo.create-refund"
          with:
            transaction_id: "tools.transaction_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-carrier-accounts
          description: "List all connected carrier accounts and their status"
          hints:
            readOnly: true
          call: "shippo.list-carrier-accounts"
          outputParameters:
            - type: object
              mapping: "$."