list_series
Browse and filter Bureau of Labor Statistics data series by category to identify relevant economic indicators like CPI and employment statistics for analysis.
Instructions
List available BLS data series with optional category filtering. Returns series metadata including titles, IDs, and categories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category (e.g., 'CPI', 'Employment'). Optional. | |
| limit | No | Maximum number of results to return (default: 50) |
Implementation Reference
- src/bls_mcp/tools/list_series.py:49-78 (handler)The execute method of ListSeriesTool, which validates input, calls the data provider's list_series method, and returns formatted results or errors.
async def execute(self, arguments: Dict[str, Any]) -> Dict[str, Any]: """Execute list_series tool.""" logger.info(f"Executing list_series with arguments: {arguments}") # Validate input try: input_data = ListSeriesInput(**arguments) except Exception as e: logger.error(f"Input validation failed: {e}") return {"error": f"Invalid input: {str(e)}"} # Validate limit is_valid, error_msg = validate_limit(input_data.limit) if not is_valid: return {"error": error_msg} # List series try: series_list = await self.data_provider.list_series( category=input_data.category, limit=input_data.limit ) logger.info(f"Successfully listed {len(series_list)} series") return { "series": series_list, "count": len(series_list), "category_filter": input_data.category, } except Exception as e: logger.error(f"Error listing series: {e}") return {"error": f"Failed to list series: {str(e)}"} - Pydantic BaseModel defining the input schema for the list_series tool, with optional category filter and limit.
class ListSeriesInput(BaseModel): """Input schema for list_series tool.""" category: Optional[str] = Field( default=None, description="Filter by category (e.g., 'CPI', 'Employment'). Optional.", ) limit: int = Field( default=50, description="Maximum number of results to return (default: 50)" ) - src/bls_mcp/server.py:47-52 (registration)Registration of all tools including list_series in the BLSMCPServer's tools dictionary, instantiated with the data provider.
self.tools = { "get_series": GetSeriesTool(self.data_provider), "list_series": ListSeriesTool(self.data_provider), "get_series_info": GetSeriesInfoTool(self.data_provider), "plot_series": PlotSeriesTool(self.data_provider), } - src/bls_mcp/data/mock_data.py:86-111 (helper)The MockDataProvider.list_series method that loads the series catalog from fixtures, filters by category if provided, applies the limit, and returns the list of series metadata.
async def list_series( self, category: str | None = None, limit: int = 50 ) -> list[dict[str, Any]]: """ List available series with optional filtering. Args: category: Optional category filter (e.g., 'CPI') limit: Maximum number of results Returns: List of series metadata dictionaries """ catalog = self._load_series_catalog() series_list = catalog["series"] # Filter by category if specified if category: series_list = [ s for s in series_list if s.get("category", "").upper() == category.upper() ] # Apply limit series_list = series_list[:limit] return list(series_list)