README.md•10.9 kB
# MCP Hybrid Forecasting System
A professional-grade algorithmic trading system that combines advanced statistical models (ARIMA, ARIMA-GARCH) with machine learning (XGBoost) to generate stock trading signals with risk management and volatility analysis.
## Features
### Core Forecasting Models
- **ARIMA Time Series Forecasting**: Professional statistical models for trend prediction with parameter optimization
- **ARIMA-GARCH Model**: Volatility-aware forecasting for high-volatility and cryptocurrency stocks
- **XGBoost Hybrid Model**: Machine learning residual correction with 10+ technical indicators
- **Hierarchical Ensemble Model**: Advanced model combination for improved accuracy
### Risk Management & Analysis
- **Volatility Classification**: Automatic detection of high-volatility stocks with configurable thresholds
- **Confidence Scoring**: Risk-managed buy/sell/hold decisions with confidence levels
- **Portfolio Analysis**: Multi-portfolio comparison and analysis capabilities
- **Smart Caching**: Intelligent result caching to avoid duplicate processing
### MCP Server Integration
- **MCP Protocol Support**: Full Model Context Protocol server implementation
- **Trading Tools**: Analyze portfolios, compare strategies, find opportunities
- **Market Summary**: Real-time market analysis and signal generation
- **Natural Language Queries**: Find trading opportunities with intuitive queries
### Production Features
- **Comprehensive Error Handling**: Robust error handling and logging
- **Multi-Stock Support**: Portfolio-level signal generation
- **Configurable Portfolios**: Pre-configured portfolios (tech, defensive, emerging tech, etc.)
- **Flexible Output**: CSV exports, charts, and detailed reports
## Performance
- **R² Accuracy**: 0.71-0.96 across major stocks
- **Feature Engineering**: 10+ technical indicators including volume analysis, moving averages, momentum
- **Signal Quality**: Conservative risk-managed decisions with confidence scoring
- **Cache Performance**: 6-hour intelligent caching reduces redundant API calls
## Quick Start
### 1. Installation
```bash
# Clone the repository
git clone <repository-url>
cd mcp-hybrid-forecasting
# Create virtual environment
python3 -m venv hybr_fcst_venv
source hybr_fcst_venv/bin/activate # On Windows: hybr_fcst_venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
### 2. Basic Usage
#### Run Standard Analysis
```bash
# Analyze default portfolio
python enhanced_main.py
# Analyze specific portfolio
python enhanced_main.py --portfolio tech_focus
# Analyze custom tickers
python enhanced_main.py --tickers AAPL MSFT GOOGL
# Filter by signal type
python enhanced_main.py --portfolio large_cap --signal BUY
```
#### Run with ARIMA-GARCH for High Volatility Stocks
```bash
# Use pure volatility detection
python enhanced_main.py --portfolio lenny_golub --mode volatility
# Use config-based crypto detection
python enhanced_main.py --portfolio custom --mode config
```
#### MCP Server Mode
```bash
# Start MCP server for Claude integration
python mcp_trading_server.py
```
### 3. Configuration
Edit [config/trading_config.json](config/trading_config.json) to customize:
```json
{
"tickers": {
"default": ["AAPL", "MSFT", "GOOGL", "AMZN"],
"tech_focus": ["AAPL", "MSFT", "GOOGL", "NVDA", "META"],
"defensive": ["PG", "KO", "PEP", "WMT", "TGT", "CVS"]
},
"trading_parameters": {
"buy_threshold": 0.02,
"sell_threshold": -0.02,
"confidence_threshold": 0.6
},
"risk_management": {
"max_volatility": 0.05,
"min_confidence": 0.6
}
}
```
## Project Structure
```
mcp-hybrid-forecasting/
├── models/ # Forecasting models
│ ├── arima_model.py # ARIMA implementation with optimization
│ ├── arima_garch_model.py # ARIMA-GARCH for volatile stocks
│ ├── hybrid_model.py # XGBoost residual correction
│ └── hierarchical_ensemble_model.py # Ensemble modeling
├── config/ # Configuration files
│ ├── trading_config.json # Main trading configuration
│ └── extreme_volatility.json # Volatility classification
├── src/ # Source modules
│ ├── analysis/ # Analysis utilities
│ ├── data/ # Data fetching and processing
│ ├── trading/ # Trading logic
│ └── utils/ # Helper functions
├── cache/ # Model and data cache
├── results/ # Output results and reports
├── enhanced_main.py # Main trading system with dual model support
├── main.py # Core trading system
├── mcp_trading_server.py # MCP server implementation
└── requirements.txt # Python dependencies
```
## Available Portfolios
The system includes pre-configured portfolios in [config/trading_config.json](config/trading_config.json):
- **Technology**: `default`, `tech_focus`, `emerging_tech`, `large_cap`
- **Market Sectors**: `financials`, `healthcare`, `energy`, `utilities`, `industrials`
- **Investment Style**: `growth`, `defensive`, `cyclical`
- **Market Cap**: `mega_cap`, `large_cap`, `mid_cap`, `small_cap`
- **Crypto-Related**: `lenny_golub` (COIN, MSTR, HOOD, etc.)
- **Defense**: `defence`, `defence1`
## Command Line Options
```bash
python enhanced_main.py --help
Options:
--portfolio PORTFOLIO Portfolio name from config (default: 'default')
--tickers TICKER [...] Custom list of tickers (overrides portfolio)
--signal SIGNAL Filter by signal: BUY, SELL, HOLD
--min-confidence FLOAT Minimum confidence threshold (0.0-1.0)
--mode MODE Volatility detection mode: 'config' or 'volatility'
--cache-hours HOURS Cache validity in hours (default: 6)
--output-dir DIR Output directory for results
```
## MCP Server Tools
When running as an MCP server, the following tools are available:
1. **analyze_portfolio**: Analyze specific portfolio with optional filtering
2. **compare_portfolios**: Compare multiple portfolios with analysis
3. **find_opportunities**: Natural language queries for trading opportunities
4. **get_market_summary**: Overall market analysis and signal distribution
5. **refresh_data**: Clear cache and refresh market data
Example queries:
- "Find high confidence buy opportunities"
- "Show defensive stocks with positive signals"
- "Compare tech_focus vs defensive portfolios"
## Dependencies
### Core Requirements
- Python 3.8+
- pandas >= 2.0.0
- numpy >= 1.24.0
- yfinance >= 0.2.18
### Modeling
- scikit-learn >= 1.3.0
- xgboost >= 1.7.0
- statsmodels >= 0.14.0
- arch >= 5.0.0 (for GARCH models)
- pmdarima >= 2.0.4 (optional, for auto-ARIMA)
### Visualization
- matplotlib >= 3.7.0
- seaborn >= 0.12.0
- plotly >= 5.17.0
### Development
- pytest >= 7.4.0
- jupyter >= 1.0.0
- black >= 23.0.0
See [requirements.txt](requirements.txt) for complete list.
## Usage Examples
### Example 1: Analyze Technology Stocks
```bash
python enhanced_main.py --portfolio tech_focus --signal BUY --min-confidence 0.7
```
### Example 2: Compare Investment Strategies
```bash
python enhanced_main.py --portfolio growth
python enhanced_main.py --portfolio defensive
# Then compare results in results/ directory
```
### Example 3: High Volatility / Crypto Stocks
```bash
# Analyze crypto-related stocks with ARIMA-GARCH
python enhanced_main.py --portfolio lenny_golub --mode volatility
```
### Example 4: Custom Stock List
```bash
python enhanced_main.py --tickers AAPL MSFT GOOGL NVDA AMD --signal BUY
```
## Output Files
Results are saved in the `results/` directory:
- **CSV files**: `trading_signals_YYYYMMDD_HHMMSS.csv`
- **Charts**: Portfolio comparison charts (if enabled)
- **Logs**: Detailed execution logs with timestamps
## Model Details
### ARIMA Model
- Auto-optimization of (p,d,q) parameters
- Configurable order search space
- AIC-based model selection
- Handles non-stationary data with differencing
### ARIMA-GARCH Model
- Volatility modeling for high-risk stocks
- Conditional heteroskedasticity handling
- Automatic fallback to ARIMA if GARCH fails
- Optimized for cryptocurrency and volatile tech stocks
### XGBoost Hybrid
- Residual-based correction
- Technical indicators: RSI, MACD, Bollinger Bands
- Volume-weighted features
- Lag features and momentum indicators
## Risk Management
The system implements multiple risk controls:
- **Volatility filtering**: Excludes extremely volatile stocks
- **Confidence scoring**: Only recommends high-confidence signals
- **Threshold-based signals**: Configurable buy/sell thresholds
- **Position limits**: Maximum position size constraints
## Development
### Running Tests
```bash
pytest tests/
```
### Code Formatting
```bash
black .
flake8 .
```
### Adding New Portfolios
Edit [config/trading_config.json](config/trading_config.json):
```json
{
"tickers": {
"my_portfolio": ["TICK1", "TICK2", "TICK3"]
}
}
```
## Troubleshooting
### Common Issues
**Import Errors**
```bash
# Ensure virtual environment is activated
source hybr_fcst_venv/bin/activate
pip install -r requirements.txt
```
**Data Fetch Failures**
- Check internet connection
- Verify ticker symbols are valid
- yfinance API may have rate limits
**ARIMA-GARCH Not Available**
```bash
# Install arch library
pip install arch
```
**Cache Issues**
```bash
# Clear cache directory
rm -rf cache/*
```
## Performance Tips
1. **Use caching**: Default 6-hour cache reduces API calls
2. **Smaller portfolios**: Analyze fewer stocks for faster results
3. **Adjust cache duration**: `--cache-hours` parameter for your needs
4. **Pre-optimize ARIMA**: Use `preprocess_arima_params.py` for parameter tuning
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
This project is for educational and research purposes. See LICENSE file for details.
## Disclaimer
This software is for educational purposes only. It is not financial advice. Always do your own research and consult with a qualified financial advisor before making investment decisions. Past performance does not guarantee future results.
## Acknowledgments
- Built with [statsmodels](https://www.statsmodels.org/), [XGBoost](https://xgboost.readthedocs.io/), and [yfinance](https://github.com/ranaroussi/yfinance)
- MCP protocol by Anthropic
- Inspired by quantitative finance research and modern ML techniques
## Contact
For questions, issues, or contributions, please open an issue on GitHub.
---
**Version**: 1.0.0
**Last Updated**: June 2025