Trimble Navigation GNSS Positioning

naftiko: "1.0.0-alpha1"

info:
  label: "Trimble Navigation GNSS Positioning"
  description: >-
    Unified GNSS positioning capability combining Trimble Mobile Manager receiver
    integration, real-time position streaming, correction service management, and
    Catalyst license activation. Powers high-accuracy field data collection apps
    for surveying, construction, and precision agriculture.
  tags:
    - Trimble Navigation
    - GPS
    - GNSS
    - Positioning
    - Navigation
    - Surveying
    - Precision Agriculture
    - Construction
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TMM_APP_ID: TMM_APP_ID

capability:
  consumes:
    - import: trimble-tmm
      location: ./shared/trimble-mobile-manager.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: gnss-positioning-api
      description: "Unified REST API for Trimble GNSS positioning and receiver management."
      resources:
        - path: /v1/system/info
          name: system-info
          description: TMM system information
          operations:
            - method: GET
              name: get-tmm-info
              description: Get TMM version and WebSocket port information
              call: "trimble-tmm.get-tmm-info"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/position/stream
          name: position-stream
          description: GNSS position stream initialization
          operations:
            - method: GET
              name: start-position-stream
              description: Initiate real-time GNSS position streaming
              call: "trimble-tmm.start-position-stream"
              with:
                format: "rest.format"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/receiver/info
          name: receiver-info
          description: GNSS receiver hardware details
          operations:
            - method: GET
              name: get-receiver-info
              description: Get connected receiver model and firmware version
              call: "trimble-tmm.get-receiver-info"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/receiver/status
          name: receiver-status
          description: Current receiver status
          operations:
            - method: GET
              name: get-receiver-status
              description: Get receiver connection and signal status
              call: "trimble-tmm.get-receiver-status"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/corrections/status
          name: corrections-status
          description: GNSS correction service status
          operations:
            - method: GET
              name: get-corrections-status
              description: Get active correction service and accuracy level
              call: "trimble-tmm.get-corrections-status"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/corrections/configure
          name: corrections-config
          description: Configure correction sources
          operations:
            - method: POST
              name: configure-corrections
              description: Configure RTX, RTK, SBAS, or NTRIP corrections
              call: "trimble-tmm.configure-corrections"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalyst/licenses
          name: catalyst-licenses
          description: Catalyst accuracy licenses
          operations:
            - method: GET
              name: get-catalyst-licenses
              description: List available Catalyst positioning accuracy licenses
              call: "trimble-tmm.get-catalyst-licenses"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/catalyst/licenses/activate
          name: catalyst-activate
          description: Activate Catalyst license
          operations:
            - method: POST
              name: activate-catalyst-license
              description: Activate Catalyst On Demand license for enhanced accuracy
              call: "trimble-tmm.activate-catalyst-license"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: gnss-positioning-mcp
      transport: http
      description: "MCP server for AI-assisted GNSS receiver management and positioning."
      tools:
        - name: get-tmm-info
          description: Get Trimble Mobile Manager system information including WebSocket ports
          hints:
            readOnly: true
            openWorld: false
          call: "trimble-tmm.get-tmm-info"
          outputParameters:
            - type: object
              mapping: "$."

        - name: start-position-stream
          description: Start real-time GNSS position streaming, returns WebSocket port to connect to
          hints:
            readOnly: false
            openWorld: false
          call: "trimble-tmm.start-position-stream"
          with:
            format: "tools.format"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-receiver-info
          description: Get connected Trimble GNSS receiver model, serial number, and firmware version
          hints:
            readOnly: true
            openWorld: false
          call: "trimble-tmm.get-receiver-info"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-receiver-status
          description: Check current GNSS receiver connection status and signal strength
          hints:
            readOnly: true
            openWorld: false
          call: "trimble-tmm.get-receiver-status"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-corrections-status
          description: Check active GNSS correction service (RTX, RTK, SBAS) and current accuracy
          hints:
            readOnly: true
            openWorld: false
          call: "trimble-tmm.get-corrections-status"
          outputParameters:
            - type: object
              mapping: "$."

        - name: configure-corrections
          description: Configure GNSS correction source (RTX, RTK, SBAS, or NTRIP)
          hints:
            readOnly: false
            idempotent: true
          call: "trimble-tmm.configure-corrections"
          with:
            type: "tools.type"
            ntripHost: "tools.ntripHost"
            ntripMountpoint: "tools.ntripMountpoint"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-catalyst-licenses
          description: List available Trimble Catalyst positioning accuracy licenses
          hints:
            readOnly: true
            openWorld: false
          call: "trimble-tmm.get-catalyst-licenses"
          outputParameters:
            - type: object
              mapping: "$."

        - name: activate-catalyst-license
          description: Activate a Trimble Catalyst On Demand license for enhanced positioning accuracy
          hints:
            readOnly: false
            openWorld: false
          call: "trimble-tmm.activate-catalyst-license"
          with:
            licenseId: "tools.licenseId"
          outputParameters:
            - type: object
              mapping: "$."