naftiko: 1.0.0-alpha2
info:
  label: SAM.gov Federal Procurement
  description: Federal procurement workflow for validating vendor registration data against SAM.gov location services. Used
    by government contractors, procurement officers, and vendor registration systems to validate address data before submission
    to SAM.gov.
  tags:
  - Government
  - Federal Procurement
  - Location Validation
  - Vendor Registration
  - GSA
  - SAM.gov
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SAM_GOV_API_KEY: SAM_GOV_API_KEY
capability:
  consumes:
  - type: http
    namespace: sam-location
    baseUri: https://api.sam.gov
    description: SAM.gov Public Location Services API
    authentication:
      type: apikey
      key: api_key
      value: '{{SAM_GOV_API_KEY}}'
      placement: query
    resources:
    - name: cities
      path: /locationservices/v1/cities
      description: City lookup and validation
      operations:
      - name: get-cities
        method: GET
        description: Get a list of cities for a given country code
        inputParameters:
        - name: cc
          in: query
          type: string
          required: false
          description: Country code (ISO 3166-1 alpha-2)
        - name: q
          in: query
          type: string
          required: false
          description: Search query for city name
        - name: active
          in: query
          type: string
          required: false
          description: Filter active cities (Y/N)
        - name: citycode
          in: query
          type: string
          required: false
          description: Filter by city code
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: states
      path: /locationservices/v1/states
      description: State and province lookup
      operations:
      - name: get-states
        method: GET
        description: Get a list of states and provinces
        inputParameters:
        - name: cc
          in: query
          type: string
          required: false
          description: Country code (ISO 3166-1 alpha-2)
        - name: q
          in: query
          type: string
          required: false
          description: Search query for state name
        - name: active
          in: query
          type: string
          required: false
          description: Filter active states (Y/N)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: zip
      path: /locationservices/v1/zip
      description: ZIP code validation
      operations:
      - name: validate-zip-code
        method: GET
        description: Validate a ZIP code and get associated city/county data
        inputParameters:
        - name: zip
          in: query
          type: string
          required: true
          description: ZIP code to validate
        - name: statecode
          in: query
          type: string
          required: false
          description: State code filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: federal-procurement-api
    description: Unified REST API for SAM.gov federal procurement location validation.
    resources:
    - path: /v1/cities
      name: cities
      description: Validated city data from SAM.gov
      operations:
      - method: GET
        name: get-cities
        description: Get list of cities for vendor address validation
        call: sam-location.get-cities
        with:
          cc: rest.cc
          q: rest.q
          active: rest.active
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/states
      name: states
      description: Validated state and province data from SAM.gov
      operations:
      - method: GET
        name: get-states
        description: Get list of states for vendor address validation
        call: sam-location.get-states
        with:
          cc: rest.cc
          q: rest.q
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/zip-codes
      name: zip-codes
      description: ZIP code validation against SAM.gov data
      operations:
      - method: GET
        name: validate-zip-code
        description: Validate a ZIP code for SAM.gov submission
        call: sam-location.validate-zip-code
        with:
          zip: rest.zip
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9080
    namespace: federal-procurement-mcp
    transport: http
    description: MCP server for AI-assisted federal procurement and SAM.gov location validation.
    tools:
    - name: lookup-cities
      description: Look up and validate city names against SAM.gov for vendor address submission
      hints:
        readOnly: true
        idempotent: true
        openWorld: true
      call: sam-location.get-cities
      with:
        cc: tools.country_code
        q: tools.city_name
      outputParameters:
      - type: object
        mapping: $.
    - name: lookup-states
      description: Look up and validate US states and international provinces against SAM.gov
      hints:
        readOnly: true
        idempotent: true
        openWorld: true
      call: sam-location.get-states
      with:
        cc: tools.country_code
        q: tools.state_name
      outputParameters:
      - type: object
        mapping: $.
    - name: validate-zip-code
      description: Validate a ZIP code against SAM.gov location data for vendor registration accuracy
      hints:
        readOnly: true
        idempotent: true
        openWorld: true
      call: sam-location.validate-zip-code
      with:
        zip: tools.zip_code
      outputParameters:
      - type: object
        mapping: $.