OLS MCP Server

Instructions

Implementation Reference

• src/ols_mcp_server/server.py:181-217 (handler)

  The core handler function for the 'get_term_children' tool. It queries the OLS API to retrieve direct children of a specified term IRI within an ontology, handles URL encoding, makes the HTTP request, formats the response as JSON, and includes error handling.

  @mcp.tool()
  async def get_term_children(
      term_iri: str,
      ontology: str,
      include_obsolete: bool = False,
      size: int = 20
  ) -> str:
      """Get direct children of a specific term.
      
      Args:
          term_iri: The IRI of the term
          ontology: The ontology identifier
          include_obsolete: Include obsolete entities
          size: Maximum number of results
      
      Returns:
          JSON formatted list of child terms
      """
      encoded_iri = url_encode_iri(term_iri)
      
      params: dict[str, Any] = {
          "page": 0,
          "size": size,
          "includeObsoleteEntities": include_obsolete
      }
      
      url = f"{OLS_BASE_URL}/api/v2/ontologies/{ontology}/classes/{encoded_iri}/children"
      
      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 getting term children: {str(e)}"

• src/ols_mcp_server/server.py:25-28 (helper)

  Helper function used by get_term_children to double URL-encode the term IRI for compatibility with the OLS API path requirements.

  def url_encode_iri(iri: str) -> str:
      """Double URL encode an IRI as required by OLS API."""
      return urllib.parse.quote(urllib.parse.quote(iri, safe=""), safe="")

• src/ols_mcp_server/server.py:30-66 (helper)

  Helper function used by get_term_children (and other tools) to format paginated OLS API responses into a readable 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)