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)