naftiko: 1.0.0-alpha2
info:
  label: RSC Chemical Research
  description: Workflow capability for chemical research and cheminformatics tasks using the RSC ChemSpider database. Supports
    compound discovery, structure lookup, property analysis, and cross-database reference retrieval for researchers, data
    scientists, and pharmaceutical developers working with chemical data.
  tags:
  - Chemistry
  - Cheminformatics
  - Chemical Research
  - RSC
  - ChemSpider
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    RSC_API_KEY: RSC_API_KEY
capability:
  consumes:
  - type: http
    namespace: chemspider-compounds
    baseUri: https://api.rsc.org/compounds/v1
    description: RSC ChemSpider Compounds API for searching and retrieving chemical compound data
    authentication:
      type: apikey
      key: apikey
      value: '{{RSC_API_KEY}}'
      placement: header
    resources:
    - name: filter
      path: /filter
      description: Search and filter chemical compounds by various properties
      operations:
      - name: filter-by-name
        method: POST
        description: Search for compounds by name; returns query ID for polling
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Compound name to search
        - name: orderBy
          in: body
          type: string
          required: false
          description: Sort field for results
        - name: orderDirection
          in: body
          type: string
          required: false
          description: Sort direction (ascending/descending)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: filter-by-smiles
        method: POST
        description: Search for compounds by SMILES string; returns query ID
        inputParameters:
        - name: smiles
          in: body
          type: string
          required: true
          description: SMILES string for compound search
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: filter-by-inchi
        method: POST
        description: Search for compounds by InChI string; returns query ID
        inputParameters:
        - name: inchi
          in: body
          type: string
          required: true
          description: InChI string for compound search
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: filter-by-inchikey
        method: POST
        description: Search for compounds by InChIKey; returns query ID
        inputParameters:
        - name: inchikey
          in: body
          type: string
          required: true
          description: InChIKey for compound search
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: filter-by-formula
        method: POST
        description: Search for compounds by molecular formula; returns query ID
        inputParameters:
        - name: formula
          in: body
          type: string
          required: true
          description: Molecular formula (e.g., C6H12O6)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: filter-by-mass
        method: POST
        description: Search for compounds within a mass range; returns query ID
        inputParameters:
        - name: mass
          in: body
          type: number
          required: true
          description: Target molecular mass
        - name: massRange
          in: body
          type: number
          required: true
          description: Acceptable mass deviation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-filter-status
        method: GET
        description: Poll status of a submitted filter query by query ID
        inputParameters:
        - name: queryId
          in: path
          type: string
          required: true
          description: Query ID from filter submission
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-filter-results
        method: GET
        description: Retrieve record IDs for a completed filter query
        inputParameters:
        - name: queryId
          in: path
          type: string
          required: true
          description: Query ID from filter submission
        - name: start
          in: query
          type: integer
          required: false
          description: Zero-based start index for pagination
        - name: count
          in: query
          type: integer
          required: false
          description: Number of results to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: records
      path: /records
      description: Retrieve compound record details, images, and MOL files
      operations:
      - name: get-record-details
        method: GET
        description: Get detailed properties for a compound by record ID
        inputParameters:
        - name: recordId
          in: path
          type: integer
          required: true
          description: ChemSpider record ID
        - name: fields
          in: query
          type: string
          required: false
          description: Comma-separated list of fields to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-records-batch
        method: POST
        description: Get details for multiple compound records in one request
        inputParameters:
        - name: recordIds
          in: body
          type: array
          required: true
          description: List of ChemSpider record IDs (max 100)
        - name: fields
          in: body
          type: string
          required: false
          description: Comma-separated list of fields to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-external-references
        method: GET
        description: Get external database references for a compound record
        inputParameters:
        - name: recordId
          in: path
          type: integer
          required: true
          description: ChemSpider record ID
        - name: dataSources
          in: query
          type: string
          required: false
          description: Comma-separated data source names to filter
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-record-image
        method: GET
        description: Get 2D structural image for a compound record
        inputParameters:
        - name: recordId
          in: path
          type: integer
          required: true
          description: ChemSpider record ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-record-mol
        method: GET
        description: Get MOL file content for a compound record
        inputParameters:
        - name: recordId
          in: path
          type: integer
          required: true
          description: ChemSpider record ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: lookups
      path: /lookups
      description: Look up reference data including available data sources
      operations:
      - name: get-data-sources
        method: GET
        description: List all available data sources in ChemSpider
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tools
      path: /tools
      description: Chemical format conversion and validation utilities
      operations:
      - name: convert-chemical-format
        method: POST
        description: Convert a chemical identifier between SMILES, InChI, InChIKey, and Mol formats
        inputParameters:
        - name: input
          in: body
          type: string
          required: true
          description: Chemical identifier to convert
        - name: inputFormat
          in: body
          type: string
          required: true
          description: Input format (SMILES, InChI, InChIKey, Mol)
        - name: outputFormat
          in: body
          type: string
          required: true
          description: Output format (SMILES, InChI, InChIKey, Mol)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: validate-inchikey
        method: POST
        description: Validate whether a string is a correctly formed InChIKey
        inputParameters:
        - name: inchikey
          in: body
          type: string
          required: true
          description: InChIKey string to validate
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: chemical-research-api
    description: Unified REST API for chemical compound research and cheminformatics workflows.
    resources:
    - path: /v1/compounds/search/name
      name: compound-name-search
      description: Search for compounds by name
      operations:
      - method: POST
        name: search-compounds-by-name
        description: Submit a name-based compound search
        call: chemspider-compounds.filter-by-name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/search/smiles
      name: compound-smiles-search
      description: Search for compounds by SMILES
      operations:
      - method: POST
        name: search-compounds-by-smiles
        description: Submit a SMILES-based compound search
        call: chemspider-compounds.filter-by-smiles
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/search/formula
      name: compound-formula-search
      description: Search for compounds by molecular formula
      operations:
      - method: POST
        name: search-compounds-by-formula
        description: Submit a formula-based compound search
        call: chemspider-compounds.filter-by-formula
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/search/mass
      name: compound-mass-search
      description: Search for compounds by molecular mass
      operations:
      - method: POST
        name: search-compounds-by-mass
        description: Submit a mass-based compound search
        call: chemspider-compounds.filter-by-mass
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/search/{queryId}/status
      name: search-status
      description: Check status of a compound search query
      operations:
      - method: GET
        name: get-search-status
        description: Poll search query status
        call: chemspider-compounds.get-filter-status
        with:
          queryId: rest.queryId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/search/{queryId}/results
      name: search-results
      description: Retrieve results from a completed compound search
      operations:
      - method: GET
        name: get-search-results
        description: Get compound search results
        call: chemspider-compounds.get-filter-results
        with:
          queryId: rest.queryId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/{recordId}
      name: compound-details
      description: Get compound details by ChemSpider record ID
      operations:
      - method: GET
        name: get-compound
        description: Retrieve compound properties
        call: chemspider-compounds.get-record-details
        with:
          recordId: rest.recordId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/{recordId}/references
      name: compound-references
      description: Get external database references for a compound
      operations:
      - method: GET
        name: get-compound-references
        description: Retrieve external references for a compound
        call: chemspider-compounds.get-external-references
        with:
          recordId: rest.recordId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/compounds/batch
      name: compound-batch
      description: Get details for multiple compounds
      operations:
      - method: POST
        name: get-compounds-batch
        description: Retrieve details for multiple compounds
        call: chemspider-compounds.get-records-batch
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tools/convert
      name: format-conversion
      description: Convert between chemical identifier formats
      operations:
      - method: POST
        name: convert-format
        description: Convert SMILES, InChI, InChIKey, or Mol format
        call: chemspider-compounds.convert-chemical-format
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tools/validate/inchikey
      name: inchikey-validation
      description: Validate InChIKey format
      operations:
      - method: POST
        name: validate-inchikey
        description: Check if an InChIKey is valid
        call: chemspider-compounds.validate-inchikey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/data-sources
      name: data-sources
      description: List available data sources
      operations:
      - method: GET
        name: list-data-sources
        description: Get all available ChemSpider data sources
        call: chemspider-compounds.get-data-sources
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: chemical-research-mcp
    transport: http
    description: MCP server for AI-assisted chemical research using the RSC ChemSpider database.
    tools:
    - name: search-compound-by-name
      description: Search the RSC ChemSpider database for compounds by chemical name
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-name
      with:
        name: tools.name
      outputParameters:
      - type: object
        mapping: $.
    - name: search-compound-by-smiles
      description: Search the RSC ChemSpider database for compounds matching a SMILES string
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-smiles
      with:
        smiles: tools.smiles
      outputParameters:
      - type: object
        mapping: $.
    - name: search-compound-by-inchi
      description: Search the RSC ChemSpider database for compounds by InChI string
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-inchi
      with:
        inchi: tools.inchi
      outputParameters:
      - type: object
        mapping: $.
    - name: search-compound-by-inchikey
      description: Search the RSC ChemSpider database for a compound by InChIKey
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-inchikey
      with:
        inchikey: tools.inchikey
      outputParameters:
      - type: object
        mapping: $.
    - name: search-compound-by-formula
      description: Search the RSC ChemSpider database for compounds by molecular formula (e.g., C6H12O6)
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-formula
      with:
        formula: tools.formula
      outputParameters:
      - type: object
        mapping: $.
    - name: search-compound-by-mass
      description: Search the RSC ChemSpider database for compounds within a molecular mass range
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.filter-by-mass
      with:
        mass: tools.mass
        massRange: tools.massRange
      outputParameters:
      - type: object
        mapping: $.
    - name: check-search-status
      description: Check the status of a ChemSpider compound search query
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.get-filter-status
      with:
        queryId: tools.queryId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-search-results
      description: Retrieve compound record IDs from a completed ChemSpider search query
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.get-filter-results
      with:
        queryId: tools.queryId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-compound-details
      description: Get detailed chemical properties for a compound by ChemSpider record ID
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.get-record-details
      with:
        recordId: tools.recordId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-compound-batch
      description: Get detailed properties for multiple compounds at once (up to 100)
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.get-records-batch
      with:
        recordIds: tools.recordIds
      outputParameters:
      - type: object
        mapping: $.
    - name: get-compound-external-references
      description: Get external database references (PubChem, PubMed, etc.) for a compound
      hints:
        readOnly: true
        openWorld: true
      call: chemspider-compounds.get-external-references
      with:
        recordId: tools.recordId
      outputParameters:
      - type: object
        mapping: $.
    - name: convert-chemical-identifier
      description: Convert a chemical identifier between SMILES, InChI, InChIKey, and Mol file formats
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.convert-chemical-format
      with:
        input: tools.input
        inputFormat: tools.inputFormat
        outputFormat: tools.outputFormat
      outputParameters:
      - type: object
        mapping: $.
    - name: validate-inchikey
      description: Validate whether a string is a correctly formed InChIKey
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.validate-inchikey
      with:
        inchikey: tools.inchikey
      outputParameters:
      - type: object
        mapping: $.
    - name: list-data-sources
      description: List all data sources available in ChemSpider for filtering searches
      hints:
        readOnly: true
        openWorld: false
      call: chemspider-compounds.get-data-sources
      outputParameters:
      - type: object
        mapping: $.