search_terms
Search and retrieve biological and medical ontology terms using the OLS API. Specify queries, filter by ontology, and customize results for precise term matching and relevance.
Instructions
Search for terms across ontologies using the OLS search API.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exact_match | No | ||
| include_obsolete | No | ||
| ontology | No | ||
| query | Yes | ||
| rows | No |
Implementation Reference
- src/ols_mcp_server/server.py:68-108 (handler)The main handler function for the 'search_terms' tool. It constructs the API request to OLS search endpoint, handles the response (including legacy format transformation), formats it using format_response, and returns either formatted JSON string or error message. The input schema is defined via Annotated type hints.@mcp.tool() async def search_terms( query: Annotated[str, "Search query text"], ontology: Annotated[Optional[str], "Optional ontology ID to restrict search (e.g., 'efo', 'go', 'hp'); may be a list of IDs separated by commas"] = None, exact_match: Annotated[bool, "Whether to perform exact matching"] = False, include_obsolete: Annotated[bool, "Include obsolete terms in results"] = False, rows: Annotated[int, "Maximum number of results to return"] = 10 ) -> TermSearchResponse | str: """Search for terms across ontologies using the OLS search API.""" params = { "q": query, "rows": rows, "start": 0, "exact": exact_match, "obsoletes": include_obsolete } if ontology: params["ontology"] = ontology url = f"{OLS_BASE_URL}/api/search" try: response = await client.get(url, params=params) response.raise_for_status() data = response.json() if "response" in data and "docs" in data["response"]: # Transform legacy API format docs = data["response"]["docs"] result = { "elements": docs, "totalElements": data["response"].get("numFound", len(docs)) } return format_response(result, rows) return format_response(data, rows) except httpx.HTTPError as e: return f"Error searching terms: {str(e)}"
- src/ols_mcp_server/models.py:34-36 (schema)Pydantic model for the output type of search_terms tool, defining the structure of search results including total count and list of TermInfo objects. Inherits pagination fields from PagedResponse.class TermSearchResponse(PagedResponse): num_found: int = Field(0, description="Total number of terms found", alias="numFound") terms: list[TermInfo] = Field(..., description="List of terms matching the search criteria")
- src/ols_mcp_server/server.py:68-68 (registration)The @mcp.tool() decorator registers the search_terms function as an MCP tool with FastMCP.@mcp.tool()
- src/ols_mcp_server/server.py:30-66 (helper)Utility function used by search_terms (and other tools) to format paginated OLS API responses into a user-friendly JSON structure with limited items and truncated descriptions.def format_response(data: Any, max_items: int = 10) -> str: """Format API response data for display.""" if isinstance(data, dict): if "elements" in data: # Handle paginated response elements = data["elements"][:max_items] total = data.get("totalElements", len(elements)) result = [] for item in elements: if isinstance(item, dict): # Extract key fields for display label = item.get("label", "") iri = item.get("iri", "") description = item.get("description", []) if isinstance(description, list) and description: description = description[0] elif isinstance(description, list): description = "" result.append({ "label": label, "iri": iri, "description": description[:200] + "..." if len(str(description)) > 200 else description }) return json.dumps({ "items": result, "total_items": total, "showing": len(result) }, indent=2) else: # Single item response return json.dumps(data, indent=2) return json.dumps(data, indent=2)