naftiko: 1.0.0-alpha2
info:
  label: USPS Package Tracking
  description: Workflow capability for package tracking and delivery status monitoring. Combines the USPS Tracking API with
    address validation to support customer service teams and logistics operations tracking USPS shipments.
  tags:
  - USPS
  - Package Tracking
  - Logistics
  - Customer Service
  - 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-tracking
    baseUri: https://apis.usps.com
    description: USPS package tracking API.
    authentication:
      type: bearer
      token: '{{USPS_BEARER_TOKEN}}'
    resources:
    - name: tracking
      path: /tracking/v3/tracking
      description: Package tracking status and event history.
      operations:
      - name: get-tracking
        method: GET
        description: Get tracking status for a package.
        inputParameters:
        - name: trackingNumber
          in: path
          type: string
          required: true
          description: USPS tracking number.
        - name: expand
          in: query
          type: string
          required: false
          description: Optional expansion (SUMMARY or DETAIL).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-multiple-tracking
        method: POST
        description: Get tracking status for multiple packages.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            trackingNumbers: '{{tools.trackingNumbers}}'
  - 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: $.
  exposes:
  - type: rest
    port: 8081
    namespace: usps-package-tracking-api
    description: Unified REST API for USPS package tracking and delivery monitoring.
    resources:
    - path: /v1/tracking/{trackingNumber}
      name: package-tracking
      description: Get tracking status for a package.
      operations:
      - method: GET
        name: get-tracking
        description: Track a USPS package.
        call: usps-tracking.get-tracking
        with:
          trackingNumber: rest.trackingNumber
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tracking
      name: bulk-tracking
      description: Track multiple packages.
      operations:
      - method: POST
        name: get-multiple-tracking
        description: Track multiple USPS packages.
        call: usps-tracking.get-multiple-tracking
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/addresses/validate
      name: address-validation
      description: Validate a delivery address.
      operations:
      - method: GET
        name: validate-address
        description: Validate address.
        call: usps-addresses.validate-address
        with:
          streetAddress: rest.streetAddress
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9091
    namespace: usps-package-tracking-mcp
    transport: http
    description: MCP server for AI-assisted USPS package tracking and delivery status.
    tools:
    - name: track-package
      description: Get tracking status and scan event history for a USPS package by tracking number.
      hints:
        readOnly: true
        openWorld: true
      call: usps-tracking.get-tracking
      with:
        trackingNumber: tools.trackingNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: track-multiple-packages
      description: Get tracking status for multiple USPS packages in a single request.
      hints:
        readOnly: true
        openWorld: true
      call: usps-tracking.get-multiple-tracking
      with:
        trackingNumbers: tools.trackingNumbers
      outputParameters:
      - type: object
        mapping: $.
    - name: validate-delivery-address
      description: Validate and standardize a delivery address to ensure USPS deliverability.
      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: $.