bc_get_human_protein_atlas_info

Instructions

Implementation Reference

• src/biocontext_kb/core/proteinatlas/_get_human_protein_atlas_info.py:1-38 (handler)

  The handler/decorator function that executes the 'get_human_protein_atlas_info' tool logic. Uses the @core_mcp.tool() decorator and accepts gene_id or gene_symbol, resolves gene_symbol to Ensembl ID if needed, then fetches data from the Human Protein Atlas API (proteinatlas.org/{gene_id}.json).

  from typing import Annotated, Optional
  
  import requests
  from pydantic import Field
  
  from biocontext_kb.core._server import core_mcp
  from biocontext_kb.core.ensembl import get_ensembl_id_from_gene_symbol
  
  
  @core_mcp.tool()
  def get_human_protein_atlas_info(
      gene_id: Annotated[Optional[str], Field(description="Ensembl gene ID (e.g., 'ENSG00000141510')")],
      gene_symbol: Annotated[Optional[str], Field(description="Gene symbol (e.g., 'TP53')")],
  ) -> dict:
      """Retrieve Human Protein Atlas information including expression, localization, and pathology data. Provide either gene_id or gene_symbol.
  
      Returns:
          dict: Protein atlas data with tissue_expression, subcellular_location, pathology, antibodies, RNA/protein levels or error message.
      """
      if gene_id is None and gene_symbol is None:
          return {"error": "At least one of gene_id or gene_symbol must be provided"}
  
      if gene_id is None:
          # If gene_id is not provided, fetch it using gene_symbol
          gene_id_response = get_ensembl_id_from_gene_symbol.fn(gene_symbol=gene_symbol, species="9606")
          if "ensembl_id" in gene_id_response:
              gene_id = gene_id_response["ensembl_id"]
          else:
              return {"error": "Failed to fetch Ensembl ID from gene name"}
  
      url = f"https://www.proteinatlas.org/{gene_id}.json"
  
      try:
          response = requests.get(url)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch Human Protein Atlas info: {e!s}"}

• src/biocontext_kb/core/proteinatlas/_get_human_protein_atlas_info.py:12-14 (schema)

  Input schema defined via Pydantic Field annotations: gene_id (Optional[str], Ensembl gene ID) and gene_symbol (Optional[str], gene symbol). Both are optional but at least one must be provided.

      gene_id: Annotated[Optional[str], Field(description="Ensembl gene ID (e.g., 'ENSG00000141510')")],
      gene_symbol: Annotated[Optional[str], Field(description="Gene symbol (e.g., 'TP53')")],
  ) -> dict:

• src/biocontext_kb/core/proteinatlas/_get_human_protein_atlas_info.py:10-10 (registration)

  Registration via @core_mcp.tool() decorator on the function, which registers it as an MCP tool on the 'core_mcp' FastMCP server instance.

  @core_mcp.tool()

• src/biocontext_kb/core/proteinatlas/__init__.py:1-5 (registration)

  Package-level __init__.py re-exports the function and registers it in __all__, and the core __init__.py (line 17) imports 'from .proteinatlas import *' to include this tool in the core MCP server.

  from ._get_human_protein_atlas_info import get_human_protein_atlas_info
  
  __all__ = [
      "get_human_protein_atlas_info",
  ]

• src/biocontext_kb/core/ensembl/_get_ensembl_id_from_gene_symbol.py:10-42 (helper)

  Helper function used by the Human Protein Atlas tool to resolve gene_symbol to an Ensembl gene ID (ENSG*) via the Ensembl REST API, when only a gene symbol is provided.

  @core_mcp.tool()
  def get_ensembl_id_from_gene_symbol(
      gene_symbol: Annotated[str, Field(description="Gene name (e.g., 'TP53')")],
      species: Annotated[
          str,
          Field(description="Taxonomy ID (e.g., 9606 for human, 10090 for mouse)"),
      ] = "9606",
  ) -> dict:
      """Get Ensembl gene ID from gene symbol. Returns the stable Ensembl ID (ENSG*) for the given gene symbol and species.
  
      Returns:
          dict: Ensembl gene ID in format {'ensembl_id': 'ENSG...'} or error message.
      """
      # Ensure at least one search parameter was provided
      if not gene_symbol:
          return {"error": "gene_symbol must be provided"}
  
      url = f"https://rest.ensembl.org/xrefs/symbol/{species}/{gene_symbol}"
  
      try:
          response = requests.get(url)
          response.raise_for_status()
  
          # Parse the Ensembl gene ID
          match = re.search(r"\b(ENSG\d+)\b", response.text)
  
          if match:
              return {"ensembl_id": match.group(1)}
          else:
              return {"error": "No Ensembl gene ID found in response"}
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch Ensembl ID: {e!s}"}