StockSage AI MCP Server

README.md
## 🎯 **StockSage AI - MCP Server Complete Documentation (Updated)**

---

## 📊 **OVERVIEW**

**Purpose:** Standalone server providing tools for stock data, technical calculations, trading signals, and monitoring for short-term trading

**Data Sources:** yfinance (Primary - Free) + Multi-Provider Support (Future)

**Architecture:** Provider-Agnostic (Easy to switch/add providers)

**Total Tools:** 51

---

## 📦 **FOLDER STRUCTURE**

```
mcp-server/
│
├── server.py                          # Main entry point - starts MCP server
├── config.py                          # Configuration & provider settings
│
├── src/
│   ├── __init__.py                    # Main registry - imports all tools
│   │
│   ├── stock_data/                    # Category: Stock Data (10 tools)
│   │   ├── __init__.py
│   │   ├── get_all_stocks.py          # Data Source: yfinance (Provider)
│   │   ├── get_stock_info.py          # Data Source: yfinance (Provider)
│   │   ├── get_real_time_price.py     # Data Source: yfinance (Provider)
│   │   ├── get_quote.py               # Data Source: yfinance (Provider)
│   │   ├── get_batch_quotes.py        # Data Source: yfinance (Provider)
│   │   ├── get_historical_data.py     # Data Source: yfinance (Provider)
│   │   ├── get_market_status.py       # Data Source: yfinance (Provider)
│   │   ├── get_premarket_data.py      # Data Source: yfinance (Provider)
│   │   ├── get_afterhours_data.py     # Data Source: yfinance (Provider)
│   │   └── get_multiple_timeframes.py # Data Source: yfinance (Provider)
│   │
│   ├── technical/                     # Category: Technical Analysis (8 tools)
│   │   ├── __init__.py
│   │   ├── calculate_rsi.py           # Calculate from historical data
│   │   ├── calculate_macd.py          # Calculate from historical data
│   │   ├── calculate_ma.py            # Calculate from historical data
│   │   ├── calculate_volatility.py    # Calculate from historical data
│   │   ├── calculate_beta.py          # Calculate from historical data
│   │   ├── detect_trend.py            # Calculate from historical data
│   │   ├── detect_support_resistance.py # Calculate from historical data
│   │   └── analyze_volume.py          # Calculate from historical data
│   │
│   ├── trading/                       # Category: Trading Signals (6 tools)
│   │   ├── __init__.py
│   │   ├── generate_buy_signal.py     # Uses technical tools
│   │   ├── generate_sell_signal.py    # Uses technical tools
│   │   ├── suggest_entry.py           # Uses support/resistance
│   │   ├── suggest_exit.py            # Uses support/resistance
│   │   ├── suggest_stop_loss.py       # Uses support/volatility
│   │   └── calculate_risk_reward.py   # Uses entry/stop/target
│   │
│   ├── risk/                          # Category: Risk Management (4 tools)
│   │   ├── __init__.py
│   │   ├── assess_risk.py             # Uses volatility/beta/drawdown
│   │   ├── calculate_var.py           # Calculate from historical data
│   │   ├── calculate_drawdown.py      # Calculate from historical data
│   │   └── suggest_position.py        # Uses risk tools
│   │
│   ├── sentiment/                     # Category: Sentiment Analysis (4 tools)
│   │   ├── __init__.py
│   │   ├── get_news.py                # Data Source: yfinance
│   │   ├── analyze_sentiment.py       # Calculate from news data
│   │   ├── get_analyst_ratings.py     # Data Source: yfinance
│   │   └── detect_rating_changes.py   # Data Source: yfinance
│   │
│   ├── portfolio/                     # Category: Portfolio Management (6 tools)
│   │   ├── __init__.py
│   │   ├── get_portfolio_value.py     # Uses stock data tools
│   │   ├── calculate_portfolio_beta.py # Calculate from historical data
│   │   ├── detect_concentration.py    # Uses yfinance data
│   │   ├── track_positions.py         # Uses stock data tools
│   │   ├── calculate_pnl.py           # Uses stock data tools
│   │   └── suggest_rebalance.py       # Uses portfolio tools
│   │
│   ├── prediction/                    # Category: Price Prediction (4 tools)
│   │   ├── __init__.py
│   │   ├── predict_direction.py       # Calculate from historical data
│   │   ├── predict_target.py          # Calculate from historical data
│   │   ├── get_confidence.py          # Calculate from analysis
│   │   └── backtest.py                # Calculate from historical data
│   │
│   └── monitoring/                    # Category: Monitoring & Alerts (9 tools)
│       ├── __init__.py
│       ├── start_streaming.py         # WebSocket (Future: Alpaca)
│       ├── stop_streaming.py          # WebSocket (Future: Alpaca)
│       ├── get_stream_data.py         # Cache
│       ├── set_price_alert.py         # Database
│       ├── set_volume_alert.py        # Database
│       ├── set_pattern_alert.py       # Database
│       ├── check_alerts.py            # Database
│       ├── clear_alert.py             # Database
│       └── detect_anomalies.py        # Calculate from stream data
│
├── services/                          # Provider-Agnostic Services
│   ├── __init__.py
│   ├── provider_manager.py            # Routes to correct provider
│   │
│   ├── providers/
│   │   ├── __init__.py
│   │   ├── base_provider.py           # Provider interface
│   │   ├── yfinance_provider.py       # Current: yfinance (Free)
│   │   ├── alpaca_provider.py         # Future: Alpaca (Real-time)
│   │   └── finnhub_provider.py        # Future: Finnhub (News)
│   │
│   └── cache_service.py               # Redis cache management
│
└── utils/                             # Utility functions
    ├── __init__.py
    ├── calculations.py                # Financial calculations
    ├── indicators.py                  # Technical indicator formulas
    └── formatters.py                  # Data formatting helpers
```

