OLS MCP Server

Instructions

Implementation Reference

• src/ols_mcp_server/server.py:68-108 (handler)

  The main handler function for the 'search_terms' tool, decorated with @mcp.tool() which also serves as registration. It performs search queries against the OLS API and formats the response.
  @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 defining the structured output schema for the search_terms tool response.
  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/models.py:16-21 (schema)

  Base Pydantic model for paginated responses, inherited by TermSearchResponse.
  class PagedResponse(BaseModel): total_elements: int = Field(0, description="Total number of items", alias="totalElements") page: int = Field(0, description="Current page number") size: int = Field(20, description="Starting index of the current page", alias="numElements") total_pages: int = Field(0, description="Total number of pages", alias="totalPages")
• src/ols_mcp_server/models.py:26-33 (schema)

  Pydantic model for individual term information used in TermSearchResponse.
  class TermInfo(BaseModel): iri: HttpUrl = Field(..., description="IRI of the term") ontology_name: str = Field(..., description="Name of the ontology containing the term") short_form: str = Field(..., description="Short form identifier for the term") label: str = Field(..., description="Human-readable label for the term") obo_id: Optional[str] = Field(None, description="OBOLibrary ID for the term", alias="oboId") is_obsolete: Optional[bool] = Field(False, description="Indicates if the term is obsolete")
• src/ols_mcp_server/server.py:30-66 (helper)

  Helper function used by search_terms to format and truncate API responses for display.
  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)