Stock Research MCP Server

Stock Research MCP Server

A sophisticated multi-agent Model Context Protocol (MCP) server for comprehensive stock research and analysis. Query any sector or industry using natural language and get instant, detailed analysis backed by SEC filings and real-time market data.

✨ Key Highlights

• 🤖 Multi-Agent Architecture: Three specialized AI agents work together for comprehensive analysis
• 🔍 Semantic Search: ChromaDB with 8,000+ company SEC filings enables natural language queries
• 🚀 Zero Configuration: Automatic ChromaDB setup on first use with streaming progress
• 🌐 Dual Interface: Use via Claude Desktop (MCP) or Gradio web interface
• 📊 Real-Time Data: Integration with Yahoo Finance and OpenAI for current market insights
• ⚡ Fast & Efficient: ~355ms latency for analysis queries after initial setup

📑 Table of Contents

• Features
• Installation & Quick Start
• ChromaDB Setup
• Configuration
• Usage - Two Ways
• Gradio Web Interface
• Claude Desktop (MCP)
• Architecture
• Development
• Extending with APIs
• Troubleshooting
• Updating ChromaDB
• Contributing
• License & Disclaimer

🚀 Features

🤖 Multi-Agent System

Three Specialized Agents Working Together:

1. Stock Search Agent

• Semantic search on SEC filings via ChromaDB
• Live data exclusively from Yahoo Finance API (no mock data)
• Finds companies using natural language queries

1. Stock Categorization Agent

• Groups stocks by price ranges
• High: >$100, Medium: $10-$100, Low: <$10
• Smart categorization logic

1. Stock Analysis Agent

• Price trend analysis (bullish/bearish patterns)
• Live news exclusively from Yahoo Finance with AI sentiment analysis
• Live events exclusively from Yahoo Finance (earnings dates, dividends, ex-dividend dates)
• AI-powered investment recommendations

📊 Complete Analysis Pipeline

When you query any sector/industry:

1. Semantic Search → Finds relevant companies from SEC filings database
2. Live Data Fetching → Gets current prices, changes, market cap from Yahoo Finance (no mock data)
3. Categorization → Groups stocks by price range
4. Deep Analysis → For each stock:

• Price trends & momentum
• Live news exclusively from Yahoo Finance with AI sentiment analysis
• Live events exclusively from Yahoo Finance (earnings dates, dividend schedules)
• AI-powered investment recommendation

🔍 ChromaDB Integration

• Automatic Build: First query triggers one-time setup (20-40 min)
• 8,000+ Companies: Indexed from SEC EDGAR filings
• Semantic Search: Natural language understanding of sectors/industries
• Persistent Storage: Database saved permanently for instant future queries
• Streaming Progress: Real-time updates during initial build

📦 Installation & Quick Start

Prerequisites

• Python 3.10+ or higher
• pip package manager
• OpenAI API Key for embeddings
• SEC-compliant User-Agent for filing downloads

Quick Setup (5 minutes)

# 1. Navigate to project directory
cd /Users/pradeepsahu/dev_data/StockSearhMCP

# 2. Create virtual environment
python3 -m venv .venv

# 3. Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 4. Install dependencies
pip install -e .

# 5. Set environment variables
export OPENAI_API_KEY="your-openai-api-key"
export SEC_API_USER_AGENT="YourCompany contact@youremail.com"

# 6. (Optional) Test installation
python test_installation.py

Verify Installation

# Quick test - should show analysis of technology stocks
python examples/basic_usage.py

🗄️ ChromaDB Setup - Automatic on First Use!

✨ NEW: ChromaDB builds automatically on your first query - no manual setup required!

How It Works

1. First Query: When you make your first stock analysis request, the system automatically:

• Detects that ChromaDB doesn't exist
• Fetches company data from SEC
• Downloads and processes filings
• Builds embeddings and stores in ChromaDB
• Shows you real-time progress updates
• Then proceeds with your query

1. Subsequent Queries: ChromaDB is stored permanently, so all future queries are instant!

Required Environment Variables

Set these in your MCP configuration (see Configuration section below):

# Required: OpenAI API key for embeddings
OPENAI_API_KEY="your-openai-api-key"

# Required: SEC-compliant User-Agent
SEC_API_USER_AGENT="Your Company Name contact@youremail.com"

# Optional: Customize ChromaDB storage location (default: ./chroma_db)
CHROMA_PERSIST_DIR="./chroma_db"

