naftiko: 1.0.0-alpha2
info:
  label: USPS E-Commerce Shipping
  description: 'Unified workflow capability for e-commerce shipping operations. Combines the USPS Addresses, Domestic Prices,
    and Carrier Pickup APIs to support the complete shipping lifecycle: address validation at checkout, rate shopping, and
    pickup scheduling. Designed for e-commerce developers and shipping software integrators.'
  tags:
  - USPS
  - E-Commerce
  - Shipping
  - Fulfillment
  - Government
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    USPS_BEARER_TOKEN: USPS_BEARER_TOKEN
capability:
  consumes:
  - type: http
    namespace: usps-addresses
    baseUri: https://apis.usps.com
    description: USPS address validation and standardization API.
    authentication:
      type: bearer
      token: '{{USPS_BEARER_TOKEN}}'
    resources:
    - name: address
      path: /addresses/v3/address
      description: Address validation and standardization.
      operations:
      - name: validate-address
        method: GET
        description: Validates and standardizes a US address to USPS specifications.
        inputParameters:
        - name: streetAddress
          in: query
          type: string
          required: true
          description: Primary street address line.
        - name: city
          in: query
          type: string
          required: false
          description: City name.
        - name: state
          in: query
          type: string
          required: false
          description: Two-letter state abbreviation.
        - name: ZIPCode
          in: query
          type: string
          required: false
          description: 5-digit ZIP Code.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: city-state
      path: /addresses/v3/city-state
      description: City and state lookup by ZIP Code.
      operations:
      - name: get-city-state
        method: GET
        description: Returns the city and state for a given ZIP Code.
        inputParameters:
        - name: ZIPCode
          in: query
          type: string
          required: true
          description: 5-digit ZIP Code.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: zipcode
      path: /addresses/v3/zipcode
      description: ZIP Code lookup by address.
      operations:
      - name: get-zip-code
        method: GET
        description: Returns ZIP Code for a given address.
        inputParameters:
        - name: streetAddress
          in: query
          type: string
          required: true
          description: Primary street address.
        - name: city
          in: query
          type: string
          required: true
          description: City name.
        - name: state
          in: query
          type: string
          required: true
          description: Two-letter state abbreviation.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: usps-domestic-prices
    baseUri: https://apis.usps.com
    description: USPS domestic postage pricing API.
    authentication:
      type: bearer
      token: '{{USPS_BEARER_TOKEN}}'
    resources:
    - name: base-rates
      path: /prices/v3/base-rates/search
      description: Base postage rate search.
      operations:
      - name: search-base-rates
        method: POST
        description: Search for base postage rates.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            originZIPCode: '{{tools.originZIPCode}}'
            destinationZIPCode: '{{tools.destinationZIPCode}}'
            weight: '{{tools.weight}}'
            mailClass: '{{tools.mailClass}}'
    - name: extra-service-rates
      path: /prices/v3/extra-service-rates/search
      description: Extra service rates search.
      operations:
      - name: search-extra-service-rates
        method: POST
        description: Search for extra service rates.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            extraServiceCode: '{{tools.extraServiceCode}}'
            mailClass: '{{tools.mailClass}}'
    - name: total-rates
      path: /prices/v3/total-rates/search
      description: Total rate search including all fees.
      operations:
      - name: search-total-rates
        method: POST
        description: Search for total postage rates including all fees.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            originZIPCode: '{{tools.originZIPCode}}'
            destinationZIPCode: '{{tools.destinationZIPCode}}'
            weight: '{{tools.weight}}'
            mailClass: '{{tools.mailClass}}'
  - type: http
    namespace: usps-carrier-pickup
    baseUri: https://apis.usps.com
    description: USPS carrier pickup scheduling API.
    authentication:
      type: bearer
      token: '{{USPS_BEARER_TOKEN}}'
    resources:
    - name: carrier-pickup
      path: /pickup/v3/carrier-pickup
      description: Carrier pickup scheduling and management.
      operations:
      - name: schedule-carrier-pickup
        method: POST
        description: Schedule a free USPS carrier pickup.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            pickupAddress: '{{tools.pickupAddress}}'
            packages: '{{tools.packages}}'
            packageLocation: '{{tools.packageLocation}}'
      - name: get-carrier-pickup
        method: GET
        description: Retrieve an existing carrier pickup by confirmation number.
        inputParameters:
        - name: confirmationNumber
          in: query
          type: string
          required: true
          description: Pickup confirmation number.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-carrier-pickup
        method: PUT
        description: Update an existing carrier pickup request.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            confirmationNumber: '{{tools.confirmationNumber}}'
            packages: '{{tools.packages}}'
      - name: cancel-carrier-pickup
        method: DELETE
        description: Cancel a previously scheduled carrier pickup.
        inputParameters:
        - name: confirmationNumber
          in: query
          type: string
          required: true
          description: Pickup confirmation number to cancel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: usps-ecommerce-shipping-api
    description: Unified REST API for USPS e-commerce shipping workflows.
    resources:
    - path: /v1/addresses/validate
      name: address-validation
      description: Validate and standardize a shipping address.
      operations:
      - method: GET
        name: validate-address
        description: Validate address for shipping.
        call: usps-addresses.validate-address
        with:
          streetAddress: rest.streetAddress
          city: rest.city
          state: rest.state
          ZIPCode: rest.ZIPCode
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/addresses/zipcode
      name: zipcode-lookup
      description: Look up ZIP Code by address.
      operations:
      - method: GET
        name: get-zip-code
        description: Get ZIP Code.
        call: usps-addresses.get-zip-code
        with:
          streetAddress: rest.streetAddress
          city: rest.city
          state: rest.state
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rates/base
      name: base-rates
      description: Search base postage rates.
      operations:
      - method: POST
        name: search-base-rates
        description: Get base postage rates for a shipment.
        call: usps-domestic-prices.search-base-rates
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/rates/total
      name: total-rates
      description: Search total postage rates with fees.
      operations:
      - method: POST
        name: search-total-rates
        description: Get total postage rates including all fees.
        call: usps-domestic-prices.search-total-rates
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pickups
      name: pickups
      description: Schedule a USPS carrier pickup.
      operations:
      - method: POST
        name: schedule-pickup
        description: Schedule carrier pickup.
        call: usps-carrier-pickup.schedule-carrier-pickup
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pickups/{confirmationNumber}
      name: pickup-management
      description: Manage an existing pickup.
      operations:
      - method: GET
        name: get-pickup
        description: Get pickup details.
        call: usps-carrier-pickup.get-carrier-pickup
        with:
          confirmationNumber: rest.confirmationNumber
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: cancel-pickup
        description: Cancel a pickup.
        call: usps-carrier-pickup.cancel-carrier-pickup
        with:
          confirmationNumber: rest.confirmationNumber
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: usps-ecommerce-shipping-mcp
    transport: http
    description: MCP server for AI-assisted USPS e-commerce shipping workflows.
    tools:
    - name: validate-shipping-address
      description: Validate and standardize a US shipping address to USPS specifications.
      hints:
        readOnly: true
        openWorld: true
      call: usps-addresses.validate-address
      with:
        streetAddress: tools.streetAddress
        city: tools.city
        state: tools.state
        ZIPCode: tools.ZIPCode
      outputParameters:
      - type: object
        mapping: $.
    - name: get-city-state
      description: Get city and state name for a ZIP Code.
      hints:
        readOnly: true
        openWorld: true
      call: usps-addresses.get-city-state
      with:
        ZIPCode: tools.ZIPCode
      outputParameters:
      - type: object
        mapping: $.
    - name: get-zip-code
      description: Look up ZIP Code for a street address.
      hints:
        readOnly: true
        openWorld: true
      call: usps-addresses.get-zip-code
      with:
        streetAddress: tools.streetAddress
        city: tools.city
        state: tools.state
      outputParameters:
      - type: object
        mapping: $.
    - name: search-base-rates
      description: Search USPS base postage rates for a domestic shipment by weight, dimensions, and mail class.
      hints:
        readOnly: true
        openWorld: true
      call: usps-domestic-prices.search-base-rates
      outputParameters:
      - type: object
        mapping: $.
    - name: search-total-rates
      description: Get total USPS postage rates including extra service fees for a complete shipping configuration.
      hints:
        readOnly: true
        openWorld: true
      call: usps-domestic-prices.search-total-rates
      outputParameters:
      - type: object
        mapping: $.
    - name: schedule-carrier-pickup
      description: Schedule a free USPS carrier pickup at a residential or commercial address.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: usps-carrier-pickup.schedule-carrier-pickup
      outputParameters:
      - type: object
        mapping: $.
    - name: get-carrier-pickup
      description: Retrieve details of a scheduled USPS carrier pickup by confirmation number.
      hints:
        readOnly: true
        openWorld: true
      call: usps-carrier-pickup.get-carrier-pickup
      with:
        confirmationNumber: tools.confirmationNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-carrier-pickup
      description: Cancel a previously scheduled USPS carrier pickup.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: usps-carrier-pickup.cancel-carrier-pickup
      with:
        confirmationNumber: tools.confirmationNumber
      outputParameters:
      - type: object
        mapping: $.