BLS MCP Server

Instructions

Implementation Reference

• src/bls_mcp/tools/get_series_info.py:21-71 (handler)

  GetSeriesInfoTool class: implements the core logic for the get_series_info tool, including name, description, input_schema properties, and the async execute method that handles input validation and delegates to data provider.

  class GetSeriesInfoTool(BaseTool):
      """Tool for getting BLS series metadata."""
  
      def __init__(self, data_provider: MockDataProvider) -> None:
          """Initialize tool with data provider."""
          self.data_provider = data_provider
  
      @property
      def name(self) -> str:
          return "get_series_info"
  
      @property
      def description(self) -> str:
          return (
              "Get detailed metadata information about a specific BLS series. "
              "Returns series title, description, category, and data availability."
          )
  
      @property
      def input_schema(self) -> type[BaseModel]:
          return GetSeriesInfoInput
  
      async def execute(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
          """Execute get_series_info tool."""
          logger.info(f"Executing get_series_info with arguments: {arguments}")
  
          # Validate input
          try:
              input_data = GetSeriesInfoInput(**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}"}
  
          # Get series info
          try:
              info = await self.data_provider.get_series_info(
                  series_id=input_data.series_id
              )
              logger.info(f"Successfully retrieved info for {input_data.series_id}")
              return info
          except ValueError as e:
              logger.warning(f"Series not found: {e}")
              return {"error": str(e)}
          except Exception as e:
              logger.error(f"Error getting series info: {e}")
              return {"error": f"Failed to get series info: {str(e)}"}

• src/bls_mcp/tools/get_series_info.py:15-19 (schema)

  Pydantic BaseModel defining the input schema: requires a 'series_id' string field.

  class GetSeriesInfoInput(BaseModel):
      """Input schema for get_series_info tool."""
  
      series_id: str = Field(description="BLS series ID (e.g., 'CUUR0000SA0')")

• src/bls_mcp/server.py:47-52 (registration)

  Tool registration: GetSeriesInfoTool instance added to the server's tools dictionary under the key 'get_series_info'.

  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:113-143 (helper)

  MockDataProvider.get_series_info: supporting method that loads series metadata from JSON fixtures and augments with data availability info.

  async def get_series_info(self, series_id: str) -> dict[str, Any]:
      """
      Get metadata information about a specific series.
  
      Args:
          series_id: BLS series ID
  
      Returns:
          Dictionary with series metadata
  
      Raises:
          ValueError: If series not found
      """
      catalog = self._load_series_catalog()
  
      for series in catalog["series"]:
          if series["series_id"] == series_id:
              # Get data point count
              historical = self._load_historical_data()
              data_count = 0
              if series_id in historical:
                  data_count = len(historical[series_id]["data"])
  
              return {
                  **series,
                  "data_point_count": data_count,
                  "available_data": series_id in historical,
              }
  
      raise ValueError(f"Series '{series_id}' not found")