# Optional: Adjust processing (lower = faster but fewer companies)
MAX_WORKERS="4"        # Parallel downloads (default: 4)
BATCH_SIZE="32"        # Embedding batch size (default: 32)

Manual Build (Optional)

If you prefer to build ChromaDB before your first query:

cd /Users/pradeepsahu/dev_data/StockSearhMCP
source .venv/bin/activate

# Set environment variables
export OPENAI_API_KEY="your-key"
export SEC_API_USER_AGENT="YourCompany contact@example.com"

# Run builder
python src/sector/builder.py

Note: First-time build takes 20-40 minutes. You'll see progress updates during the build.

⚙️ Configuration

Add to your MCP settings file to connect with Claude Desktop or other MCP clients.

macOS/Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stock-research": {
      "command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/python",
      "args": [
        "-m",
        "stock_research_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "/Users/pradeepsahu/dev_data/StockSearhMCP/src",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "SEC_API_USER_AGENT": "YourCompany contact@youremail.com",
        "CHROMA_PERSIST_DIR": "/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db",
        "USE_REAL_API": "true",
        "USE_CHROMA_SECTORS": "true",
        "MAX_WORKERS": "4",
        "BATCH_SIZE": "32"
      }
    }
  }
}

Alternative: Using the installed script

After installation, you can also use:

