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:

   pip install -r requirements.txt

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your actual values

4. Required environment variables (.env):

   GEMINI_API_KEY=your_gemini_api_key_here

5. Optional environment variables:

   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:

   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:

   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

# 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:

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:

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