get_series
Fetch Bureau of Labor Statistics time series data by ID with date range filtering. Retrieve economic indicators like CPI and employment statistics with values, periods, and metadata.
Instructions
Fetch BLS data series by ID with optional date range filtering. Returns time series data points with values, periods, and metadata.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_year | No | End year for data range (optional) | |
| series_id | Yes | BLS series ID (e.g., 'CUUR0000SA0' for CPI All Items) | |
| start_year | No | Start year for data range (optional) |
Implementation Reference
- src/bls_mcp/tools/get_series.py:51-90 (handler)The async execute method in GetSeriesTool class implements the core logic for the 'get_series' tool: input validation using Pydantic and custom validators, data fetching from MockDataProvider, logging, and error handling.async def execute(self, arguments: Dict[str, Any]) -> Dict[str, Any]: """Execute get_series tool.""" logger.info(f"Executing get_series with arguments: {arguments}") # Validate input try: input_data = GetSeriesInput(**arguments) except Exception as e: logger.error(f"Input validation failed: {e}") return {"error": f"Invalid input: {str(e)}"} # Validate series ID format if not validate_series_id(input_data.series_id): return {"error": f"Invalid series ID format: {input_data.series_id}"} # Validate year range is_valid, error_msg = validate_year_range( input_data.start_year, input_data.end_year ) if not is_valid: return {"error": error_msg} # Fetch data try: result = await self.data_provider.get_series( series_id=input_data.series_id, start_year=input_data.start_year, end_year=input_data.end_year, ) logger.info( f"Successfully fetched {result['count']} data points for {input_data.series_id}" ) return result except ValueError as e: logger.warning(f"Series not found: {e}") return {"error": str(e)} except Exception as e: logger.error(f"Error fetching series: {e}") return {"error": f"Failed to fetch series: {str(e)}"}
- Pydantic BaseModel defining the input schema for the get_series tool, including series_id (required), and optional start_year and end_year with descriptions.class GetSeriesInput(BaseModel): """Input schema for get_series tool.""" series_id: str = Field( description="BLS series ID (e.g., 'CUUR0000SA0' for CPI All Items)" ) start_year: Optional[int] = Field( default=None, description="Start year for data range (optional)" ) end_year: Optional[int] = Field( default=None, description="End year for data range (optional)" )
- src/bls_mcp/server.py:47-52 (registration)The tools dictionary in BLSMCPServer __init__ registers the 'get_series' tool by instantiating GetSeriesTool and mapping it to the name 'get_series', which is later used in list_tools and call_tool handlers.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), }