BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/interpro/_get_protein_domains.py:9-93 (handler)

  Handler function decorated with @core_mcp.tool() implementing the logic to retrieve protein domains from InterPro API, including matches, architecture, and optional structure info. Tool name: 'get_protein_domains' (likely 'bc_get_protein_domains' under 'BC' MCP server).

  @core_mcp.tool()
  def get_protein_domains(
      protein_id: Annotated[
          str,
          Field(description="UniProt ID/accession (e.g., 'P04637' or 'CYC_HUMAN')"),
      ],
      source_db: Annotated[
          str,
          Field(description="Database source ('uniprot', 'reviewed', or 'unreviewed')"),
      ] = "uniprot",
      include_structure_info: Annotated[
          bool,
          Field(description="Include structural information"),
      ] = False,
      species_filter: Annotated[
          Optional[str],
          Field(description="Taxonomy ID filter (e.g., '9606' for human)"),
      ] = None,
  ) -> dict:
      """Get protein domain architecture and InterPro matches. Returns all InterPro domains, functional sites, and domain architecture.
  
      Returns:
          dict: Protein metadata with interpro_matches array, interpro_match_count, domain_architecture, optionally structure data or error message.
      """
      base_url = f"https://www.ebi.ac.uk/interpro/api/protein/{source_db}/{protein_id}"
  
      # Build query parameters
      params = {}
      extra_fields = ["description", "sequence"]
  
      if include_structure_info:
          extra_fields.append("structure")
  
      if species_filter:
          params["tax_id"] = species_filter
  
      params["extra_fields"] = ",".join(extra_fields)
  
      try:
          # Get protein information with InterPro matches
          response = requests.get(base_url, params=params)
          response.raise_for_status()
  
          protein_data = response.json()
  
          if not protein_data.get("metadata"):
              return {"error": f"No data found for protein {protein_id}"}
  
          result = protein_data["metadata"]
  
          # Get InterPro domain matches for this protein
          try:
              domains_url = f"https://www.ebi.ac.uk/interpro/api/entry/interpro/protein/{source_db}/{protein_id}"
              domains_response = requests.get(domains_url)
  
              if domains_response.status_code == 200:
                  domains_data = domains_response.json()
                  result["interpro_matches"] = domains_data.get("results", [])
                  result["interpro_match_count"] = len(domains_data.get("results", []))
              else:
                  result["interpro_matches"] = []
                  result["interpro_match_count"] = 0
  
          except Exception as e:
              result["interpro_matches"] = {"error": f"Could not fetch InterPro matches: {e}"}
  
          # Get domain architecture ID (IDA) if available
          try:
              ida_url = f"{base_url}?ida"
              ida_response = requests.get(ida_url)
              if ida_response.status_code == 200:
                  ida_data = ida_response.json()
                  if ida_data.get("metadata", {}).get("ida"):
                      result["domain_architecture"] = ida_data["metadata"]["ida"]
          except Exception:
              pass  # IDA is optional
  
          return result
  
      except requests.exceptions.HTTPError as e:
          if e.response.status_code == 404:
              return {"error": f"Protein {protein_id} not found in {source_db}"}
          return {"error": f"HTTP error: {e}"}
      except Exception as e:
          return {"error": f"Exception occurred: {e!s}"}

• src/biocontext_kb/core/interpro/_get_protein_domains.py:10-27 (schema)

  Input schema defined using Pydantic Annotated types and Field descriptions for the tool parameters.

  def get_protein_domains(
      protein_id: Annotated[
          str,
          Field(description="UniProt ID/accession (e.g., 'P04637' or 'CYC_HUMAN')"),
      ],
      source_db: Annotated[
          str,
          Field(description="Database source ('uniprot', 'reviewed', or 'unreviewed')"),
      ] = "uniprot",
      include_structure_info: Annotated[
          bool,
          Field(description="Include structural information"),
      ] = False,
      species_filter: Annotated[
          Optional[str],
          Field(description="Taxonomy ID filter (e.g., '9606' for human)"),
      ] = None,
  ) -> dict:

• src/biocontext_kb/core/interpro/__init__.py:2-2 (registration)

  Imports the get_protein_domains function, triggering its registration via the @tool decorator when the module is imported.

  from ._get_protein_domains import get_protein_domains

• src/biocontext_kb/core/__init__.py:11-11 (registration)

  Imports all interpro tools, including get_protein_domains, into the core namespace for registration on core_mcp.

  from .interpro import *