naftiko: 1.0.0-alpha2
info:
  label: Science Museum Group Collection Discovery
  description: Unified capability for exploring and discovering artifacts, people, and documents in the Science Museum Group's
    collection across five UK museums. Enables researchers, educators, developers, and cultural heritage professionals to
    search, browse, and retrieve detailed records from over 7 million items in the world's leading science and technology
    museum collection.
  tags:
  - Museums
  - Collections
  - Cultural Heritage
  - Open Data
  - Science
  - History
  - Research
  - Education
  created: '2026-05-02'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: smg-collection
    baseUri: https://collection.sciencemuseumgroup.org.uk
    description: Science Museum Group Collection API - open access, no authentication required
    resources:
    - name: search-all
      path: /search
      description: Full-text and filtered search across all collection types
      operations:
      - name: search-all-collection
        method: GET
        description: Search all objects, people, and documents in the collection
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Full-text search query term
        - name: page[number]
          in: query
          type: integer
          required: false
          description: Zero-indexed page number
        - name: page[size]
          in: query
          type: integer
          required: false
          description: Results per page (max 100)
        - name: date[from]
          in: query
          type: string
          required: false
          description: Filter from date
        - name: date[to]
          in: query
          type: string
          required: false
          description: Filter to date
        - name: places
          in: query
          type: string
          required: false
          description: Filter by geographical association
        - name: images
          in: query
          type: boolean
          required: false
          description: Filter to items with images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search-objects
      path: /search/objects
      description: Search physical objects and artifacts in the collection
      operations:
      - name: search-objects
        method: GET
        description: Search collection objects with filtering by type, maker, museum, category, and display status
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: type
          in: query
          type: string
          required: false
          description: Object type filter
        - name: makers
          in: query
          type: string
          required: false
          description: Filter by maker or manufacturer
        - name: museum
          in: query
          type: string
          required: false
          description: Filter by museum code (NRM, SMG, NMeM, MSI)
        - name: on_display
          in: query
          type: boolean
          required: false
          description: Filter to objects on display
        - name: categories
          in: query
          type: string
          required: false
          description: Filter by collection category
        - name: places
          in: query
          type: string
          required: false
          description: Filter by geographical association
        - name: images
          in: query
          type: boolean
          required: false
          description: Filter to objects with images
        - name: page[number]
          in: query
          type: integer
          required: false
          description: Zero-indexed page number
        - name: page[size]
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search-people
      path: /search/people
      description: Search people associated with the museum collections
      operations:
      - name: search-people
        method: GET
        description: Search for scientists, engineers, makers and historical figures in the collection
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: occupation
          in: query
          type: string
          required: false
          description: Filter by occupation
        - name: birth[place]
          in: query
          type: string
          required: false
          description: Filter by birth place
        - name: birth[date]
          in: query
          type: string
          required: false
          description: Filter by birth date
        - name: places
          in: query
          type: string
          required: false
          description: Filter by geographical association
        - name: page[number]
          in: query
          type: integer
          required: false
          description: Zero-indexed page number
        - name: page[size]
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search-documents
      path: /search/documents
      description: Search documents and archives in the collection
      operations:
      - name: search-documents
        method: GET
        description: Search for documents, archives, and written records
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: makers
          in: query
          type: string
          required: false
          description: Filter by document creator
        - name: people
          in: query
          type: string
          required: false
          description: Filter by associated person
        - name: archive
          in: query
          type: string
          required: false
          description: Filter by archive reference
        - name: page[number]
          in: query
          type: integer
          required: false
          description: Zero-indexed page number
        - name: page[size]
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: objects
      path: /objects/{id}
      description: Retrieve individual collection objects by ID
      operations:
      - name: get-object
        method: GET
        description: Retrieve a single collection object with full metadata, images, and relationships
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Collection object identifier (e.g., co26704)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: people
      path: /people/{id}
      description: Retrieve individual person records by ID
      operations:
      - name: get-person
        method: GET
        description: Retrieve a single person record with biographical data and image references
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Person identifier (e.g., cp22644)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: documents
      path: /documents/{id}
      description: Retrieve individual document records by ID
      operations:
      - name: get-document
        method: GET
        description: Retrieve a single document record with metadata and archive location
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Document identifier (e.g., cd23456)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: smg-discovery-api
    description: Unified REST API for Science Museum Group collection discovery.
    resources:
    - path: /v1/search
      name: search-all
      description: Search all collection types simultaneously
      operations:
      - method: GET
        name: search-all-collection
        description: Full-text search across objects, people, and documents
        call: smg-collection.search-all-collection
        with:
          q: rest.q
          places: rest.places
          images: rest.images
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/objects
      name: objects
      description: Browse and search collection objects
      operations:
      - method: GET
        name: search-objects
        description: Search physical artifacts with museum, category, and date filters
        call: smg-collection.search-objects
        with:
          q: rest.q
          type: rest.type
          makers: rest.makers
          museum: rest.museum
          categories: rest.categories
          on_display: rest.on_display
          images: rest.images
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/objects/{id}
      name: object-detail
      description: Retrieve full object record
      operations:
      - method: GET
        name: get-object
        description: Retrieve a single object with all metadata, images, and relationships
        call: smg-collection.get-object
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/people
      name: people
      description: Browse and search collection people
      operations:
      - method: GET
        name: search-people
        description: Search for scientists, engineers, and historical figures
        call: smg-collection.search-people
        with:
          q: rest.q
          occupation: rest.occupation
          places: rest.places
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/people/{id}
      name: person-detail
      description: Retrieve full person record
      operations:
      - method: GET
        name: get-person
        description: Retrieve a single person with biographical data
        call: smg-collection.get-person
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/documents
      name: documents
      description: Browse and search collection documents
      operations:
      - method: GET
        name: search-documents
        description: Search for documents and archive materials
        call: smg-collection.search-documents
        with:
          q: rest.q
          makers: rest.makers
          archive: rest.archive
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/documents/{id}
      name: document-detail
      description: Retrieve full document record
      operations:
      - method: GET
        name: get-document
        description: Retrieve a single document with metadata and archive location
        call: smg-collection.get-document
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: smg-discovery-mcp
    transport: http
    description: MCP server for AI-assisted Science Museum Group collection research and discovery.
    tools:
    - name: search-collection
      description: Search the Science Museum Group's collection of 7 million items including scientific instruments, industrial
        machinery, railway artifacts, and cultural objects. Returns matching items with images and metadata.
      hints:
        readOnly: true
        openWorld: true
      call: smg-collection.search-all-collection
      with:
        q: tools.q
        places: tools.places
        images: tools.images
      outputParameters:
      - type: object
        mapping: $.
    - name: search-objects
      description: Search specifically for physical objects and artifacts in the Science Museum Group collection. Filter by
        museum (Science Museum London, National Railway Museum York, Science and Industry Museum Manchester, etc.), category,
        maker, date range, and display status.
      hints:
        readOnly: true
        openWorld: true
      call: smg-collection.search-objects
      with:
        q: tools.q
        type: tools.type
        makers: tools.makers
        museum: tools.museum
        categories: tools.categories
        on_display: tools.on_display
        images: tools.images
      outputParameters:
      - type: object
        mapping: $.
    - name: get-object
      description: Retrieve the complete record for a specific collection object by its ID. Returns full metadata including
        description, date, dimensions, maker, location, and high-resolution image references.
      hints:
        readOnly: true
        idempotent: true
      call: smg-collection.get-object
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: search-people
      description: Search for scientists, engineers, inventors, and historical figures associated with the Science Museum
        Group collection. Filter by occupation, birth place, and date of birth/death.
      hints:
        readOnly: true
        openWorld: true
      call: smg-collection.search-people
      with:
        q: tools.q
        occupation: tools.occupation
        birth_place: tools.birth_place
      outputParameters:
      - type: object
        mapping: $.
    - name: get-person
      description: Retrieve the complete record for a specific person in the collection, including biographical information,
        associated objects, and image references.
      hints:
        readOnly: true
        idempotent: true
      call: smg-collection.get-person
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: search-documents
      description: Search for documents, correspondence, drawings, and archival materials in the Science Museum Group collection.
        Filter by creator, associated people, archive reference, and date range.
      hints:
        readOnly: true
        openWorld: true
      call: smg-collection.search-documents
      with:
        q: tools.q
        makers: tools.makers
        archive: tools.archive
      outputParameters:
      - type: object
        mapping: $.
    - name: get-document
      description: Retrieve the complete record for a specific document in the collection, including metadata, archive location,
        and image scans if available.
      hints:
        readOnly: true
        idempotent: true
      call: smg-collection.get-document
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.