MCP Servers

Setup and Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd mcp-sales-forecasting
   

2. Create a Python virtual environment and activate it:

   python -m venv .venv
   # On Windows:
   # .\.venv\Scripts\activate
   # On macOS/Linux:
   # source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. API Key for Visual Crossing:

   • Sign up for a free API key at Visual Crossing Weather.
   • Open the ui.py file and replace the placeholder VC_API_KEY = "YOUR_API_KEY_HERE" with your actual Visual Crossing API key.

     # Inside ui.py (and potentially src/forecasting/model.py if you run its test block)
     VC_API_KEY = "YOUR_ACTUAL_VISUAL_CROSSING_API_KEY"
     

   • Important: Do not commit your actual API key to a public repository. For sharing, it's better to instruct users to add their own.

5. Data Setup:

   • Sales Data: Download the train.csv file from Kaggle's Store Item Demand Forecasting Challenge (or provide a direct link if not including it in the repo) and place it in the data/ folder. The agent is currently configured to use data for Store 1, Item 1.
   • Historical Weather Data: This project was trained using historical daily temperature data for Basel, CH, covering the period 2013-01-01 to 2017-05-31. You will need to obtain a similar CSV file. For demonstration, the src/forecasting/model.py file expects a CSV file at the path defined by HISTORICAL_WEATHER_CSV_PATH (e.g., data/Geçmiş Hava Durumu Verileri May 30 2025.csv - rename this to something like basel_weather_2013_2017.csv).
     • Ensure your CSV contains at least 'timestamp' (format e.g., YYYYMMDDTHHMMSS) and 'temperature' columns. The load_historical_weather_from_csv function in model.py will process this into daily min/mean/max temperatures.
     • Update HISTORICAL_WEATHER_CSV_PATH and HISTORICAL_WEATHER_COLUMN_MAP (if column names are different) in src/forecasting/model.py if your CSV file name or structure differs.

How to Run

1. Train the Model (if no model file exists or you want to re-train): The Streamlit UI will attempt to load a pre-trained model. If you need to train the model for the first time or re-train it (e.g., after changing historical data), ensure your historical weather CSV is correctly set up and then run:

   python -m src.forecasting.model
   

   This will train the model using the data in data/ and save it to models/sales_prophet_model_basel_temp.json. (The if __name__ == '__main__' block in model.py is set to delete any existing model file and retrain).

2. Run the Streamlit Web UI:

   streamlit run ui.py
   

   This will open the application in your web browser (usually at http://localhost:8501).

Project Logic Overview

• Historical Data Processing:
  • Sales data is loaded via sales_data_server.py.
  • Historical weather data (Basel temperatures) is loaded from a local CSV and processed into daily min/mean/max values by load_historical_weather_from_csv in model.py.
• Model Training (model.py):
  • Historical sales and processed historical weather are merged.
  • A Prophet model is trained with temperature metrics as external regressors.
  • The trained model is saved.
• Prediction (ui.py via model.py):
  • The user specifies the number of future days for forecasting.
  • weather_server.py fetches future weather forecasts from the Visual Crossing API for the requested period.
  • The pre-trained Prophet model is loaded.
  • make_sales_forecast in model.py uses the model and the future weather data (as regressors) to generate sales predictions.
  • Results are displayed in the Streamlit UI.

(Optional) Future Enhancements

• Implement more sophisticated methods for handling API rate limits for historical data.
• Add more diverse weather regressors (precipitation, wind, humidity, specific weather event flags).
• Incorporate holiday effects directly into the Prophet model.
• Perform rigorous model evaluation and hyperparameter tuning.
• Deploy as a more formal API (e.g., using the Flask app prototyped earlier).
• Develop a more autonomous agent that runs daily and stores/reports predictions.