get_temporal_coverage_tool

Check available years for World Bank datasets to ensure valid data retrieval by identifying temporal coverage before downloading.

Instructions

[STEP 2/3] Get available years for a specific dataset.

    CRITICAL: Always call this BEFORE retrieve_data to avoid errors.
    
    Workflow:
    1. search_datasets - Done ✓
    2. get_temporal_coverage (this tool) - Check what years are available
    3. retrieve_data - Use latest_year from this response
    
    Returns: start_year, end_year, latest_year, and full list of available years.
    Next step: Call retrieve_data with year=latest_year.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`indicator`	Yes
`database`	Yes

Implementation Reference

src/world_bank_mcp/server.py:410-423 (handler)

The MCP tool handler decorated with @server.tool(). This is the entry point for the 'get_temporal_coverage_tool' tool, which validates inputs via type hints and delegates execution to the core helper function.

def get_temporal_coverage_tool(indicator: str, database: str) -> dict[str, Any]:
    """[STEP 2/3] Get available years for a specific dataset.
    
    CRITICAL: Always call this BEFORE retrieve_data to avoid errors.
    
    Workflow:
    1. search_datasets - Done ✓
    2. get_temporal_coverage (this tool) - Check what years are available
    3. retrieve_data - Use latest_year from this response
    
    Returns: start_year, end_year, latest_year, and full list of available years.
    Next step: Call retrieve_data with year=latest_year.
    """
    return get_temporal_coverage(indicator, database)

src/world_bank_mcp/server.py:83-123 (helper)

Core helper function containing the actual API call to retrieve temporal coverage (start_year, end_year) from World Bank metadata endpoint for the specified indicator.

def get_temporal_coverage(indicator: str, database: str) -> dict[str, Any]:
    """Get available years for a dataset"""
    try:
        payload = {
            "query": f"&$filter=series_description/idno eq '{indicator}'"
        }
        
        response = requests.post(
            METADATA_ENDPOINT,
            json=payload,
            headers={"Content-Type": "application/json", "Accept": "application/json"},
            timeout=30
        )
        response.raise_for_status()
        
        metadata = response.json()
        values = metadata.get("value", [])
        
        if not values:
            return {"success": False, "error": "No metadata found"}
        
        series_desc = values[0].get("series_description", {})
        time_periods = series_desc.get("time_periods", [])
        
        if time_periods:
            period = time_periods[0]
            start_year = int(period.get("start", 0))
            end_year = int(period.get("end", 0))
            
            return {
                "success": True,
                "start_year": start_year,
                "end_year": end_year,
                "latest_year": end_year,
                "available_years": list(range(start_year, end_year + 1))
            }
        
        return {"success": False, "error": "No temporal data available"}
        
    except Exception as e:
        return {"success": False, "error": str(e)}

src/world_bank_mcp/server.py:410-410 (registration)
The @server.tool() decorator registers this function as an MCP tool named 'get_temporal_coverage_tool' in the FastMCP server.
```
def get_temporal_coverage_tool(indicator: str, database: str) -> dict[str, Any]:
```

World Bank Data360 MCP Server