BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/reactome/__init__.py:9-140 (handler)

  The main handler function for the tool. It is decorated with @core_mcp.tool() and implements the logic to query the Reactome API's identifier endpoint for pathways associated with the given identifier, with extensive parameter support for filtering and pagination.

  @core_mcp.tool()
  def get_reactome_info_by_identifier(
      identifier: Annotated[str, Field(description="The identifier of the element to be retrieved")],
      base_url: Annotated[
          str, Field(description="Base URL for the Reactome API")
      ] = "https://reactome.org/AnalysisService",
      interactors: Annotated[bool, Field(description="Include interactors")] = False,
      species: Annotated[
          Optional[Union[str, List[str]]],
          Field(description="List of species to filter the result (accepts taxonomy ids, species names and dbId)"),
      ] = None,
      page_size: Annotated[int, Field(description="Pathways per page", ge=1)] = 20,
      page: Annotated[int, Field(description="Page number", ge=1)] = 1,
      sort_by: Annotated[
          str,
          Field(description="Field to sort results by (e.g., 'ENTITIES_PVALUE', 'ENTITIES_FDR')"),
      ] = "ENTITIES_PVALUE",
      order: Annotated[str, Field(description="Sort order ('ASC' or 'DESC')")] = "ASC",
      resource: Annotated[
          str,
          Field(description="Resource to filter by (TOTAL includes all molecule types)"),
      ] = "TOTAL",
      p_value: Annotated[
          float,
          Field(
              description="P-value threshold (only pathways with p-value <= threshold will be returned)",
              ge=0,
              le=1,
          ),
      ] = 1.0,
      include_disease: Annotated[bool, Field(description="Set to False to exclude disease pathways")] = True,
      min_entities: Annotated[
          Optional[int],
          Field(description="Minimum number of contained entities per pathway"),
      ] = None,
      max_entities: Annotated[
          Optional[int],
          Field(description="Maximum number of contained entities per pathway"),
      ] = None,
      importable_only: Annotated[bool, Field(description="Filter to only include importable resources")] = False,
      timeout: Annotated[int, Field(description="Request timeout in seconds", ge=1)] = 30,
  ) -> Dict[str, Any]:
      """Query the Reactome API identifier endpoint.
  
      Use this endpoint to retrieve pathways associated with a given identifier.
      Always provide the species parameter to ensure the correct protein is returned.
  
      Args:
          identifier (str): The identifier of the element to be retrieved
          base_url (str): Base URL for the Reactome API
          interactors (bool): Include interactors
          species (str or list): List of species to filter the result (accepts taxonomy ids, species names and dbId)
          page_size (int): Pathways per page
          page (int): Page number
          sort_by (str): Field to sort results by (e.g., "ENTITIES_PVALUE", "ENTITIES_FDR")
          order (str): Sort order ("ASC" or "DESC")
          resource (str): Resource to filter by (TOTAL includes all molecule types)
          p_value (float): P-value threshold (only pathways with p-value <= threshold will be returned)
          include_disease (bool): Set to False to exclude disease pathways
          min_entities (int): Minimum number of contained entities per pathway
          max_entities (int): Maximum number of contained entities per pathway
          importable_only (bool): Filter to only include importable resources
          timeout (int): Request timeout in seconds
  
      Returns:
          dict: API response data or error information
      """
      # Input validation
      if not identifier:
          return {"error": "Identifier cannot be empty"}
  
      if order not in ["ASC", "DESC"]:
          return {"error": "Order must be either 'ASC' or 'DESC'"}
  
      if p_value < 0 or p_value > 1:
          return {"error": "P-value must be between 0 and 1"}
  
      # Build endpoint URL
      endpoint = f"{base_url.rstrip('/')}/identifier/{identifier}"
  
      # Prepare parameters
      params: dict[str, Union[str, int, float]] = {
          "interactors": str(interactors).lower(),
          "pageSize": page_size,
          "page": page,
          "sortBy": sort_by,
          "order": order,
          "resource": resource,
          "pValue": p_value,
          "includeDisease": str(include_disease).lower(),
          "importableOnly": str(importable_only).lower(),
      }
  
      # Add optional parameters if provided
      if species:
          if isinstance(species, list):
              params["species"] = ",".join(str(s) for s in species)
          else:
              params["species"] = species
  
      if min_entities is not None:
          params["min"] = min_entities
  
      if max_entities is not None:
          params["max"] = max_entities
  
      try:
          # Make the request
          response = requests.get(endpoint, params=params, timeout=timeout)
  
          # Return the JSON response if successful
          if response.status_code == 200:
              return response.json()
          elif response.status_code == 404:
              return {"error": f"Identifier '{identifier}' not found"}
          elif response.status_code == 400:
              return {"error": f"Invalid parameters: {response.text}"}
          else:
              return {
                  "error": f"HTTP error occurred: {response.status_code}",
                  "details": response.text,
              }
  
      except requests.exceptions.ConnectionError as conn_err:
          return {"error": f"Connection error: {conn_err!s}"}
      except requests.exceptions.Timeout:
          return {"error": f"Request timed out after {timeout} seconds"}
      except requests.exceptions.RequestException as req_err:
          return {"error": f"Request error: {req_err!s}"}
      except Exception as err:
          return {"error": f"Unexpected error: {err!s}"}

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

  Imports all from reactome module, which triggers the registration of the get_reactome_info_by_identifier tool into core_mcp via its @tool decorator.

  from .reactome import *

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

  Imports the core_mcp (named 'BC') into the main mcp_app with slugified prefix 'bc', effectively registering all core tools with 'bc_' prefix, e.g., 'bc_get_reactome_info_by_identifier'.

  for mcp in [core_mcp, *(await get_openapi_mcps())]:
      await mcp_app.import_server(
          mcp,
          slugify(mcp.name),
      )

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

  Defines the core_mcp FastMCP server instance named 'BC', into which individual tools are registered via decorators.

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