Smithsonian Collection Discovery

naftiko: "1.0.0-alpha1"

info:
  label: Smithsonian Collection Discovery
  description: >-
    Workflow capability for discovering and exploring Smithsonian Institution collections.
    Used by researchers, educators, and developers to search across 22 million museum
    objects, artworks, and natural history specimens, retrieve detailed metadata,
    explore subject categories, and get collection statistics.
  tags:
    - Smithsonian Institution
    - Collections
    - Museums
    - Open Data
    - Cultural Heritage
    - Research
    - Education
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SMITHSONIAN_API_KEY: SMITHSONIAN_API_KEY

capability:
  consumes:
    - import: smithsonian-open-access
      location: ./shared/open-access-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: collection-discovery-api
      description: Unified REST API for Smithsonian collection discovery and exploration.
      resources:
        - path: /v1/search
          name: search
          description: Full-text collection search
          operations:
            - method: GET
              name: search-collections
              description: Search across all Smithsonian collections
              call: "smithsonian-open-access.search-collections"
              with:
                q: "rest.q"
                start: "rest.start"
                rows: "rest.rows"
                sort: "rest.sort"
                type: "rest.type"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/search/category
          name: category-search
          description: Category-filtered search
          operations:
            - method: GET
              name: search-by-category
              description: Search by subject category
              call: "smithsonian-open-access.search-by-category"
              with:
                q: "rest.q"
                category: "rest.category"
                start: "rest.start"
                rows: "rest.rows"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/items/{id}
          name: item
          description: Individual collection item
          operations:
            - method: GET
              name: get-item
              description: Get detailed metadata for a collection item
              call: "smithsonian-open-access.get-content"
              with:
                id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/search/terms
          name: search-terms
          description: Search facet terms
          operations:
            - method: GET
              name: get-terms
              description: Get available terms for search faceting
              call: "smithsonian-open-access.get-search-terms"
              with:
                category: "rest.category"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/metrics
          name: metrics
          description: Collection statistics
          operations:
            - method: GET
              name: get-metrics
              description: Get collection statistics and metrics
              call: "smithsonian-open-access.get-metrics-stats"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: collection-discovery-mcp
      transport: http
      description: MCP server for AI-assisted Smithsonian collection discovery.
      tools:
        - name: search-collections
          description: >-
            Search across all 22 million Smithsonian collection items including
            artworks, natural history specimens, cultural objects, and archival materials
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.search-collections"
          with:
            q: "tools.q"
            start: "tools.start"
            rows: "tools.rows"
            sort: "tools.sort"
            type: "tools.type"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-art-and-design
          description: Search Smithsonian art and design collections specifically
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.search-by-category"
          with:
            q: "tools.q"
            category: "art_design"
            start: "tools.start"
            rows: "tools.rows"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-history-and-culture
          description: Search Smithsonian history and cultural collections
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.search-by-category"
          with:
            q: "tools.q"
            category: "history_culture"
            start: "tools.start"
            rows: "tools.rows"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-science-and-technology
          description: Search Smithsonian science and technology collections
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.search-by-category"
          with:
            q: "tools.q"
            category: "science_technology"
            start: "tools.start"
            rows: "tools.rows"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-collection-item
          description: >-
            Get complete metadata for a specific Smithsonian collection item including
            description, media images, provenance, and classification data
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.get-content"
          with:
            id: "tools.id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: browse-facet-terms
          description: >-
            Get available facet values for filtering searches by culture, place,
            object type, date, topic, or museum unit
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.get-search-terms"
          with:
            category: "tools.category"
            starts_with: "tools.starts_with"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-collection-stats
          description: >-
            Get aggregate statistics about the Smithsonian collections including
            total object counts, online media counts, and open access availability
          hints:
            readOnly: true
            openWorld: true
          call: "smithsonian-open-access.get-metrics-stats"
          outputParameters:
            - type: object
              mapping: "$."