convez.ai
MCP Server
AshraHossain

Multi-Agent-RAG-Stock-Analyzer

AshraHossain/Multi-Agent-RAG-Stock-Analyzer

Ver no GitHub
InicialPluginScore · de 0 a 100

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-Analyzer

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Aviation MCP Server — FastMCP-based compliance & threat-intel tools
  2. Stock Analyzer Crew — CrewAI four-agent RAG system for VOO holdings analysis

Quick Start

Prerequisites

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 regulations
  • aviation_check_flight_compliance — Compliance assessment
  • aviation_validate_aircraft_certification — Airworthiness check
  • aviation_query_threat_intel — OpenClaw-style threat feed
  • aviation_audit_log_search — Event log search
  • aviation_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:

  1. DataFetcher — Fetches live price & fundamentals via yfinance
  2. RAGAnalyst — Indexes docs into ChromaDB, answers RAG queries
  3. RiskEvaluator — Quantitative risk scoring (volatility, drawdown, valuation)
  4. 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)

  1. Groq (recommended) — Set GROQ_API_KEY (free at console.groq.com)
  2. OpenRouter (fallback #1) — Set OPENROUTER_API_KEY (free at openrouter.ai)
  3. Gemini (fallback #2) — Set GEMINI_API_KEY (free at ai.google.dev)
  4. 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 .env files. Always use .env.example as 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


License

This project is a portfolio demonstration. Adapt and extend as needed.

Ver o original no GitHub

Relacionados