naftiko: 1.0.0-alpha2
info:
  label: NLM Biomedical Literature and Clinical Research
  description: Unified capability for biomedical literature research and clinical trial discovery workflows combining NCBI
    E-Utilities (PubMed, Entrez databases) with ClinicalTrials.gov. Used by researchers, clinicians, bioinformaticians, and
    healthcare professionals to search literature, find clinical trials, retrieve gene data, and explore biomedical databases.
  tags:
  - Biomedical Research
  - PubMed
  - Clinical Trials
  - Genomics
  - Healthcare
  - NLM
  - Federal Government
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    NCBI_API_KEY: NCBI_API_KEY
capability:
  consumes:
  - type: http
    namespace: eutils
    baseUri: https://eutils.ncbi.nlm.nih.gov/entrez/eutils
    description: NCBI E-Utilities Entrez API
    authentication:
      type: apikey
      key: api_key
      value: '{{NCBI_API_KEY}}'
      placement: query
    resources:
    - name: search
      path: /esearch.fcgi
      description: Search Entrez databases
      operations:
      - name: search-database
        method: GET
        description: Search Entrez Database
        inputParameters:
        - name: db
          in: query
          type: string
          required: true
          description: Target database (pubmed, gene, nuccore, etc.)
        - name: term
          in: query
          type: string
          required: true
          description: Search query with optional field tags
        - name: retmax
          in: query
          type: integer
          required: false
          description: Max UIDs to return
        - name: retstart
          in: query
          type: integer
          required: false
          description: Starting index
        - name: retmode
          in: query
          type: string
          required: false
          description: Output format (json or xml)
        - name: sort
          in: query
          type: string
          required: false
          description: Sort order
        - name: datetype
          in: query
          type: string
          required: false
          description: Date field type
        - name: mindate
          in: query
          type: string
          required: false
          description: Minimum date
        - name: maxdate
          in: query
          type: string
          required: false
          description: Maximum date
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: fetch
      path: /efetch.fcgi
      description: Retrieve full records from Entrez
      operations:
      - name: fetch-records
        method: GET
        description: Fetch Records
        inputParameters:
        - name: db
          in: query
          type: string
          required: true
          description: Target database
        - name: id
          in: query
          type: string
          required: false
          description: Comma-separated UIDs
        - name: rettype
          in: query
          type: string
          required: false
          description: Record type (abstract, medline, fasta, etc.)
        - name: retmode
          in: query
          type: string
          required: false
          description: Output format (xml, text, json)
        outputRawFormat: xml
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: summary
      path: /esummary.fcgi
      description: Retrieve document summaries
      operations:
      - name: get-summaries
        method: GET
        description: Get Document Summaries
        inputParameters:
        - name: db
          in: query
          type: string
          required: true
          description: Target database
        - name: id
          in: query
          type: string
          required: false
          description: Comma-separated UIDs
        - name: retmode
          in: query
          type: string
          required: false
          description: Output format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: link
      path: /elink.fcgi
      description: Find linked records across databases
      operations:
      - name: get-linkages
        method: GET
        description: Get Linked Records
        inputParameters:
        - name: dbfrom
          in: query
          type: string
          required: true
          description: Source database
        - name: db
          in: query
          type: string
          required: false
          description: Target database
        - name: id
          in: query
          type: string
          required: true
          description: Source UIDs
        - name: linkname
          in: query
          type: string
          required: false
          description: Named link
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: clinicaltrials
    baseUri: https://clinicaltrials.gov/api/v2
    description: ClinicalTrials.gov REST API v2 - no authentication required
    resources:
    - name: studies
      path: /studies
      description: Search and retrieve clinical trial studies
      operations:
      - name: search-studies
        method: GET
        description: Search Clinical Trial Studies
        inputParameters:
        - name: query.term
          in: query
          type: string
          required: false
          description: Full-text search query
        - name: query.cond
          in: query
          type: string
          required: false
          description: Condition or disease filter
        - name: query.intr
          in: query
          type: string
          required: false
          description: Intervention or treatment filter
        - name: query.spons
          in: query
          type: string
          required: false
          description: Sponsor filter
        - name: filter.overallStatus
          in: query
          type: string
          required: false
          description: Overall status filter
        - name: filter.phase
          in: query
          type: string
          required: false
          description: Clinical trial phase filter
        - name: filter.studyType
          in: query
          type: string
          required: false
          description: Study type filter
        - name: pageSize
          in: query
          type: integer
          required: false
          description: Results per page
        - name: pageToken
          in: query
          type: string
          required: false
          description: Next page token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: study-by-id
      path: /studies/{nctId}
      description: Retrieve a specific clinical trial by NCT ID
      operations:
      - name: get-study
        method: GET
        description: Get Study by NCT ID
        inputParameters:
        - name: nctId
          in: path
          type: string
          required: true
          description: ClinicalTrials.gov NCT identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: dataset-size
      path: /stats/size
      description: Get total count of studies matching criteria
      operations:
      - name: get-dataset-size
        method: GET
        description: Get Dataset Size
        inputParameters:
        - name: query.cond
          in: query
          type: string
          required: false
          description: Condition filter for count
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: nlm-research-api
    description: Unified REST API for NLM biomedical literature and clinical research workflows.
    resources:
    - path: /v1/pubmed/search
      name: pubmed-search
      description: Search PubMed biomedical literature database
      operations:
      - method: GET
        name: search-pubmed
        description: Search PubMed for articles by query, author, or topic
        call: eutils.search-database
        with:
          db: pubmed
          term: rest.query
          retmax: rest.limit
          sort: rest.sort
          mindate: rest.mindate
          maxdate: rest.maxdate
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/pubmed/articles/{pmids}
      name: pubmed-articles
      description: Retrieve PubMed article records
      operations:
      - method: GET
        name: get-pubmed-articles
        description: Fetch full PubMed article records by PMID
        call: eutils.fetch-records
        with:
          db: pubmed
          id: rest.pmids
          rettype: abstract
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/gene/search
      name: gene-search
      description: Search NCBI Gene database
      operations:
      - method: GET
        name: search-genes
        description: Search NCBI Gene database for gene records
        call: eutils.search-database
        with:
          db: gene
          term: rest.query
          retmax: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/trials/search
      name: trial-search
      description: Search ClinicalTrials.gov for clinical trials
      operations:
      - method: GET
        name: search-trials
        description: Search clinical trials by condition, intervention, or status
        call: clinicaltrials.search-studies
        with:
          query.cond: rest.condition
          query.intr: rest.intervention
          filter.overallStatus: rest.status
          filter.phase: rest.phase
          pageSize: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/trials/{nctId}
      name: trial-detail
      description: Retrieve a specific clinical trial
      operations:
      - method: GET
        name: get-trial
        description: Get complete clinical trial record by NCT ID
        call: clinicaltrials.get-study
        with:
          nctId: rest.nctId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: nlm-research-mcp
    transport: http
    description: MCP server for AI-assisted biomedical literature search and clinical research.
    tools:
    - name: search-pubmed
      description: Search PubMed for biomedical literature articles by topic, author, or keywords
      hints:
        readOnly: true
        idempotent: true
      call: eutils.search-database
      with:
        db: pubmed
        term: tools.query
        retmax: tools.max_results
        sort: tools.sort
        mindate: tools.start_date
        maxdate: tools.end_date
      outputParameters:
      - type: object
        mapping: $.
    - name: get-pubmed-abstracts
      description: Retrieve PubMed article abstracts for a list of PMIDs
      hints:
        readOnly: true
        idempotent: true
      call: eutils.fetch-records
      with:
        db: pubmed
        id: tools.pmids
        rettype: abstract
        retmode: text
      outputParameters:
      - type: object
        mapping: $.
    - name: get-pubmed-summaries
      description: Get PubMed document summaries including title, authors, and journal for PMIDs
      hints:
        readOnly: true
        idempotent: true
      call: eutils.get-summaries
      with:
        db: pubmed
        id: tools.pmids
      outputParameters:
      - type: object
        mapping: $.
    - name: search-genes
      description: Search NCBI Gene database for gene records by symbol, name, or description
      hints:
        readOnly: true
        idempotent: true
      call: eutils.search-database
      with:
        db: gene
        term: tools.query
        retmax: tools.max_results
      outputParameters:
      - type: object
        mapping: $.
    - name: search-clinical-trials
      description: Search ClinicalTrials.gov for trials by condition, intervention, phase, or status
      hints:
        readOnly: true
        idempotent: true
      call: clinicaltrials.search-studies
      with:
        query.cond: tools.condition
        query.intr: tools.intervention
        query.spons: tools.sponsor
        filter.overallStatus: tools.status
        filter.phase: tools.phase
        pageSize: tools.page_size
      outputParameters:
      - type: object
        mapping: $.
    - name: get-clinical-trial-details
      description: Retrieve complete protocol, eligibility, and results for a clinical trial by NCT ID
      hints:
        readOnly: true
        idempotent: true
      call: clinicaltrials.get-study
      with:
        nctId: tools.nct_id
      outputParameters:
      - type: object
        mapping: $.
    - name: search-ncbi-database
      description: Search any NCBI Entrez database (nuccore, protein, snp, taxonomy, sra, etc.)
      hints:
        readOnly: true
        idempotent: true
      call: eutils.search-database
      with:
        db: tools.database
        term: tools.query
        retmax: tools.max_results
      outputParameters:
      - type: object
        mapping: $.