bc_get_string_id
Convert protein identifiers or gene names to STRING database IDs for reliable API interactions. Specify protein symbols and optional species taxonomy to retrieve accurate STRING IDs or preferred names.
Instructions
Map a protein identifier to STRING database IDs.
This function helps resolve common gene names, synonyms, or UniProt identifiers to the STRING-specific identifiers. Using STRING IDs in subsequent API calls improves reliability and performance.
Args:
protein_symbol (str): The name of the protein to search for (e.g., "TP53").
species (str): The species taxonomy ID (e.g., "9606" for human). Optional.
return_field (str): The field to return. Either stringId or preferredName (default: stringId).
limit (int): Limit the number of matches returned per query (default: 1).
Returns: str: The STRING ID or preferred name if found, otherwise an error message.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Limit the number of matches returned | |
| protein_symbol | Yes | The name of the protein to search for (e.g., 'TP53') | |
| return_field | No | Which field to return. Either `stringId` (default) or `preferredName`. | stringId |
| species | No | The species taxonomy ID (e.g., '9606' for human) |
Implementation Reference
- The handler function for the 'get_string_id' tool (prefixed to 'bc_get_string_id'), decorated with @core_mcp.tool(). It queries the STRING-DB API to map a protein symbol to a STRING 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/app.py:35-39 (registration)Registers the core_mcp server (including get_string_id tool) into the main MCP app under the slugified prefix 'bc' (from core_mcp.name='BC'), making the tool available as 'bc_get_string_id'.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 instance named 'BC', where tools like get_string_id are registered via @core_mcp.tool() decorators.core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )
- Pydantic schema defined via Annotated parameters and Field descriptions for input validation of the bc_get_string_id 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}"}
- Imports and exports the get_string_id tool for use within the stringdb module.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",