naftiko: 1.0.0-alpha2
info:
  label: Trefle Botanical Data
  description: Workflow capability for Trefle botanical data covering plant search, species detail retrieval, taxonomy navigation,
    and geographic distribution analysis. Designed for gardening applications, agricultural tools, ecological research platforms,
    and farming automation systems that need plant species data.
  tags:
  - Agriculture
  - Botany
  - Data API
  - Ecology
  - Open Data
  - Plants
  - Science
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TREFLE_TOKEN: TREFLE_TOKEN
capability:
  consumes:
  - type: http
    namespace: trefle
    baseUri: https://trefle.io/api/v1
    description: Trefle botanical REST API for plant taxonomy, species, and distribution data.
    authentication:
      type: apikey
      key: token
      value: '{{TREFLE_TOKEN}}'
      placement: query
    resources:
    - name: plants
      path: /plants
      description: Search and browse plant species
      operations:
      - name: list-plants
        method: GET
        description: Returns a paginated list of plant species
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: search-plants
        method: GET
        description: Search for plants by common or scientific name
        inputParameters:
        - name: q
          in: query
          type: string
          required: true
          description: Search query
        - name: page
          in: query
          type: integer
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-plant
        method: GET
        description: Get detailed information about a specific plant
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Plant ID or slug
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: species
      path: /species
      description: Access detailed species data
      operations:
      - name: list-species
        method: GET
        description: Returns a paginated list of plant species with detailed data
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
        - name: filter[common_name]
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: search-species
        method: GET
        description: Search species by common or scientific name
        inputParameters:
        - name: q
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-species
        method: GET
        description: Get comprehensive species data including morphology and distributions
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: families
      path: /families
      description: Browse plant family taxonomy
      operations:
      - name: list-families
        method: GET
        description: List all plant families
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-family
        method: GET
        description: Get a specific plant family
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: genus
      path: /genus
      description: Browse plant genus taxonomy
      operations:
      - name: list-genus
        method: GET
        description: List all plant genera
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-genus
        method: GET
        description: Get a specific plant genus
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: distributions
      path: /distributions
      description: Access geographic distribution data
      operations:
      - name: list-distributions
        method: GET
        description: List all geographic distribution zones
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-plants-by-distribution
        method: GET
        description: Get plants native or established in a specific geographic zone
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Distribution zone slug (e.g., california, france)
        - name: filter[establishment]
          in: query
          type: string
          required: false
          description: Filter by establishment type (native, introduced, etc.)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: trefle-botanical-api
    description: Unified REST API for Trefle botanical data workflows.
    resources:
    - path: /v1/plants
      name: plants
      description: Browse and discover plant species
      operations:
      - method: GET
        name: list-plants
        description: List plant species with pagination
        call: trefle.list-plants
        with:
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/plants/search
      name: plant-search
      description: Search for plants by name
      operations:
      - method: GET
        name: search-plants
        description: Search plants by common or scientific name
        call: trefle.search-plants
        with:
          q: rest.q
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/plants/{id}
      name: plant-detail
      description: Get plant details
      operations:
      - method: GET
        name: get-plant
        description: Get a specific plant by ID or slug
        call: trefle.get-plant
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/species
      name: species
      description: Browse species with detailed botanical data
      operations:
      - method: GET
        name: list-species
        description: List species with taxonomy and growth data
        call: trefle.list-species
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/species/search
      name: species-search
      description: Search species
      operations:
      - method: GET
        name: search-species
        description: Search species by name
        call: trefle.search-species
        with:
          q: rest.q
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/species/{id}
      name: species-detail
      description: Get comprehensive species data
      operations:
      - method: GET
        name: get-species
        description: Get full species data including morphology and distribution
        call: trefle.get-species
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/families
      name: families
      description: Browse plant family taxonomy
      operations:
      - method: GET
        name: list-families
        description: List all plant families
        call: trefle.list-families
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/genus
      name: genus
      description: Browse plant genus taxonomy
      operations:
      - method: GET
        name: list-genus
        description: List all plant genera
        call: trefle.list-genus
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/distributions
      name: distributions
      description: Browse geographic distribution zones
      operations:
      - method: GET
        name: list-distributions
        description: List all distribution zones
        call: trefle.list-distributions
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/distributions/{id}/plants
      name: plants-by-distribution
      description: Get plants in a specific region
      operations:
      - method: GET
        name: get-plants-by-distribution
        description: Get plants native or established in a geographic zone
        call: trefle.get-plants-by-distribution
        with:
          id: rest.id
          filter[establishment]: rest.establishment
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: trefle-botanical-mcp
    transport: http
    description: MCP server for AI-assisted botanical data queries with Trefle.
    tools:
    - name: search-plants
      description: Search the Trefle database for plant species by common or scientific name
      hints:
        readOnly: true
        openWorld: true
      call: trefle.search-plants
      with:
        q: tools.q
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: list-plants
      description: List plant species from Trefle with optional pagination
      hints:
        readOnly: true
        openWorld: true
      call: trefle.list-plants
      with:
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-plant
      description: Get basic information about a plant by Trefle ID or slug
      hints:
        readOnly: true
        openWorld: false
      call: trefle.get-plant
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: search-species
      description: Search Trefle plant species by name for detailed botanical data
      hints:
        readOnly: true
        openWorld: true
      call: trefle.search-species
      with:
        q: tools.q
      outputParameters:
      - type: object
        mapping: $.
    - name: get-species-detail
      description: Get comprehensive species data including morphology, growth requirements, and distribution
      hints:
        readOnly: true
        openWorld: false
      call: trefle.get-species
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-plant-families
      description: List all plant families in the Trefle botanical taxonomy
      hints:
        readOnly: true
        openWorld: true
      call: trefle.list-families
      outputParameters:
      - type: object
        mapping: $.
    - name: list-plant-genera
      description: List all plant genera in the Trefle botanical taxonomy
      hints:
        readOnly: true
        openWorld: true
      call: trefle.list-genus
      outputParameters:
      - type: object
        mapping: $.
    - name: list-distribution-zones
      description: List geographic distribution zones used in Trefle plant range data
      hints:
        readOnly: true
        openWorld: true
      call: trefle.list-distributions
      outputParameters:
      - type: object
        mapping: $.
    - name: get-plants-in-region
      description: Get plant species native or established in a specific geographic region
      hints:
        readOnly: true
        openWorld: false
      call: trefle.get-plants-by-distribution
      with:
        id: tools.id
        filter[establishment]: tools.establishment
      outputParameters:
      - type: object
        mapping: $.