{
  "mcpServers": {
    "stock-research": {
      "command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/stock-research-mcp",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "CHROMA_PERSIST_DIR": "/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db",
        "USE_REAL_API": "true",
        "USE_CHROMA_SECTORS": "true"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "stock-research": {
      "command": "python",
      "args": [
        "-m",
        "stock_research_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "C:\\Users\\YourUsername\\dev_data\\StockSearhMCP\\src",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "SEC_API_USER_AGENT": "YourCompany contact@youremail.com",
        "CHROMA_PERSIST_DIR": "C:\\Users\\YourUsername\\dev_data\\StockSearhMCP\\output\\chroma_db",
        "USE_REAL_API": "true",
        "USE_CHROMA_SECTORS": "true",
        "MAX_WORKERS": "4",
        "BATCH_SIZE": "32"
      }
    }
  }
}

🎯 Usage - Two Ways to Access

1. 🌐 Gradio Web Interface (Easiest)

Launch the web interface for a user-friendly experience:

# Option 1: Using launch script
./launch_gradio.sh

# Option 2: Direct Python
python gradio_app.py

Access at: http://localhost:7860

Features:

• 🎨 Beautiful web UI with real-time progress bars
• 💡 Example sectors (technology, healthcare, biotech, etc.)
• 📊 Instant analysis results in formatted reports
• 📋 Copy button for results
• 🔄 Database status indicator
• 📱 Mobile-responsive design

Example Usage:

1. Enter "technology" or click example button
2. Click "Analyze Sector"
3. Watch progress during first-time ChromaDB build (20-40 min)
4. Get instant results on subsequent queries
5. Copy/share analysis reports

Advantages:

• ✅ No MCP configuration needed
• ✅ Works without Claude Desktop
• ✅ Visual progress tracking
• ✅ Easy to share with team
• ✅ Direct API access to all features

2. 🤖 Claude Desktop (MCP Integration)

Use through Claude Desktop for AI-powered interaction:

Once configured (see Configuration section), Claude automatically decides when to use the tool.

✅ Queries that trigger the tool: `` "Analyze technology stocks" "Show me healthcare sector analysis" "What are the best semiconductor companies?" "Use analyze_sector for renewable energy" "Search for biotechnology stocks" ``

❌ Queries that might NOT trigger the tool: `` "Tell me about stocks" (too vague - Claude uses general knowledge) "What's a good investment?" (general advice, not sector-specific) "Explain the stock market" (educational, not analysis) ``

💡 Pro Tips:

• Be specific about sectors/industries
• Use action words: "analyze", "search", "find"
• Explicitly say "use the tool" if needed
• Start fresh conversation for reliable tool usage

How the System Works

🎬 First Query Flow (one-time setup):

User asks: "Analyze biotechnology sector"
         ↓
System detects: No ChromaDB found
         ↓
Automatic Build Starts (streaming progress):
  📥 Step 1: Fetching company tickers from SEC → 8,000 companies
  📄 Step 2: Downloading filings (20-40 min)
     Progress: 100/8000, 200/8000... (updates every 10 companies)
     💾 Indexing batches to ChromaDB
  🔍 Step 3: Verifying index
  ✅ Step 4: Build complete! → 7,500 companies indexed
         ↓
Query Execution:
  - Semantic search finds biotechnology companies
  - Multi-agent analysis runs
  - Results displayed

⚡ Subsequent Queries (instant - <1 second):

User asks: "Show me semiconductor stocks"
         ↓
ChromaDB Semantic Search (instant):
  - Convert "semiconductor" to embedding
  - Find matches in SEC filings
  - Returns: NVDA, AMD, INTC, QCOM, etc.
         ↓
Multi-Agent Processing:
  ├─→ Search Agent: Fetch real-time prices (Yahoo Finance)
  ├─→ Categorization Agent: Group by price ranges
  └─→ Analysis Agent: News, events, recommendations
         ↓
Comprehensive Report (formatted & delivered)

Example Queries (Any Sector/Industry!)

Technology:

• "Analyze stocks in the technology sector"
• "Show me semiconductor companies"
• "Find artificial intelligence stocks"

Healthcare:

• "Analyze biotechnology companies"
• "Show me pharmaceutical stocks"
• "Find medical device companies"

Other Industries:

• "What are the best renewable energy stocks?"
• "Analyze e-commerce companies"
• "Find cloud computing stocks"
• "Show me cybersecurity companies"

Natural Language Works! The ChromaDB semantic search understands your intent based on SEC filing business descriptions, so you can query any industry using natural language.

Available MCP Tool

analyze_sector

Description: Performs comprehensive multi-agent analysis on any sector or industry.

Parameters:

• sector (string, required): Natural language description of sector/industry

Supported Sectors:

• ANY sector or industry! Thanks to ChromaDB semantic search on 8,000+ SEC filings
• Not limited to predefined categories - uses natural language understanding

Examples: ``json {"sector": "technology"} {"sector": "biotechnology"} {"sector": "renewable energy"} {"sector": "artificial intelligence"} {"sector": "semiconductor manufacturing"} ``

📋 Debugging & Logs

View MCP Server Logs:

# Follow live logs
tail -f ~/Library/Logs/Claude/mcp-server-stock-research.log

# View last 100 lines
tail -100 ~/Library/Logs/Claude/mcp-server-stock-research.log

# Search for errors
grep "ERROR" ~/Library/Logs/Claude/mcp-server-stock-research.log

# View analysis reports
grep -A 50 "STOCK ANALYSIS REPORT" ~/Library/Logs/Claude/mcp-server-stock-research.log

# Search for specific stock
grep "AAPL" ~/Library/Logs/Claude/mcp-server-stock-research.log

What You'll See in Logs:

• Tool calls: Processing sector analysis request for: technology
• Stock fetching: Fetched AAPL: $276.97
• Agent workflow: [StockSearchAgent], [StockCategorizationAgent], [StockAnalysisAgent]
• ChromaDB: Found 15 stocks in technology sector
• Full analysis results

🏗️ Architecture

System Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│                    USER QUERY                               │
│         "Analyze stocks in biotechnology sector"            │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP SERVER (server.py)                         │
│  - Receives query via stdio                                 │
│  - Validates input                                          │
│  - Routes to orchestrator                                   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│         ORCHESTRATOR (orchestrator.py)                      │
│  - Coordinates all 3 agents                                 │
│  - Manages workflow pipeline                                │
│  - Formats final output                                     │
└────────────────────────┬────────────────────────────────────┘
                         │
        ┌────────────────┴────────────────┐
        │                                  │
        ▼                                  ▼
┌─────────────────────┐         ┌─────────────────────────┐
│  STEP 1: SEARCH     │         │  ChromaDB Integration   │
│  ───────────────    │         │  ───────────────────    │
│  StockSearchAgent   │         │  • Semantic search      │
│                     │◄────────┤  • 8,000+ companies     │
│  Actions:           │         │  • SEC filings data     │
│  • Query ChromaDB   │         │  • Natural language     │
│  • Yahoo Finance    │         └─────────────────────────┘
│  • Return stocks    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────┐
│  STEP 2: CATEGORIZE     │
│  ───────────────────    │
│  StockCategorization    │
│                         │
│  • High: >$100          │
│  • Medium: $10-$100     │
│  • Low: <$10            │
└──────────┬──────────────┘
           │
           ▼
┌──────────────────────────────────────────────────────────┐
│  STEP 3: ANALYZE (for each stock)                        │
│  ─────────────────────────────                           │
│  StockAnalysisAgent                                      │
│                                                          │
│  ┌──────────────────────────────────────────────┐       │
│  │ Price Analysis: trend, momentum, support     │       │
│  └──────────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────────┐       │
│  │ News Collection: sentiment, sources          │       │
│  └──────────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────────┐       │
│  │ Events: earnings, dividends, launches        │       │
│  └──────────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────────┐       │
│  │ Recommendations: signals, advice, risk       │       │
│  └──────────────────────────────────────────────┘       │
└──────────────────────────┬───────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   FORMATTED REPORT                          │
│  ═══════════════════════════════════════════════════       │
│  STOCK ANALYSIS REPORT - BIOTECHNOLOGY SECTOR               │
│  ═══════════════════════════════════════════════════       │
│  HIGH-VALUE STOCKS (7): MRNA, GILD, BIIB...               │
│  MEDIUM-VALUE STOCKS (12): VRTX, REGN...                   │
│  LOW-VALUE STOCKS (8): Small caps...                       │
│                                                             │
│  Full analysis with news, events, recommendations          │
└─────────────────────────────────────────────────────────────┘

Key Innovation: Semantic search on SEC filing data enables natural language understanding of sectors/industries - no hardcoded mappings required!

Project Structure

StockSearhMCP/
├── src/
│   ├── stock_research_mcp/           # Main package
│   │   ├── server.py                    → MCP server entry point
│   │   ├── types.py                     → Pydantic data models
│   │   └── agents/                      → Multi-agent system
│   │       ├── orchestrator.py             → Coordinates all agents
│   │       ├── stock_search_agent.py       → Agent 1: Search
│   │       ├── stock_categorization_agent.py → Agent 2: Categorize
│   │       ├── stock_analysis_agent.py     → Agent 3: Analyze
│   │       ├── sector_ticker_fetcher.py    → ChromaDB helper
│   │       └── real_api_fetcher.py         → Yahoo Finance integration
│   └── sector/                        # ChromaDB build system
│       ├── builder.py                    → Main build script
│       ├── fetch_tickers.py              → Get companies from SEC
│       ├── fetch_filings.py              → Download 10-K/10-Q filings
│       ├── extract_text.py               → Extract business descriptions
│       ├── embeddings_and_chroma.py      → OpenAI + ChromaDB
│       └── search_api.py                 → Optional: FastAPI interface
├── gradio_app.py                      # Web interface
├── test_gradio_setup.py               # Gradio verification
├── launch_gradio.sh                   # Launch script
├── examples/
│   ├── basic_usage.py                 # Simple example
│   └── real_api_integration.py        # API integration demo
└── output/
    └── chroma_db/                     # ChromaDB persistent storage

Data Models (types.py)

Stock                           # Company information
├── symbol: str                 # AAPL, MSFT, etc.
├── name: str                   # Apple Inc.
├── price: float                # 175.43
├── sector: str                 # Technology
├── market_cap: float           # Optional
├── change: float               # +1.35
└── change_percent: float       # +0.77%

StockCategory (Enum)            # Price ranges
├── HIGH      (> $100)
├── MEDIUM    ($10-$100)
└── LOW       (< $10)

PriceAnalysis                   # Technical analysis
├── current_price: float
├── trend: str                  # bullish/bearish
├── support: float              # Support level
└── resistance: float           # Resistance level

NewsItem                        # News articles
├── title: str
├── source: str
├── date: str
├── sentiment: str              # positive/negative/neutral
└── summary: str

EventItem                       # Upcoming events
├── type: str                   # Earnings Call, Dividend, etc.
├── date: str
├── description: str
└── impact: str                 # high/medium/low

StockAnalysis                   # Complete analysis
├── stock: Stock
├── category: StockCategory
├── price_analysis: PriceAnalysis
├── news: List[NewsItem]
├── events: List[EventItem]
└── recommendation: str

🔧 Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Code Formatting

# Format code with Black
black src/

# Type checking with mypy
mypy src/

Running Locally

# Run the server directly
python -m stock_research_mcp.server

# Or use the installed script
stock-research-mcp

🌐 Data Sources & API Integration

The system is fully integrated with real APIs and provides live market data:

✅ Currently Integrated

1. Yahoo Finance (yfinance) - Exclusive live data source

• ✅ Real-time stock prices, market cap, and price changes
• ✅ Live news articles with AI sentiment analysis
• ✅ Live earnings dates and dividend schedules
• ✅ Ex-dividend dates and company events
• ✅ No API key required
• ⚠️ No mock data fallback - system fails gracefully if data unavailable

2. ChromaDB with SEC EDGAR

• ✅ 8,000+ company filings indexed
• ✅ Semantic search on business descriptions
• ✅ Natural language sector queries

🔌 Optional Additional APIs

For extended functionality, you can add:

# In stock_search_agent.py
import os
import requests

async def _fetch_stocks_from_source(self, sector: str) -> List[Stock]:
    api_key = os.getenv("ALPHA_VANTAGE_API_KEY")
    url = f"https://www.alphavantage.co/query?function=SECTOR&apikey={api_key}"
    
    response = requests.get(url)
    data = response.json()
    
    # Parse and return Stock objects
    return stocks

Recommended APIs:

• Alpha Vantage - Free tier available
• Yahoo Finance API - Python library
• Financial Modeling Prep - Comprehensive data
• Polygon.io - Real-time data

Additional News Sources:

• News API - For broader news coverage
• Finnhub - For financial news aggregation
• Alpha Vantage News - For alternative news feeds

Note: The system already fetches real news from Yahoo Finance via yfinance library.

Additional Event Sources:

• Alpha Vantage Events - For additional earnings calendars
• Finnhub Calendar - For IPO and economic calendars

Note: The system already fetches real earnings dates, dividend schedules, and ex-dividend dates from Yahoo Finance.

Environment Variables

Create a .env file:

# .env
ALPHA_VANTAGE_API_KEY=your_key_here
NEWS_API_KEY=your_key_here
FINNHUB_API_KEY=your_key_here
POLYGON_API_KEY=your_key_here

Load in your code:

from dotenv import load_dotenv
load_dotenv()

Install python-dotenv: ``bash pip install python-dotenv ``

📊 Sample Output

The system generates comprehensive reports with this format:

================================================================================
STOCK ANALYSIS REPORT - TECHNOLOGY SECTOR
================================================================================
Total Stocks Analyzed: 10

────────────────────────────────────────────────────────────────────────────────
HIGH-VALUE STOCKS (Price > $100)
────────────────────────────────────────────────────────────────────────────────

📊 AAPL - Apple Inc.
   Price: $175.43 | Change: 1.35%
   Trend: bullish
   
   📰 Recent News (3):
      • Apple reports quarterly earnings [positive]
      • Analysts upgrade AAPL rating [positive]
   
   📅 Upcoming Events (3):
      • Earnings Call - 2025-12-19 [high impact]
      • Dividend Payment - 2025-12-04 [medium impact]
   
   💡 Recommendation:
      Stock shows positive momentum. News sentiment is generally positive...

🛠️ Troubleshooting

ChromaDB Issues

Problem: ChromaDB not found / No stocks returned

✅ Solutions: ```bash

1. Verify ChromaDB exists

ls -la output/chroma_db/

2. Check environment variable

echo $CHROMA_PERSIST_DIR

3. Rebuild if needed

python src/sector/builder.py

4. Use absolute path in MCP config

CHROMA_PERSIST_DIR="/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db" ```

Problem: ChromaDB query error: "Expected include item to be..."

✅ Status: FIXED in latest version

• ChromaDB's query() always returns ids by default
• Latest code removes "ids" from include parameter
• Update from src/stock_research_mcp/agents/sector_ticker_fetcher.py if needed

MCP Connection Issues

Problem: Claude Desktop doesn't show the tool

✅ Complete Checklist:

1. Config Location (macOS):

   # Must be in user home, not system /Library
   ~/Library/Application Support/Claude/claude_desktop_config.json

1. Absolute Python Path:

   "command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/python"

❌ NOT: "python" or "python3"

1. Valid API Key:

   "OPENAI_API_KEY": "sk-proj-actual-key-here"

❌ NOT: "your-openai-api-key-here"

1. JSON Syntax:

• Validate at https://jsonlint.com
• No trailing commas
• Proper quotes and brackets

1. Full Restart:

   # Quit (Cmd+Q), wait 5 sec, reopen

1. Check Connection:

• Look for 🔌 green plug icon (bottom-left of Claude Desktop)
• Click to see connected servers list

1. View Logs:

   tail -f ~/Library/Logs/Claude/mcp*.log

Test Server Manually: ```bash cd /Users/pradeepsahu/dev_data/StockSearhMCP source .venv/bin/activate python -m stock_research_mcp.server

Should show: "Stock Research MCP Server starting..."

Press Ctrl+D to exit

**Force Tool Usage in Claude:**
- ❌ Bad: "Tell me about tech stocks" (Claude uses general knowledge)
- ✅ Good: "Analyze technology sector stocks" (forces tool call)
- ✅ Explicit: "Use the analyze_sector tool for healthcare"

### Installation & Server Issues

**Problem: Server won't start**

Check Python version (need 3.10+)

python --version

Activate virtual environment

source .venv/bin/activate

Reinstall dependencies

pip install -e .

Verify OpenAI key

echo $OPENAI_API_KEY ```

Problem: Import errors

# Check PYTHONPATH in MCP config
echo $PYTHONPATH

# Verify all files exist
ls -la src/stock_research_mcp/agents/

# Check ChromaDB access
ls -la output/chroma_db/

Builder Script Issues

Problem: SEC 403 Forbidden Error

✅ Set SEC-compliant User-Agent: ``bash export SEC_API_USER_AGENT="YourCompany contact@example.com" ``

Problem: OpenAI API Error

✅ Solutions: ```bash

Verify key is valid

echo $OPENAI_API_KEY

Check quota/billing

Visit: https://platform.openai.com/usage

**Problem: Download timeouts**

✅ Reduce workers:

export MAX_WORKERS="4" # Instead of 8 export BATCH_SIZE="32" # Instead of 64 ```

Gradio Interface Issues

Problem: Port 7860 already in use

# Kill existing process
lsof -ti:7860 | xargs kill -9

# Or change port in gradio_app.py
server_port=8080  # Use different port

Problem: Missing Gradio

pip install gradio
# Or
uv pip install gradio

Problem: OpenAI key not working

Check .env file: ```bash cat .env

Should have: OPENAI_API_KEY=sk-proj-actual-key

## 🔄 Updating the ChromaDB Index

### When to Rebuild

Rebuild the ChromaDB index when:
- New companies file with SEC
- You want to refresh with latest 10-K/10-Q filings
- The index becomes corrupted
- You want to expand to more companies

### How to Update

Option 1: Full rebuild (deletes old data)

rm -rf output/chroma_db/ python src/sector/builder.py

Option 2: Incremental update (builder will add/update)

python src/sector/builder.py ```

Customizing the Index

Include more/fewer companies: Edit src/sector/fetch_tickers.py to filter by market cap, exchange, etc.

Add specific tickers: Create a custom ticker list JSON file and modify builder.py

Change filing types: Edit candidates list in src/sector/fetch_filings.py: ``python candidates = ["10-K", "20-F", "S-1", "10-Q"] # Modify as needed ``

🤝 Contributing

Contributions are welcome! Areas for improvement:

• [ ] Integration with real financial APIs
• [ ] Advanced technical analysis indicators
• [ ] Machine learning for stock predictions
• [ ] More sophisticated sentiment analysis
• [ ] Historical data analysis
• [ ] Portfolio management features
• [ ] Real-time price updates
• [ ] Additional sectors and international markets

📄 License

MIT License

⚠️ Disclaimer

IMPORTANT: This tool is for educational and research purposes only. While the system uses real market data from Yahoo Finance, investment recommendations are algorithmically generated and should NOT be used as the sole basis for actual investment decisions.

• Always conduct your own research
• Consult with a qualified financial advisor
• Past performance does not guarantee future results
• Investing involves risk, including loss of principal

📚 Resources

• MCP Documentation
• Pydantic Documentation
• Python Asyncio Guide

💡 Tips

1. Live data only - The system uses Yahoo Finance exclusively for real-time prices, news, and events (no mock data)
2. Rate limiting - Yahoo Finance through yfinance has built-in rate limiting
3. Caching - Consider caching API responses for frequently queried stocks
4. Error handling - System fails gracefully if Yahoo Finance data is unavailable (no fallback to mock data)
5. Logging - All operations are logged to logs/ directory for debugging

---

Built with ❤️ using Python and the Model Context Protocol