OLS MCP Server

Instructions

Implementation Reference

• src/ols_mcp_server/server.py:127-152 (handler)

  The handler function for the 'search_ontologies' tool. Decorated with @mcp.tool() for automatic registration. Handles input parameters, makes HTTP request to OLS API (/api/v2/ontologies), processes response, and returns formatted JSON or error string.
  @mcp.tool() async def search_ontologies( search: Annotated[Optional[str], "Optional search query to filter ontologies"] = None, page: Annotated[int, "Page number for pagination (default: 0)"] = 0, size: Annotated[int, "Number of results per page (default: 20)"] = 20, ) -> list[OntologySearchResponse] | str: """Search for available ontologies.""" params: dict[str, Any] = { "page": page, "size": size } if search: params["search"] = search url = f"{OLS_BASE_URL}/api/v2/ontologies" try: response = await client.get(url, params=params) response.raise_for_status() data = response.json() return format_response(data, size) except httpx.HTTPError as e: return f"Error searching ontologies: {str(e)}"
• src/ols_mcp_server/models.py:4-24 (schema)

  Pydantic models defining the structure for ontology search response: OntologyInfo, PagedResponse base class, and OntologySearchResponse used in the tool's return type annotation.
  class OntologyInfo(BaseModel): id: str = Field(..., description="Unique identifier for the ontology", alias="ontologyId") title: str = Field(..., description="Name of the ontology") version: Optional[str] = Field(None, description="Version of the ontology") description: Optional[str] = Field(None, description="Description of the ontology") domain: Optional[str] = Field(None, description="Domain of the ontology") homepage: Optional[HttpUrl] = Field(None, description="URL for the ontology") preferred_prefix: Optional[str] = Field(None, description="Preferred prefix for the ontology", alias="preferredPrefix") number_of_terms: Optional[int] = Field(None, description="Number of terms in the ontology") number_of_classes: Optional[int] = Field(None, description="Number of classes in the ontology", alias="numberOfClasses") repository: Optional[HttpUrl] = Field(None, description="Repository URL for the ontology") 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") class OntologySearchResponse(PagedResponse): ontologies: list[OntologyInfo] = Field(..., description="List of ontologies matching the search criteria")
• src/ols_mcp_server/server.py:30-66 (helper)

  Helper function used by search_ontologies (and other tools) to format paginated OLS API responses into a standardized JSON structure for tool output.
  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)
• src/ols_mcp_server/server.py:127-127 (registration)

  The @mcp.tool() decorator registers the search_ontologies function as an MCP tool with FastMCP.
  @mcp.tool()