Chronulus MCP Server

Instructions

Implementation Reference

• src/chronulus_mcp/io.py:16-61 (handler)

  The handler function that executes the save_forecast tool: fetches the normalized forecast by prediction_id, rescales it using provided y_min/y_max/invert_scale, saves the rescaled data to CSV and the original text explanation to TXT, returns confirmation message.

  async def save_forecast(
      prediction_id: Annotated[str, Field(description="The prediction_id from a prediction result")],
      output_path: Annotated[str, Field(description="The path where the CSV file should be saved. Should end in .csv")],
      csv_name: Annotated[str, Field(description="The path where the CSV file should be saved. Should end in .csv")],
      txt_name: Annotated[str, Field(description="The name of the TXT file to be saved. Should end in .txt")],
      ctx: Context,
      y_min: Annotated[float, Field(default=0.0, description="The expected smallest value for the use case. E.g., for product sales, 0 would be the least possible value for sales.")],
      y_max: Annotated[float, Field(default=1.0, description="The expected largest value for the use case. E.g., for product sales, 0 would be the largest possible value would be given by the user or determined from this history of sales for the product in question or a similar product.")],
      invert_scale: Annotated[bool, Field(default=False, description="Set this flag to true if the scale of the new units will run in the opposite direction from the inputs.")],
  ) -> str:
      """Saves the forecast from a NormalizedForecaster agent to CSV and the explanation to TXT
  
      Args:
          prediction_id (str): The prediction_id for the prediction you would like to rescale as returned by the forecasting agent
          output_path (str): The path where the CSV and TXT file should be saved.
          csv_name (str): The name of the CSV file to be saved. Should end in .csv
          txt_name (str): The name of the TXT file to be saved. Should end in .txt
          ctx (Context): Context object providing access to MCP capabilities.
          y_min (float): The expected smallest value for the use case. E.g., for product sales, 0 would be the least possible value for sales.
          y_max (float): The expected largest value for the use case. E.g., for product sales, 0 would be the largest possible value would be given by the user or determined from this history of sales for the product in question or a similar product.
          invert_scale (bool): Set this flag to true if the scale of the new units will run in the opposite direction from the inputs.
  
  
      Returns:
          str: A message confirming the file was saved and its location
      """
      # Get normalized forecast and rescale it
      _ = await ctx.info(f"Fetching prediction data for {prediction_id}")
      normalized_forecast = NormalizedForecaster.get_prediction_static(prediction_id, verbose=False)
      rescaled_forecast = RescaledForecast.from_forecast(
          forecast=normalized_forecast,
          y_min=y_min,
          y_max=y_max,
          invert_scale=invert_scale
      )
  
      # Convert to pandas using built-in method
      df = rescaled_forecast.to_pandas()
  
      # Save to CSV
      df.to_csv(os.path.join(output_path, csv_name), index_label="ds")
  
      with open(os.path.join(output_path, txt_name), "w") as f:
          f.write(normalized_forecast.text)
  
      return f"Forecast saved successfully to {output_path}"

• src/chronulus_mcp/__init__.py:156-156 (registration)

  Registers the save_forecast function as an MCP tool with its description.

  mcp.add_tool(save_forecast, description=SAVE_FORECAST_DESCRIPTION)

• src/chronulus_mcp/__init__.py:132-150 (schema)

  Tool description providing usage instructions and parameter explanations, used in registration.

  SAVE_FORECAST_DESCRIPTION = """
  A tool that saves a Chronulus forecast from NormalizedForecaster to separate CSV and TXT files
  
  When to use this tool:
  - Use this tool when you need to save both the forecast data and its explanation to files
  - The forecast data will be saved as a CSV file for data analysis
  - The forecast explanation will be saved as a TXT file for reference
  - Both files will be saved in the same directory specified by output_path
  - This tool can also be used to directly save rescaled predictions without first calling the rescaling tool
  
  How to use this tool:
  - Provide the prediction_id from a previous forecast
  - Specify the output_path where both files should be saved
  - Provide csv_name for the forecast data file (must end in .csv)
  - Provide txt_name for the explanation file (must end in .txt)
  - Optionally provide y_min and y_max to rescale the predictions (defaults to 0)
  - Set invert_scale to True if the target units run in the opposite direction
  - The tool will provide status updates through the MCP context
  """

• src/chronulus_mcp/__init__.py:9-9 (registration)

  Imports the save_forecast function from io.py for use in this module.

  from .io import save_forecast, save_prediction_analysis_html