BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/alphafold/_get_alphafold_info_by_protein_symbol.py:15-48 (handler)

  The core handler function for the 'bc_get_alphafold_info_by_protein_symbol' tool. It resolves the protein symbol to a UniProt ID using another tool, then fetches AlphaFold structure predictions. Includes input schema via Pydantic Annotated Fields.

  @core_mcp.tool()
  def get_alphafold_info_by_protein_symbol(
      protein_symbol: Annotated[str, Field(description="Gene/protein name (e.g., 'SYNPO')")],
      species: Annotated[
          str,
          Field(description="Taxonomy ID (e.g., '9606' for human)"),
      ] = "9606",
  ) -> dict:
      """Query AlphaFold database using protein name. First converts protein symbol to UniProt ID, then fetches structure predictions.
  
      Returns:
          dict: AlphaFold prediction data including PDB/CIF file URLs, confidence scores, and metadata or error message.
      """
      # Get the UniProt Id from the protein_symbol
      try:
          uniprot_id = get_uniprot_id_by_protein_symbol.fn(protein_symbol, species)
  
          if uniprot_id:
              result = get_alphafold_info_by_uniprot_id(uniprot_id)
              if isinstance(result, dict) and "error" in result:
                  return {"error": result["error"]}
              elif isinstance(result, list) and len(result) > 0:
                  # If result is a list, return the first item
                  return result[0]
              elif isinstance(result, dict):
                  # If result is a dict, return it directly
                  return result
              else:
                  return {"error": "Unexpected result format from AlphaFold query"}
          else:
              return {"error": "No results found for the given protein name"}
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch AlphaFold info: {e!s}"}

• src/biocontext_kb/core/alphafold/_get_alphafold_info_by_uniprot_id.py:8-33 (helper)

  Helper function called by the handler to query AlphaFold API directly using UniProt ID.

  def get_alphafold_info_by_uniprot_id(
      uniprot_id: Annotated[str, Field(description="UniProt protein ID (e.g., 'P62258')")],
  ) -> dict:
      """Query AlphaFold database for protein structure data.
  
      Returns:
          dict: AlphaFold prediction data including PDB/CIF file URLs, confidence scores, and metadata or error message.
      """
      # Ensure the UniProt ID is in uppercase
      uniprot_id = uniprot_id.upper()
  
      # Validate the UniProt ID format
      if not re.match(r"^[A-Z0-9]{6}$", uniprot_id):
          return {"error": "Invalid UniProt ID format"}
  
      # Construct the URL for AlphaFold database query
      url = f"https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id}"
  
      try:
          # Make the request and get the response
          response = requests.get(url)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch AlphaFold info: {e!s}"}

• src/biocontext_kb/core/uniprot/_get_uniprot_id_by_protein_symbol.py:9-32 (helper)

  Helper tool called by the main handler (via .fn()) to resolve protein symbol and species to UniProt ID using UniProt REST API.

  @core_mcp.tool()
  def get_uniprot_id_by_protein_symbol(
      protein_symbol: Annotated[str, Field(description="Gene or protein name to search for (e.g., 'SYNPO')")],
      species: Annotated[
          str,
          Field(description="Organism taxonomy ID (e.g., '9606' for human)"),
      ] = "9606",
  ) -> str | None:
      """Retrieve UniProt accession ID from protein name and species. Returns the primary accession or None if not found.
  
      Returns:
          str or None: UniProt accession ID string (e.g., 'P04637') or None if not found.
      """
      url = f"https://rest.uniprot.org/uniprotkb/search?query=protein_name:{protein_symbol}+AND+organism_id:{species}&format=json"
  
      response = requests.get(url)
      response.raise_for_status()
      data = response.json()
  
      if data["results"]:
          return data["results"][0]["primaryAccession"]
  
      return None

• src/biocontext_kb/core/_server.py:3-6 (registration)

  The FastMCP server instance 'core_mcp' with prefix 'BC' to which all tools including 'bc_get_alphafold_info_by_protein_symbol' are registered via decorators.

  core_mcp = FastMCP(  # type: ignore
      "BC",
      instructions="Provides access to biomedical knowledge bases.",
  )