naftiko: 1.0.0-alpha2
info:
  label: Web of Science Academic Research
  description: Unified academic research workflow combining Web of Science Starter and Expanded APIs for bibliographic search,
    citation analysis, journal discovery, and bibliometric reporting. Used by researchers, librarians, and data analysts to
    automate literature review and citation analysis.
  tags:
  - Research
  - Academic
  - Bibliometrics
  - Citations
  - Literature Review
  - Science
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    WOS_API_KEY: WOS_API_KEY
capability:
  consumes:
  - type: http
    namespace: wos-starter
    baseUri: https://api.clarivate.com/apis/wos-starter/v1
    description: Web of Science Starter API for document and journal search.
    resources:
    - name: documents
      path: /documents
      description: Document search and retrieval
      operations:
      - name: search-documents
        method: GET
        description: Search Web of Science documents
        inputParameters:
        - name: q
          in: query
          type: string
          required: true
          description: Advanced query syntax string
        - name: db
          in: query
          type: string
          required: false
          description: Database to search
        - name: limit
          in: query
          type: integer
          required: false
          description: Number of records to return
        - name: page
          in: query
          type: integer
          required: false
          description: Page number for pagination
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: document
      path: /documents/{uid}
      description: Individual document retrieval
      operations:
      - name: get-document
        method: GET
        description: Get a specific document by UID
        inputParameters:
        - name: uid
          in: path
          type: string
          required: true
          description: Web of Science unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: journals
      path: /journals
      description: Journal search and retrieval
      operations:
      - name: search-journals
        method: GET
        description: Search journals by ISSN or name
        inputParameters:
        - name: issn
          in: query
          type: string
          required: false
          description: Journal ISSN
        - name: q
          in: query
          type: string
          required: false
          description: Free-text search query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: journal
      path: /journals/{id}
      description: Individual journal retrieval
      operations:
      - name: get-journal
        method: GET
        description: Get journal details by ID
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Web of Science journal identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: wos-expanded
    baseUri: https://api.clarivate.com/api/wos
    description: Web of Science API Expanded for full bibliometric analysis.
    resources:
    - name: search
      path: /
      description: Document search operations
      operations:
      - name: search-documents
        method: GET
        description: Search Web of Science documents
        inputParameters:
        - name: databaseId
          in: query
          type: string
          required: true
          description: Database to search
        - name: usrQuery
          in: query
          type: string
          required: true
          description: Advanced search query
        - name: count
          in: query
          type: integer
          required: false
          description: Number of records
        - name: firstRecord
          in: query
          type: integer
          required: false
          description: Starting record for pagination
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: query-results
      path: /query/{queryId}
      description: Paginate through query results
      operations:
      - name: get-query-results
        method: GET
        description: Get results from a previous search query
        inputParameters:
        - name: queryId
          in: path
          type: integer
          required: true
          description: Query identifier from search
        - name: count
          in: query
          type: integer
          required: false
          description: Number of records
        - name: firstRecord
          in: query
          type: integer
          required: false
          description: Starting record
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: record-ids
      path: /recordids/{queryId}
      description: Get record UIDs from a query
      operations:
      - name: get-record-ids
        method: GET
        description: Get only UIDs from a query result set
        inputParameters:
        - name: queryId
          in: path
          type: integer
          required: true
          description: Query identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: record-by-id
      path: /id/{uniqueId}
      description: Retrieve records by UID
      operations:
      - name: get-record-by-id
        method: GET
        description: Get records by WOS unique identifier
        inputParameters:
        - name: uniqueId
          in: path
          type: string
          required: true
          description: WOS unique identifier(s)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: citing
      path: /citing
      description: Find citing articles
      operations:
      - name: get-citing-articles
        method: GET
        description: Get articles citing a specific document
        inputParameters:
        - name: databaseId
          in: query
          type: string
          required: true
          description: Database identifier
        - name: uniqueId
          in: query
          type: string
          required: true
          description: WOS UID of the cited article
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: references
      path: /references
      description: Get document references
      operations:
      - name: get-references
        method: GET
        description: Get the reference list of a document
        inputParameters:
        - name: databaseId
          in: query
          type: string
          required: true
          description: Database identifier
        - name: uniqueId
          in: query
          type: string
          required: true
          description: WOS UID of the document
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: related
      path: /related
      description: Find related records
      operations:
      - name: get-related-records
        method: GET
        description: Get records sharing cited references with a document
        inputParameters:
        - name: databaseId
          in: query
          type: string
          required: true
          description: Database identifier
        - name: uniqueId
          in: query
          type: string
          required: true
          description: WOS UID of the source document
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: citation-report
      path: /citation-report/{queryId}
      description: Citation report generation
      operations:
      - name: get-citation-report
        method: GET
        description: Generate citation report for a query result set
        inputParameters:
        - name: queryId
          in: path
          type: integer
          required: true
          description: Query identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8084
    namespace: academic-research-api
    description: Unified REST API for Web of Science academic research operations.
    resources:
    - path: /v1/documents/search
      name: document-search
      description: Document search
      operations:
      - method: GET
        name: search-documents
        description: Search Web of Science documents
        call: wos-starter.search-documents
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/documents/{uid}
      name: document
      description: Individual document
      operations:
      - method: GET
        name: get-document
        description: Get document by UID
        call: wos-starter.get-document
        with:
          uid: rest.uid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/journals
      name: journals
      description: Journal search
      operations:
      - method: GET
        name: search-journals
        description: Search journals by ISSN or name
        call: wos-starter.search-journals
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/citations/citing
      name: citing-articles
      description: Articles citing a document
      operations:
      - method: GET
        name: get-citing-articles
        description: Get citing articles
        call: wos-expanded.get-citing-articles
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/citations/references
      name: references
      description: Document references
      operations:
      - method: GET
        name: get-references
        description: Get document reference list
        call: wos-expanded.get-references
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/citations/related
      name: related-records
      description: Related records
      operations:
      - method: GET
        name: get-related-records
        description: Get related records
        call: wos-expanded.get-related-records
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reports/citations/{queryId}
      name: citation-report
      description: Citation report
      operations:
      - method: GET
        name: get-citation-report
        description: Get citation report for query
        call: wos-expanded.get-citation-report
        with:
          queryId: rest.queryId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9094
    namespace: academic-research-mcp
    transport: http
    description: MCP server for AI-assisted Web of Science academic research.
    tools:
    - name: search-literature
      description: Search Web of Science literature using advanced query syntax (e.g., TS=climate change AND PY=2020-2024)
      hints:
        readOnly: true
        openWorld: true
      call: wos-starter.search-documents
      outputParameters:
      - type: object
        mapping: $.
    - name: get-paper-details
      description: Get full bibliographic details for a specific Web of Science document by UID
      hints:
        readOnly: true
        openWorld: false
      call: wos-starter.get-document
      with:
        uid: tools.uid
      outputParameters:
      - type: object
        mapping: $.
    - name: find-journal
      description: Look up a journal in Web of Science by ISSN or name to get impact metrics
      hints:
        readOnly: true
        openWorld: false
      call: wos-starter.search-journals
      outputParameters:
      - type: object
        mapping: $.
    - name: get-journal-details
      description: Get detailed information about a journal including JCR profile and categories
      hints:
        readOnly: true
        openWorld: false
      call: wos-starter.get-journal
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: advanced-search
      description: Run advanced Web of Science search with full field tag syntax for comprehensive literature review
      hints:
        readOnly: true
        openWorld: true
      call: wos-expanded.search-documents
      outputParameters:
      - type: object
        mapping: $.
    - name: find-citing-papers
      description: Find all papers that have cited a specific article (forward citation tracking)
      hints:
        readOnly: true
        openWorld: true
      call: wos-expanded.get-citing-articles
      outputParameters:
      - type: object
        mapping: $.
    - name: get-references
      description: Get the complete reference list of a paper (backward citation tracking)
      hints:
        readOnly: true
        openWorld: false
      call: wos-expanded.get-references
      outputParameters:
      - type: object
        mapping: $.
    - name: find-related-research
      description: Discover research papers related to a given article based on shared references
      hints:
        readOnly: true
        openWorld: true
      call: wos-expanded.get-related-records
      outputParameters:
      - type: object
        mapping: $.
    - name: generate-citation-report
      description: Generate a bibliometric citation report including h-index and year-by-year citation counts
      hints:
        readOnly: true
        openWorld: false
      call: wos-expanded.get-citation-report
      outputParameters:
      - type: object
        mapping: $.
    - name: get-record-by-uid
      description: Retrieve a full Web of Science record directly by its unique identifier
      hints:
        readOnly: true
        openWorld: false
      call: wos-expanded.get-record-by-id
      outputParameters:
      - type: object
        mapping: $.