bc_get_string_similarity_scores

Instructions

Implementation Reference

• src/biocontext_kb/core/stringdb/_get_string_similarity_scores.py:10-42 (handler)

  The main handler implementation for the 'bc_get_string_similarity_scores' tool. The function is decorated with @core_mcp.tool() which registers it as an MCP tool. It takes two protein symbols and optional species, resolves them to STRING IDs, and queries the STRING database for homology similarity scores (Smith-Waterman bit scores).

  @core_mcp.tool()
  def get_string_similarity_scores(
      protein_symbol: Annotated[str, Field(description="First protein symbol (e.g., 'TP53')")],
      protein_symbol_comparison: Annotated[str, Field(description="Second protein symbol (e.g., 'MKI67')")],
      species: Annotated[str, Field(description="Species taxonomy ID (e.g., '9606' for human)")] = "",
  ) -> Union[List[Dict[str, Any]], dict]:
      """Retrieve protein homology similarity scores from STRING database based on Smith-Waterman bit scores. Only scores above 50 reported.
  
      Returns:
          list or dict: Similarity scores array with stringId_A, stringId_B, bitscore or error message.
      """
      # Resolve both protein symbols to STRING IDs
      try:
          string_id1 = get_string_id.fn(protein_symbol=protein_symbol, species=species)
          string_id2 = get_string_id.fn(protein_symbol=protein_symbol_comparison, species=species)
  
          if not all(isinstance(string_id, str) for string_id in [string_id1, string_id2]):
              return {"error": "Could not extract STRING IDs"}
  
          identifiers = f"{string_id1}%0d{string_id2}"
  
          url = f"https://string-db.org/api/json/homology?identifiers={identifiers}"
          if species:
              url += f"&species={species}"
  
          response = requests.get(url)
          response.raise_for_status()
  
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch similarity scores: {e!s}"}
      except Exception as e:
          return {"error": f"An error occurred: {e!s}"}

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

  The FastMCP server instance 'core_mcp' is created here. The @core_mcp.tool() decorator in the handler file registers the tool with this server instance.

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

• src/biocontext_kb/core/stringdb/_get_string_similarity_scores.py:11-15 (schema)

  Pydantic Field annotations define the input schema: protein_symbol (str), protein_symbol_comparison (str), and species (str, optional). The return type is Union[List[Dict[str, Any]], dict].

  def get_string_similarity_scores(
      protein_symbol: Annotated[str, Field(description="First protein symbol (e.g., 'TP53')")],
      protein_symbol_comparison: Annotated[str, Field(description="Second protein symbol (e.g., 'MKI67')")],
      species: Annotated[str, Field(description="Species taxonomy ID (e.g., '9606' for human)")] = "",
  ) -> Union[List[Dict[str, Any]], dict]:

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

  Exports get_string_similarity_scores from the stringdb package module, making it accessible via import.

  from ._get_string_id import get_string_id
  from ._get_string_interactions import get_string_interactions
  from ._get_string_network_image import get_string_network_image
  from ._get_string_similarity_scores import get_string_similarity_scores
  
  __all__ = [
      "get_string_id",
      "get_string_interactions",
      "get_string_network_image",
      "get_string_similarity_scores",
  ]

• src/biocontext_kb/core/stringdb/_get_string_id.py:1-8 (helper)

  The get_string_id helper function that is called by get_string_similarity_scores to resolve protein symbols to STRING IDs before querying homology scores.

  from typing import Annotated, Union
  
  import requests
  from pydantic import Field
  
  from biocontext_kb.core._server import core_mcp