---

## 📊 **COMPLETE TOOLS TABLE & IMPLEMENTATION STATUS**

---

## CATEGORY 1: STOCK DATA TOOLS (10 Tools)

| #   | Tool Name               | Data Source         | Description                                                                                                      | Status    |
| --- | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- | --------- |
| 1   | get_all_stocks          | yfinance (Provider) | Fetches complete list of all US stocks for dropdown. Users search and select stocks to get buy/sell suggestions. | ✅ **DONE**   |
| 2   | get_stock_info          | yfinance (Provider) | Gets company name, sector, industry, description. Helps user understand what company they're trading.            | ✅ **DONE**   |
| 3   | get_real_time_price     | yfinance (Provider) | Gets current stock price. Critical for short-term trading decisions.                                             | ✅ **DONE**   |
| 4   | get_quote               | yfinance (Provider) | Gets bid/ask prices and sizes. Used to determine spread and best execution price.                                | ✅ **DONE**   |
| 5   | get_batch_quotes        | yfinance (Provider) | Gets quotes for multiple stocks in one call. Used for watchlist display showing real-time prices.                | ✅ **DONE**   |
| 6   | get_historical_data     | yfinance (Provider) | Gets OHLCV historical data for technical analysis, pattern detection, and backtesting.                           | ✅ **DONE**   |
| 7   | get_market_status       | yfinance (Provider) | Checks if market is open or closed and current session.                                                          | ✅ **DONE**   |
| 8   | get_premarket_data      | yfinance (Provider) | Gets pre-market trading data for gap detection and early signals.                                                | ✅ **DONE**   |
| 9   | get_afterhours_data     | yfinance (Provider) | Gets after-hours trading data for overnight analysis.                                                            | ✅ **DONE**   |
| 10  | get_multiple_timeframes | yfinance (Provider) | Gets data across 1Min, 5Min, 15Min, 1Hour, 1Day timeframes for comprehensive analysis.                           | ✅ **DONE**   |

