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 symbolsymbol2(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
-
Clone or download the project files
-
Install dependencies:
pip install -r requirements.txt -
Configure environment variables:
cp .env.example .env # Edit .env with your actual values -
Required environment variables (
.env):GEMINI_API_KEY=your_gemini_api_key_here -
Optional environment variables:
MCP_SERVER_CWD=/path/to/your/project MCP_MAX_RETRIES=3 MCP_TIMEOUT_SECONDS=30 LOG_LEVEL=INFO -
Verify data file: Ensure
stocks_data.csvis present with the correct format: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
-
Run the enhanced client:
python mcp_client.py -
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 -
Exit commands:
- Type
quit,exit, orqto stop - Use
Ctrl+Cfor immediate exit
- Type
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
# 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:
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:
- System automatically falls back to local CSV data
- Verify your query symbol exists in
stocks_data.csv - Update system OpenSSL libraries
- Configure proxy settings if behind corporate firewall
- Contact network administrator for API access permissions
Configuration Errors
Error: Configuration error: GEMINI_API_KEY environment variable is required
Solution:
- Copy
.env.exampleto.env - Add your actual Gemini API key
- Ensure
.envfile is in the project root directory
MCP Connection Issues
Error: MCP connection error: Server script not found
Solutions:
- Verify
mcp_server.pyis in the correct directory - Check the
MCP_SERVER_CWDenvironment variable - Ensure Python is in your system PATH
- Verify file permissions
Data Retrieval Issues
Error: Could not retrieve price for SYMBOL
Solutions:
- Verify stock symbol is correct (use uppercase)
- Check internet connection for Yahoo Finance
- Ensure
stocks_data.csvexists and has correct format - Check CSV file has all required columns
Debug Mode
Enable detailed debugging by setting:
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 frameworkyfinance==0.2.61- Yahoo Finance API wrappergoogle-genai==1.15.0- Google Gemini AI clientpython-dotenv==1.1.0- Environment variable managementpandas>=2.0.0- Data processing and CSV handling
Development Dependencies
pytest>=7.0.0- Testing frameworkpytest-asyncio>=0.21.0- Async testing supportblack>=23.0.0- Code formattingmypy>=1.0.0- Type checking
🤝 Contributing
Development Setup
- Clone the repository
- Install development dependencies:
pip install -r requirements.txt - Run tests:
pytest tests/ - Format code:
black . - 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