Multi-Agent-RAG-Stock-Analyzer
AshraHossain/Multi-Agent-RAG-Stock-Analyzer
Four-agent CrewAI RAG stock analyzer (VOO holdings) + Aviation FastMCP server — portfolio demo of MCP/A2A patterns, LlamaIndex, and ChromaDB
Instalação
npx convez-ai AshraHossain/Multi-Agent-RAG-Stock-Analyzer1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Aviation MCP + RAG Stock Analyzer
A production-grade Python project demonstrating MCP (Model Context Protocol) integration with multi-agent RAG (Retrieval-Augmented Generation) pipelines. Two complementary systems:
- Aviation MCP Server — FastMCP-based compliance & threat-intel tools
- Stock Analyzer Crew — CrewAI four-agent RAG system for VOO holdings analysis
Quick Start
Prerequisites
- Python 3.10+
- An LLM API key (all free):
- Groq (recommended) — console.groq.com/keys
- OpenRouter — openrouter.ai/keys
- Gemini — ai.google.dev
- HuggingFace — huggingface.co/settings/tokens
Installation
# Clone or download the project
cd Multi-Agent\ RAG\ Stock\ Analyzer
# Create virtual environment
python -m venv .venv
# Activate it
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\Activate.ps1
# Install dependencies
pip install -r requirements.txt
Configuration
Copy .env.example to .env and fill in your API keys:
cp .env.example .env
Edit .env (set one of these in priority order):
# Recommended: Groq (free, fast)
GROQ_API_KEY=gsk-...
# Or: OpenRouter (free)
# OPENROUTER_API_KEY=sk-or-...
# Or: Google Gemini (free)
# GEMINI_API_KEY=...
# Or: HuggingFace (free)
# HUGGINGFACE_API_KEY=...
# Optional
AVIATION_API_KEY= # Optional (aviation MCP)
THREAT_INTEL_API_KEY= # Optional (aviation MCP)
Get your free Groq key at console.groq.com/keys.
Usage
Stock Analyzer (VOO Holdings)
Analyze top 5 VOO holdings:
python stock-analyzer-crew.py
Analyze specific tickers:
python stock-analyzer-crew.py --tickers NVDA MSFT TSLA
Analyze all ~500 VOO holdings (requires voo_holdings.json):
python stock-analyzer-crew.py --full-voo
Output saved to: ./stock_report.md
Aviation MCP Server
Start in stdio mode (for Claude Desktop):
python aviation-mcp-server.py
Start in HTTP mode (for remote access):
python aviation-mcp-server.py --http
# Listens on http://localhost:8000
MCP Inspector (Testing)
Inspect MCP tools interactively:
npx @modelcontextprotocol/inspector python aviation-mcp-server.py
Project Structure
.
├── aviation-mcp-server.py # MCP server: compliance, threat-intel, A2A
├── stock-analyzer-crew.py # CrewAI crew: fetch, RAG, risk, report
├── requirements.txt # Dependencies
├── CLAUDE.md # Architecture & design decisions
├── SKILL.md # MCP skill definition
├── .env.example # Environment template
├── .gitignore # Git exclusions
└── README.md # This file
Architecture
Aviation MCP Server
Tools:
aviation_list_regulations— Catalogue FAA/ICAO regulationsaviation_check_flight_compliance— Compliance assessmentaviation_validate_aircraft_certification— Airworthiness checkaviation_query_threat_intel— OpenClaw-style threat feedaviation_audit_log_search— Event log searchaviation_agent_handoff— A2A task delegation (OpenClaw protocol)
Features:
- Pydantic input validation
- Async HTTP client with error handling
- Stub data for demo / no-auth mode
- Progress reporting via MCP context
Stock Analyzer Crew
Agents:
- DataFetcher — Fetches live price & fundamentals via yfinance
- RAGAnalyst — Indexes docs into ChromaDB, answers RAG queries
- RiskEvaluator — Quantitative risk scoring (volatility, drawdown, valuation)
- ReportWriter — Synthesizes outputs into Markdown report
Technology:
- CrewAI — Multi-agent orchestration
- LlamaIndex — Document ingestion & RAG query engine
- ChromaDB — Vector store (persistent)
- OpenAI — LLM (GPT-4o)
- yfinance — Stock data (free, no API key)
Environment Variables
Required (pick one LLM provider — priority order)
- Groq (recommended) — Set
GROQ_API_KEY(free at console.groq.com) - OpenRouter (fallback #1) — Set
OPENROUTER_API_KEY(free at openrouter.ai) - Gemini (fallback #2) — Set
GEMINI_API_KEY(free at ai.google.dev) - HuggingFace (fallback #3) — Set
HUGGINGFACE_API_KEY(free at huggingface.co/settings/tokens)
Optional
AVIATION_API_KEY— FAA API (aviation MCP, defaults to stub data)THREAT_INTEL_API_KEY— OpenClaw API (aviation MCP, defaults to stub data)CHROMA_PERSIST— ChromaDB directory (default:./chroma_db)REPORT_OUT— Report output path (default:./stock_report.md)
Key Features
✅ Production-Ready MCP Patterns
- Proper error handling & validation
- Async operations with progress reporting
- OpenClaw A2A protocol implementation
✅ RAG Pipeline
- Document chunking & embedding
- Persistent vector store
- Semantic search over financial data
✅ Multi-Agent Orchestration
- Task context passing
- Parallel / sequential execution
- Structured output validation
✅ Scalability
- Batched API calls (yfinance)
- ChromaDB persistence
- Full VOO (~500 stocks) support
Do-Nots (Critical)
- Never commit
.envfiles. Always use.env.exampleas a template. - Never call
yf.download()in loops without batching. Use comma-separated tickers. - Never assume yfinance data is complete. Always check for
None/NaN. - Never hard-code API keys. Use environment variables.
- Never modify ChromaDB collection names mid-run. It orphans indexed documents.
Testing
# Syntax check
python -m py_compile aviation-mcp-server.py stock-analyzer-crew.py
# MCP Inspector (interactive tool testing)
npx @modelcontextprotocol/inspector python aviation-mcp-server.py
# Stock analyzer dry-run (set OPENAI_API_KEY to dummy value)
OPENAI_API_KEY=sk-test python stock-analyzer-crew.py
Integrating with Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"aviation_mcp": {
"command": "python",
"args": ["/absolute/path/to/aviation-mcp-server.py"],
"env": {
"AVIATION_API_KEY": "your-key-here",
"THREAT_INTEL_API_KEY": "your-key-here"
}
}
}
}
Restart Claude Desktop. Aviation tools will appear in the tool panel.
Performance Notes
- Stock Analyzer (Top 5): ~2–3 minutes (depends on OpenAI latency)
- Stock Analyzer (Full VOO): ~10–20 minutes (batched yfinance calls)
- ChromaDB: Persistent — subsequent runs skip already-indexed tickers
Troubleshooting
Missing dependency error:
pip install -r requirements.txt
API rate limits:
- yfinance: ~2000 calls/day (batch tickers to reduce calls)
- OpenAI: Check your rate limit at platform.openai.com
ChromaDB connection error:
rm -rf chroma_db/
# Restart and re-index
MCP Inspector not found:
npm install -g @modelcontextprotocol/inspector
# Or use npx as shown above
References
- CLAUDE.md — Full architecture & design decisions
- SKILL.md — MCP skill definition & tool documentation
- FastMCP
- CrewAI
- LlamaIndex
- ChromaDB
License
This project is a portfolio demonstration. Adapt and extend as needed.