BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/stringdb/_get_string_network_image.py:13-48 (handler)

  The primary handler function for the 'bc_get_string_network_image' tool. It uses inline Pydantic schema for input validation, fetches the STRING protein ID using a helper, constructs the API URL for the network image, retrieves and processes the PNG image, and returns it as an Image object or an error dictionary.

  @core_mcp.tool()
  def get_string_network_image(
      protein_symbol: Annotated[str, Field(description="Protein name to search for (e.g., 'TP53')")],
      species: Annotated[str, Field(description="Species taxonomy ID (e.g., '10090' for mouse)")],
      flavor: Annotated[
          str, Field(description="Network flavor (e.g., 'confidence', 'evidence', 'actions')")
      ] = "confidence",
      min_score: Annotated[int, Field(description="Minimum combined score threshold (0-1000)", ge=0, le=1000)] = 700,
  ) -> Image | dict:
      """Generate protein-protein interaction network image from STRING database. Always provide species parameter.
  
      Returns:
          Image or dict: Network visualization as PNG image object or error message.
      """
      # First resolve the protein name to a STRING ID
      try:
          string_id = get_string_id.fn(protein_symbol=protein_symbol, species=species)
  
          if not string_id or not isinstance(string_id, str):
              return {"error": f"No STRING ID found for protein: {protein_symbol}"}
  
          url = f"https://string-db.org/api/image/network?identifiers={string_id}&species={species}&required_score={min_score}&network_flavor={flavor}&format=png"
          response = requests.get(url)
          response.raise_for_status()
          img = PILImage.open(BytesIO(response.content))
  
          buffer = BytesIO()
          img.save(buffer, format="PNG")
          img_bytes = buffer.getvalue()
  
          return Image(data=img_bytes, format="png")
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch image: {e!s}"}
      except Exception as e:
          return {"error": f"An error occurred: {e!s}"}

• src/biocontext_kb/core/stringdb/_get_string_id.py:9-41 (helper)

  Helper tool 'get_string_id' (likely 'bc_get_string_id') called by the main handler to resolve the protein_symbol and species to a STRING database ID.

  @core_mcp.tool()
  def get_string_id(
      protein_symbol: Annotated[str, Field(description="Protein name or identifier (e.g., 'TP53')")],
      species: Annotated[str, Field(description="Species taxonomy ID (e.g., '9606' for human)")] = "",
      return_field: Annotated[str, Field(description="Field to return: 'stringId' or 'preferredName'")] = "stringId",
      limit: Annotated[int, Field(description="Maximum number of matches to return")] = 1,
  ) -> Union[dict, str]:
      """Map protein identifiers (gene names, synonyms, UniProt IDs) to STRING database IDs. Using STRING IDs improves reliability.
  
      Returns:
          str or dict: STRING ID string (e.g., '9606.ENSP00000269305') or dict with error message.
      """
      url = f"https://string-db.org/api/json/get_string_ids?identifiers={protein_symbol}&echo_query=1&limit={limit}"
  
      if species:
          url += f"&species={species}"
  
      try:
          response = requests.get(url)
          response.raise_for_status()
  
          data = response.json()
  
          if isinstance(data, dict) and "error" in data:
              return data
  
          if not data:
              return {"error": f"No STRING ID found for protein: {protein_symbol}"}
  
          return data[0].get(return_field)
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch STRING ID: {e!s}"}

• src/biocontext_kb/core/_server.py:1-7 (registration)

  Defines core_mcp FastMCP instance with name 'BC' (providing the 'bc_' prefix for tools) where all core tools including get_string_network_image are registered via @core_mcp.tool() decorators.

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

• src/biocontext_kb/app.py:35-40 (registration)

  Imports the core_mcp server (with 'BC' tools) into the main 'BioContextAI' FastMCP app using slugify('BC')='bc' as the prefix, making tools available as 'bc_*'.

  for mcp in [core_mcp, *(await get_openapi_mcps())]:
      await mcp_app.import_server(
          mcp,
          slugify(mcp.name),
      )
  logger.info("MCP server setup complete.")