Enhanced MCP Stock Query System

# Enhanced MCP Stock Query System An intelligent, production-ready stock data retrieval system built on the Model Context Protocol (MCP) that combines AI-powered query understanding with reliable financial data access. The system uses Google's Gemini AI to interpret natural language queries and automatically selects the appropriate tools to fetch comprehensive stock market information. ## 🚀 Features ### Core Functionality - 🤖 **AI-Powered Query Understanding**: Uses Google Gemini to interpret natural language stock queries - 📊 **Dual Data Sources**: Primary Yahoo Finance API with CSV fallback for reliability - 🔄 **Automatic Tool Selection**: Intelligent mapping of user queries to appropriate stock tools - 💬 **Interactive Chat Interface**: Enhanced command-line interface with error handling - 🛡️ **Robust Error Handling**: Comprehensive fallback mechanisms and error recovery - ⚡ **Asynchronous Processing**: High-performance async operations for better responsiveness ### Enhanced MCP Features - 📋 **MCP Resources**: Exposes stock data and market information as discoverable resources - 🎯 **MCP Prompts**: Pre-built prompt templates for stock analysis and comparisons - 🔧 **Enhanced Tools**: Improved tools with better validation and error handling - 📈 **Market Summary**: New tool for getting overview of key market data ### Production-Ready Improvements - 🏗️ **Type Safety**: Comprehensive type hints throughout the codebase - 📝 **Comprehensive Logging**: Structured logging for debugging and monitoring - ⚙️ **Configuration Management**: Environment-based configuration with validation - 🧪 **Testing Suite**: Unit tests for core functionality - 🔒 **Input Validation**: Sanitization and validation of all user inputs - 🔄 **Retry Logic**: Automatic retry with exponential backoff for failed operations ## 📋 Available Tools ### `get_stock_price` - **Purpose**: Retrieve current stock price for a single symbol - **Parameters**: `symbol` (string): Stock ticker symbol (e.g., "AAPL", "MSFT") - **Enhanced Features**: Input validation, detailed error messages, data source indication ### `compare_stocks` - **Purpose**: Compare prices between two stock symbols with percentage differences - **Parameters**: - `symbol1` (string): First stock ticker symbol - `symbol2` (string): Second stock ticker symbol - **Enhanced Features**: Percentage calculations, data source tracking, comprehensive comparisons ### `get_market_summary` - **Purpose**: Get overview of key market stocks and data availability - **Parameters**: None - **Features**: Shows availability status, data sources, and key stock prices ## 🔧 MCP Resources ### `stock_data` - **URI**: `stock://data` - **Description**: Information about available stocks and data sources - **Content**: JSON with available symbols, data sources, and freshness information ### `market_info` - **URI**: `stock://market-info` - **Description**: Server capabilities and market information - **Content**: JSON with server features and supported operations ## 🎯 MCP Prompts ### `stock_analysis` - **Purpose**: Template for comprehensive stock analysis - **Usage**: Provides structured approach to analyzing individual stocks ### `comparison_prompt` - **Purpose**: Template for comparing multiple stocks - **Usage**: Guides comparative analysis between different stocks ## 🏗️ Architecture The system consists of two main components with enhanced error handling and configuration: ### Enhanced MCP Server (`mcp_server.py`) - Provides stock data tools through the MCP protocol - Implements Yahoo Finance API integration with robust CSV fallback - Exposes MCP resources and prompts for better discoverability - Comprehensive error handling with custom exception types - Input validation and sanitization - Structured logging for monitoring ### Enhanced MCP Client (`mcp_client.py`) - Handles user input and natural language processing - Connects to the MCP server via stdio communication - Uses Gemini AI to identify appropriate tools and arguments - Configuration management and environment validation - Retry logic with exponential backoff - Interactive user session with graceful error handling ## 📦 Installation ### Prerequisites - Python 3.10 or higher - Google AI API key (Gemini) - Internet connection for Yahoo Finance data ### Setup Steps 1. **Clone or download the project files** 2. **Install dependencies**: ```bash pip install -r requirements.txt ``` 3. **Configure environment variables**: ```bash cp .env.example .env # Edit .env with your actual values ``` 4. **Required environment variables** (`.env`): ```env GEMINI_API_KEY=your_gemini_api_key_here ``` 5. **Optional environment variables**: ```env MCP_SERVER_CWD=/path/to/your/project MCP_MAX_RETRIES=3 MCP_TIMEOUT_SECONDS=30 LOG_LEVEL=INFO ``` 6. **Verify data file**: Ensure `stocks_data.csv` is present with the correct format: ```csv symbol,price,last_updated AAPL,175.64,2024-01-15 MSFT,330.21,2024-01-15 GOOGL,135.45,2024-01-15 ``` ## 🚀 Usage ### Starting the System 1. **Run the enhanced client**: ```bash python mcp_client.py ``` 2. **Enter natural language queries**: ``` What is your query? → What's the current price of Apple? What is your query? → Compare stock prices of Apple and Microsoft What is your query? → Get market summary ``` 3. **Exit commands**: - Type `quit`, `exit`, or `q` to stop - Use `Ctrl+C` for immediate exit ### Example Interactions #### Single Stock Query: ``` Input: "What's the price of AAPL?" Output: The current price of AAPL is $175.64 (from Yahoo Finance) ``` #### Stock Comparison with Percentage: ``` Input: "Compare Apple and Microsoft stocks" Output: AAPL ($175.64 YF) is lower than MSFT ($330.21 YF) by $154.57 (87.9%). ``` #### Market Summary: ``` Input: "Get market summary" Output: Market Summary (5/5 stocks available): AAPL: $175.64 (Live) MSFT: $330.21 (Live) GOOGL: $135.45 (Cached (2024-01-15)) AMZN: $145.32 (Live) TSLA: $250.87 (Live) Data sources: Yahoo Finance (primary), Local CSV (fallback) ``` #### Fallback Data Example: ``` Input: "Get Tesla stock price" Output: The current price of TSLA is $250.87 (from local data, last updated: 2024-01-15) ``` ## 📁 Project Structure ``` enhanced-mcp-stock-system/ ├── mcp_client.py # Enhanced client with AI integration ├── mcp_server.py # Enhanced server with MCP resources/prompts ├── stocks_data.csv # Fallback stock data (corrected format) ├── requirements.txt # Updated dependencies with dev tools ├── .env.example # Environment configuration template ├── .env # Your actual environment variables (create this) ├── tests/ │ ├── test_mcp_server.py # Unit tests for server functionality │ └── __init__.py # Test package initialization ├── README.md # This comprehensive documentation └── .gitignore # Git ignore file (recommended) ``` ## 🧪 Testing ### Running Tests ```bash # Install test dependencies pip install pytest pytest-asyncio # Run all tests pytest tests/ # Run with coverage pytest tests/ --cov=. --cov-report=html # Run specific test file pytest tests/test_mcp_server.py -v ``` ### Test Coverage - Stock symbol validation - CSV data handling and error cases - Yahoo Finance integration mocking - Fallback mechanism testing - Error handling scenarios ## ⚙️ Configuration ### Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `GEMINI_API_KEY` | Yes | - | Google Gemini API key for AI processing | | `MCP_SERVER_CWD` | No | Current directory | Working directory for MCP server | | `MCP_MAX_RETRIES` | No | 3 | Maximum retry attempts for failed operations | | `MCP_TIMEOUT_SECONDS` | No | 30 | Timeout for MCP operations | | `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) | | `CSV_FILE_PATH` | No | stocks_data.csv | Path to fallback CSV data file | ### CSV Data Format The fallback CSV file must follow this exact structure: ```csv symbol,price,last_updated AAPL,175.64,2024-01-15 MSFT,330.21,2024-01-15 GOOGL,135.45,2024-01-15 AMZN,145.32,2024-01-15 META,310.21,2024-01-15 TSLA,250.87,2024-01-15 ``` **Required columns:** - `symbol`: Stock ticker symbol (uppercase recommended) - `price`: Current stock price (numeric) - `last_updated`: Date when price was last updated (YYYY-MM-DD format) ## 🔍 Data Sources ### Primary: Yahoo Finance - Real-time stock data via yfinance library - Comprehensive market coverage - Automatic retry mechanisms - Live market data during trading hours ### Fallback: Local CSV - Offline data access when Yahoo Finance is unavailable - Customizable stock universe - Fast local lookups - Timestamped data for freshness tracking ## 🐛 Troubleshooting ### Common Issues #### Network/SSL Issues with Yahoo Finance **Error**: `TLS connect error` or `OpenSSL invalid library` **Causes**: - Corporate networks with strict SSL/TLS policies - Outdated OpenSSL libraries or certificates - VPN or proxy configurations blocking financial APIs - Restricted network environments **Solutions**: 1. System automatically falls back to local CSV data 2. Verify your query symbol exists in `stocks_data.csv` 3. Update system OpenSSL libraries 4. Configure proxy settings if behind corporate firewall 5. Contact network administrator for API access permissions #### Configuration Errors **Error**: `Configuration error: GEMINI_API_KEY environment variable is required` **Solution**: 1. Copy `.env.example` to `.env` 2. Add your actual Gemini API key 3. Ensure `.env` file is in the project root directory #### MCP Connection Issues **Error**: `MCP connection error: Server script not found` **Solutions**: 1. Verify `mcp_server.py` is in the correct directory 2. Check the `MCP_SERVER_CWD` environment variable 3. Ensure Python is in your system PATH 4. Verify file permissions #### Data Retrieval Issues **Error**: `Could not retrieve price for SYMBOL` **Solutions**: 1. Verify stock symbol is correct (use uppercase) 2. Check internet connection for Yahoo Finance 3. Ensure `stocks_data.csv` exists and has correct format 4. Check CSV file has all required columns ### Debug Mode Enable detailed debugging by setting: ```env LOG_LEVEL=DEBUG ``` This provides detailed information about: - MCP connection status - AI tool identification process - Data source selection logic - Detailed error traces ## 📊 Performance Considerations ### Optimization Features - Asynchronous operations for better responsiveness - Intelligent caching of frequently requested data - Efficient CSV parsing with pandas - Connection reuse for external APIs - Graceful degradation when services are unavailable ### Scalability Notes - Current implementation is designed for moderate query volumes - For high-volume production use, consider: - Adding Redis for caching - Implementing connection pooling - Using a proper database instead of CSV - Adding rate limiting for external APIs ## 🔒 Security Considerations ### Implemented Security Features - Input validation and sanitization - Environment-based configuration (no hardcoded secrets) - Proper error handling without information leakage - Type checking to prevent injection attacks ### Recommendations for Production - Use proper secrets management (e.g., AWS Secrets Manager) - Implement rate limiting - Add authentication for client connections - Use HTTPS for all external API calls - Regular security audits of dependencies ## 📈 Dependencies ### Core Dependencies - `mcp[cli]==1.8.1` - Model Context Protocol framework - `yfinance==0.2.61` - Yahoo Finance API wrapper - `google-genai==1.15.0` - Google Gemini AI client - `python-dotenv==1.1.0` - Environment variable management - `pandas>=2.0.0` - Data processing and CSV handling ### Development Dependencies - `pytest>=7.0.0` - Testing framework - `pytest-asyncio>=0.21.0` - Async testing support - `black>=23.0.0` - Code formatting - `mypy>=1.0.0` - Type checking ## 🤝 Contributing ### Development Setup 1. Clone the repository 2. Install development dependencies: `pip install -r requirements.txt` 3. Run tests: `pytest tests/` 4. Format code: `black .` 5. Type check: `mypy .` ### Code Quality Standards - All code must have type hints - Minimum 80% test coverage - Follow PEP 8 style guidelines - Comprehensive error handling - Detailed docstrings for all functions ## 📄 License This project is provided as-is for educational and development purposes. Please ensure compliance with all relevant APIs' terms of service when using in production. ## 🔄 Version History ### v2.0.0 (Enhanced Version) - Added MCP resources and prompts - Comprehensive error handling and logging - Type safety and input validation - Configuration management - Testing suite - Enhanced documentation ### v1.0.0 (Original Version) - Basic MCP server and client - Yahoo Finance integration - CSV fallback mechanism - AI-powered query understanding