get_term_ancestors

Retrieve parent terms from biological ontologies using term IRI and ontology identifier to understand hierarchical relationships in OLS MCP Server.

Instructions

Get ancestor terms (parents) 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 ancestor terms

Input Schema

TableJSON Schema

Name	Required	Description	Default
`term_iri`	Yes
`ontology`	Yes
`include_obsolete`	No
`size`	No

Implementation Reference

src/ols_mcp_server/server.py:219-254 (handler)

The core handler function for the 'get_term_ancestors' tool. It is decorated with @mcp.tool() which also serves as registration. Queries the OLS API for ancestor terms of a given term IRI in a specific ontology, formats the response, and handles errors.

@mcp.tool()
async def get_term_ancestors(
    term_iri: str,
    ontology: str,
    include_obsolete: bool = False,
    size: int = 20
) -> str:
    """Get ancestor terms (parents) 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 ancestor 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}/ancestors"
    
    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 ancestors: {str(e)}"

src/ols_mcp_server/server.py:219-219 (registration)
Registration of the 'get_term_ancestors' tool using FastMCP's @mcp.tool() decorator.
```
@mcp.tool()
```

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

Helper function used by get_term_ancestors to format the API response into a readable JSON structure.

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:25-27 (helper)

Helper function used to double URL encode the term IRI for OLS API requests.

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="")

OLS MCP Server