---

## CATEGORY 2: TECHNICAL TOOLS (8 Tools)

| #   | Tool Name                 | Data Source                    | Description                                                                        | Status      |
| --- | ------------------------- | ------------------------------ | ---------------------------------------------------------------------------------- | ----------- |
| 11  | calculate_rsi             | Calculate from historical data | Calculates RSI (0-100) to identify overbought (>70) and oversold (<30) conditions. | ✅ **DONE** |
| 12  | calculate_macd            | Calculate from historical data | Calculates MACD line, signal line, and histogram for trend detection.              | ✅ **DONE** |
| 13  | calculate_ma              | Calculate from historical data | Calculates moving averages (50-day, 200-day) for trend and golden/death cross.     | ✅ **DONE** |
| 14  | calculate_volatility      | Calculate from historical data | Calculates price volatility to determine risk level for position sizing.           | ✅ **DONE** |
| 15  | calculate_beta            | Calculate from historical data | Calculates stock beta to measure market sensitivity.                               | ✅ **DONE** |
| 16  | detect_trend              | Calculate from historical data | Detects trend direction (up/down/sideways) and strength.                           | ✅ **DONE** |
| 17  | detect_support_resistance | Calculate from historical data | Identifies support (entry) and resistance (exit) levels.                           | ✅ **DONE** |
| 18  | analyze_volume            | Calculate from historical data | Analyzes current volume vs average, detects unusual activity.                      | ✅ **DONE** |

---

## CATEGORY 3: TRADING TOOLS (6 Tools)

| #   | Tool Name             | Data Source                         | Description                                                                                                                          | Status      |
| --- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| 19  | generate_buy_signal   | Uses RSI, MACD, Trend, Volume tools | Checks all buy conditions (RSI < 30, MACD bullish, high volume, above support, uptrend) and generates buy recommendation with score. | ⏳ PENDING  |
| 20  | generate_sell_signal  | Uses RSI, MACD, Trend, Volume tools | Checks all sell conditions (RSI > 70, MACD bearish, declining volume, near resistance, downtrend) and generates sell recommendation. | ⏳ PENDING  |
| 21  | suggest_entry         | Uses Support/Resistance, RSI tools  | Calculates best entry price near support level for safety.                                                                           | ⏳ PENDING  |
| 22  | suggest_exit          | Uses Support/Resistance tools       | Calculates exit price at resistance level with multiple targets.                                                                     | ⏳ PENDING  |
| 23  | suggest_stop_loss     | Uses Support, Volatility tools      | Calculates stop-loss level below support to limit losses.                                                                            | ⏳ PENDING  |
| 24  | calculate_risk_reward | Uses Entry, Stop, Target            | Calculates risk/reward ratio. Minimum 1:2 required.                                                                                  | ⏳ PENDING  |

---

## CATEGORY 4: RISK TOOLS (4 Tools)

| #   | Tool Name          | Data Source                     | Description                                                                  | Status      |
| --- | ------------------ | ------------------------------- | ---------------------------------------------------------------------------- | ----------- |
| 25  | assess_risk        | Uses Volatility, Beta, Drawdown | Assesses overall risk level (Low/Medium/High) by analyzing multiple factors. | ⏳ PENDING  |
| 26  | calculate_var      | Calculate from historical data  | Calculates Value at Risk - maximum potential loss at confidence level.       | ⏳ PENDING  |
| 27  | calculate_drawdown | Calculate from historical data  | Calculates maximum drawdown from peak to trough.                             | ⏳ PENDING  |
| 28  | suggest_position   | Uses Risk tools                 | Suggests position size ensuring maximum 2% risk per trade.                   | ⏳ PENDING  |

---

## CATEGORY 5: SENTIMENT TOOLS (4 Tools)

