BioMCP

Instructions

Retrieves all available information for a variant including:
- Gene location and consequences
- Population frequencies across databases
- Clinical significance from ClinVar
- Functional predictions
- External annotations (TCGA cancer data, conservation scores)

Accepts various ID formats:
- HGVS: NM_004333.4:c.1799T>A
- rsID: rs113488022
- MyVariant ID: chr7:g.140753336A>T

Implementation Reference

• src/biomcp/individual_tools.py:587-622 (handler)

  MCP tool registration and handler function for 'variant_getter'. Defines input schema via Annotated parameters and docstring. Delegates to internal _variant_details function.

  @mcp_app.tool()
  @track_performance("biomcp.variant_getter")
  async def variant_getter(
      variant_id: Annotated[
          str,
          Field(
              description="Variant ID (HGVS, rsID, or MyVariant ID like 'chr7:g.140753336A>T')"
          ),
      ],
      include_external: Annotated[
          bool,
          Field(
              description="Include external annotations (TCGA, 1000 Genomes, functional predictions)"
          ),
      ] = True,
  ) -> str:
      """Fetch comprehensive details for a specific genetic variant.
  
      Retrieves all available information for a variant including:
      - Gene location and consequences
      - Population frequencies across databases
      - Clinical significance from ClinVar
      - Functional predictions
      - External annotations (TCGA cancer data, conservation scores)
  
      Accepts various ID formats:
      - HGVS: NM_004333.4:c.1799T>A
      - rsID: rs113488022
      - MyVariant ID: chr7:g.140753336A>T
      """
      return await _variant_details(
          call_benefit="Fetch comprehensive variant annotations for interpretation",
          variant_id=variant_id,
          include_external=include_external,
      )

• src/biomcp/variants/getter.py:145-182 (helper)

  Internal helper function _variant_details called by the variant_getter tool handler. Defines additional parameters and calls the core get_variant function.

  async def _variant_details(
      call_benefit: Annotated[
          str,
          "Define and summarize why this function is being called and the intended benefit",
      ],
      variant_id: str,
      include_external: Annotated[
          bool,
          "Include annotations from external sources (TCGA, 1000 Genomes, cBioPortal)",
      ] = True,
      assembly: Annotated[
          str,
          "Genome assembly (hg19 or hg38). Default: hg19",
      ] = DEFAULT_ASSEMBLY,
  ) -> str:
      """
      Retrieves detailed information for a *single* genetic variant.
  
      Parameters:
      - call_benefit: Define and summarize why this function is being called and the intended benefit
      - variant_id: A variant identifier ("chr7:g.140453136A>T")
      - include_external: Include annotations from TCGA, 1000 Genomes, cBioPortal, and Mastermind
      - assembly: Genome assembly (hg19 or hg38). Default: hg19
  
      Process: Queries the MyVariant.info GET endpoint, optionally fetching
              additional annotations from external databases
      Output: A Markdown formatted string containing comprehensive
              variant annotations (genomic context, frequencies,
              predictions, clinical data, external annotations). Returns error if invalid.
      Note: Use the variant_searcher to find the variant id first.
      """
      return await get_variant(
          variant_id,
          output_json=False,
          include_external=include_external,
          assembly=assembly,
      )

• src/biomcp/variants/getter.py:42-143 (helper)

  Core implementation get_variant function that queries MyVariant.info API, processes response, adds links/filters/external annotations/OncoKB, and renders to markdown or JSON.

  async def get_variant(  # noqa: C901
      variant_id: str,
      output_json: bool = False,
      include_external: bool = False,
      assembly: str = DEFAULT_ASSEMBLY,
  ) -> str:
      """
      Get variant details from MyVariant.info using the variant identifier.
  
      The identifier can be a full HGVS-style string (e.g. "chr7:g.140453136A>T")
      or an rsID (e.g. "rs113488022"). The API response is expected to include a
      "hits" array; this function extracts the first hit.
  
      Args:
          variant_id: Variant identifier (HGVS or rsID)
          output_json: Return JSON format if True, else Markdown
          include_external: Include external annotations (TCGA, 1000 Genomes, cBioPortal)
          assembly: Genome assembly (hg19 or hg38), defaults to hg19
  
      Returns:
          Formatted variant data as JSON or Markdown string
  
      If output_json is True, the result is returned as a formatted JSON string;
      otherwise, it is rendered as Markdown.
      """
      response, error = await http_client.request_api(
          url=f"{MYVARIANT_GET_URL}/{variant_id}",
          request={"fields": "all", "assembly": assembly},
          method="GET",
          domain="myvariant",
      )
  
      # Handle errors gracefully with user-friendly messages
      if error:
          data_to_return = _format_error_response(error, variant_id)
          # Skip all processing for error responses
          if output_json:
              return json.dumps(data_to_return, indent=2)
          else:
              return render.to_markdown(data_to_return)
  
      data_to_return = ensure_list(response)
  
      # Inject database links into the variant data
      data_to_return = inject_links(data_to_return)
      data_to_return = filter_variants(data_to_return)
  
      # Collect OncoKB annotations separately for markdown appendage
      oncokb_annotations: list[str] = []
  
      # Add external annotations if requested
      if include_external and data_to_return:
          logger.info(
              f"Adding external annotations for {len(data_to_return)} variants"
          )
          aggregator = ExternalVariantAggregator()
  
          for _i, variant_data in enumerate(data_to_return):
              logger.info(
                  f"Processing variant {_i}: keys={list(variant_data.keys())}"
              )
              # Get enhanced annotations
              enhanced = await aggregator.get_enhanced_annotations(
                  variant_id,
                  include_tcga=True,
                  include_1000g=True,
                  include_cbioportal=True,
                  variant_data=variant_data,
              )
  
              # Add formatted annotations to the variant data
              formatted = format_enhanced_annotations(enhanced)
              logger.info(
                  f"Formatted external annotations: {formatted['external_annotations'].keys()}"
              )
              variant_data.update(formatted["external_annotations"])
  
              # Get formatted OncoKB annotation separately
              gene_aa = aggregator._extract_gene_aa_change(variant_data)
              # Handle case where method might be mocked as async in tests
              if inspect.iscoroutine(gene_aa) or inspect.isawaitable(gene_aa):
                  gene_aa = await gene_aa
              if gene_aa:
                  parts = gene_aa.split(" ", 1)
                  if len(parts) == 2:
                      gene, variant = parts
                      oncokb_formatted = await get_oncokb_annotation_for_variant(
                          gene, variant
                      )
                      if oncokb_formatted:
                          oncokb_annotations.append(oncokb_formatted)
  
      if output_json:
          return json.dumps(data_to_return, indent=2)
      else:
          # Render base markdown and append OncoKB annotations
          base_markdown = render.to_markdown(data_to_return)
          if oncokb_annotations:
              # Append OncoKB annotations as separate markdown sections
              return base_markdown + "\n" + "\n".join(oncokb_annotations)
          return base_markdown

• src/biomcp/individual_tools.py:31-31 (registration)

  Import of the _variant_details helper function used by the variant_getter tool.

  from biomcp.variants.getter import _variant_details