OLS MCP Server

Instructions

Implementation Reference

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

  The main handler function decorated with @mcp.tool() that implements the search_ontologies tool logic, querying the OLS v2 API and formatting the response.

  @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 structured output type (OntologySearchResponse) used by the search_ontologies tool handler.

  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)

  Utility function used by search_ontologies (and other tools) to format paginated OLS API responses into readable JSON.

  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)