| #   | Tool Name             | Data Source         | Description                                                   | Status      |
| --- | --------------------- | ------------------- | ------------------------------------------------------------- | ----------- |
| 29  | get_news              | yfinance            | Gets latest company news headlines for sentiment analysis.    | ✅ **DONE**     |
| 30  | analyze_sentiment     | Calculate from news | Analyzes news sentiment (positive/negative/neutral).          | ⏳ PENDING  |
| 31  | get_analyst_ratings   | yfinance            | Gets analyst buy/hold/sell recommendations and price targets. | ✅ **DONE**     |
| 32  | detect_rating_changes | yfinance            | Detects recent analyst upgrades and downgrades.               | ⏳ PENDING  |

---

## CATEGORY 6: PORTFOLIO TOOLS (6 Tools)

| #   | Tool Name                | Data Source                    | Description                                                 | Status      |
| --- | ------------------------ | ------------------------------ | ----------------------------------------------------------- | ----------- |
| 33  | get_portfolio_value      | Uses stock data tools          | Calculates total portfolio value with current prices.       | ⏳ PENDING  |
| 34  | calculate_portfolio_beta | Calculate from historical data | Calculates portfolio beta for overall risk.                 | ⏳ PENDING  |
| 35  | detect_concentration     | yfinance                       | Detects sector concentration in portfolio.                  | ⏳ PENDING  |
| 36  | track_positions          | Uses stock data tools          | Tracks open positions with entry prices and current values. | ⏳ PENDING  |
| 37  | calculate_pnl            | Uses stock data tools          | Calculates profit/loss for positions.                       | ⏳ PENDING  |
| 38  | suggest_rebalance        | Uses Portfolio tools           | Suggests portfolio rebalancing for diversification.         | ⏳ PENDING  |

---

## CATEGORY 7: PREDICTION TOOLS (4 Tools)

| #   | Tool Name         | Data Source                    | Description                                                          | Status      |
| --- | ----------------- | ------------------------------ | -------------------------------------------------------------------- | ----------- |
| 39  | predict_direction | Calculate from historical data | Predicts short-term price direction (up/down) using patterns and ML. | ⏳ PENDING  |
| 40  | predict_target    | Calculate from historical data | Predicts target price for short-term trading.                        | ⏳ PENDING  |
| 41  | get_confidence    | Calculate from analysis        | Returns confidence score for predictions.                            | ⏳ PENDING  |
| 42  | backtest          | Calculate from historical data | Backtests predictions to measure accuracy.                           | ⏳ PENDING  |

---

## CATEGORY 8: MONITORING TOOLS (9 Tools)

| #   | Tool Name         | Data Source           | Description                                 | Status      |
| --- | ----------------- | --------------------- | ------------------------------------------- | ----------- |
| 43  | start_streaming   | WebSocket (Provider)  | Starts real-time streaming for symbols.     | ⏳ PENDING  |
| 44  | stop_streaming    | WebSocket (Provider)  | Stops streaming and closes connection.      | ⏳ PENDING  |
| 45  | get_stream_data   | Cache                 | Gets latest cached real-time data.          | ⏳ PENDING  |
| 46  | set_price_alert   | Database              | Sets alert when price crosses target level. | ⏳ PENDING  |
| 47  | set_volume_alert  | Database              | Sets alert when volume exceeds threshold.   | ⏳ PENDING  |
| 48  | set_pattern_alert | Database              | Sets alert for chart patterns.              | ⏳ PENDING  |
| 49  | check_alerts      | Database              | Checks triggered alerts for notification.   | ⏳ PENDING  |
| 50  | clear_alert       | Database              | Clears triggered alert from active list.    | ⏳ PENDING  |
| 51  | detect_anomalies  | Calculate from stream | Detects price spikes and unusual volume.    | ⏳ PENDING  |

---

## 📊 **SUMMARY TABLE**

| Category   | Folder        | Total Tools  | Completed   | Pending     | Primary Data Source | Implementation Status |
| ---------- | ------------- | ------------ | ----------- | ----------- | ------------------- | --------------------- |
| Stock Data | stock_data/   | 10           | 10          | 0           | yfinance (Provider) | ✅ **100% COMPLETE**  |
| Technical  | technical/    | 8            | 8           | 0           | Calculate from data | ✅ **100% COMPLETE**  |
| Trading    | trading/      | 6            | 0           | 6           | Multiple tools      | ⏳ PENDING            |
| Risk       | risk/         | 4            | 0           | 4           | Calculate from data | ⏳ PENDING            |
| Sentiment  | sentiment/    | 4            | 2           | 2           | yfinance            | 🔄 **50% IN PROGRESS** |
| Portfolio  | portfolio/    | 6            | 0           | 6           | Multiple tools      | ⏳ PENDING            |
| Prediction | prediction/   | 4            | 0           | 4           | Calculate from data | ⏳ PENDING            |
| Monitoring | monitoring/   | 9            | 0           | 9           | Cache + Database    | ⏳ PENDING            |
| **Total**  | **8 folders** | **51 tools** | **20 DONE** | **31 PEND** |                     | **20/51 DONE**        |


---

## 📊 **PROVIDER ARCHITECTURE**

### **Current Provider: yfinance (Free, No API Key)**

```
PROVIDER_CONFIG = {
    "default": "yfinance",
    "features": {
        "stock_data": "yfinance",
        "historical_data": "yfinance",
        "fundamentals": "yfinance",
        "news": "yfinance",
        "streaming": None  # Future: Alpaca
    }
}
```

### **Future Providers (Easy to Add):**

| Provider     | Use Case              | API Key | Real-time         |
| ------------ | --------------------- | ------- | ----------------- |
| **yfinance** | Current - All data    | ❌ No   | ⚠️ Near real-time |
| **Alpaca**   | Real-time + Streaming | ✅ Yes  | ✅ 0-delay        |
| **Finnhub**  | News + Sentiment      | ✅ Yes  | ✅ 0-delay        |
| **Polygon**  | Real-time + Options   | ✅ Yes  | ✅ 0-delay        |

---

## ✅ **REQUIREMENT COVERAGE CONFIRMATION**

| StockSage AI Requirement         | Tools Used         | Covered? |
| -------------------------------- | ------------------ | -------- |
| Multi-Perspective Stock Analysis | Tools 1-32         | ✅ YES   |
| Technical Analysis               | Tools 11-18        | ✅ YES   |
| Fundamental Analysis             | Tools 2, 29-32     | ✅ YES   |
| Sentiment Analysis               | Tools 29-32        | ✅ YES   |
| Risk Assessment                  | Tools 14-15, 25-28 | ✅ YES   |
| Portfolio Risk Management        | Tools 33-38        | ✅ YES   |
| Market Trend Prediction          | Tools 39-42        | ✅ YES   |
| 24/7 Watchlist Monitoring        | Tools 43-51        | ✅ YES   |
| Buy/Sell Signals                 | Tools 19-24        | ✅ YES   |
| Entry/Exit/Stop Loss             | Tools 21-24        | ✅ YES   |
| Real-time Data                   | Tools 3-5, 43-45   | ✅ YES   |
| Alerts & Notifications           | Tools 46-51        | ✅ YES   |

---

## 🎯 **FINAL CONCLUSION**

**All 51 tools fully support StockSage AI with provider-agnostic architecture!**

- ✅ **Current:** yfinance (Free, No API Key)
- ✅ **Future:** Easy to add Alpaca, Finnhub, Polygon
- ✅ **Provider Manager:** Routes to correct provider
- ✅ **Config-Based:** Switch providers without code changes
- ✅ **All Requirements Covered:** 100%

**This is the complete updated MCP server documentation with provider-agnostic architecture!**
This server cannot be deployed
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Maintenance

ActivitySlowing
ResponsivenessNo issues
Resources

GitHub Repository
Need Help?
Related Servers