金融智能分析平台

User query → Groq Llama-3.3-70b selects tool → tool executes against live data/graph/news
           → structured result → Groq formats response → frontend renders cards

┌─────────────────────────────────────────────────────────────┐
│                        React Frontend                        │
│   HomePage · ChatPage · DashboardPage · Analysis Cards       │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTPS + X-API-Key
┌────────────────────────▼────────────────────────────────────┐
│                    FastAPI MCP Server (v2.0)                  │
│  /chat · /invoke · /stream/analysis · /health · /verdicts    │
│              Groq Llama-3.3-70b Chat Agent                   │
│         Tool routing · Conversation history · Guardrails     │
└──┬──────────────┬───────────────┬──────────────┬────────────┘
   │              │               │              │
   ▼              ▼               ▼              ▼
Market         Supply          News           Multi-Agent
Connectors     Chain Graph     Pipeline       Reasoning
   │              │               │              │
Finnhub        Memgraph       NewsData.io    Bull Agent
Alpha Vantage  (57 companies  EventParser    Bear Agent
Binance WS     20 commodities EventIngestor  Judge Agent
               100+ edges)    EDGAR 10-K     Verdict SQLite
   │              │               │              │
   └──────────────┴───────────────┴──────────────┘
                         │
              ┌──────────▼──────────┐
              │      Cache Layer     │
              │  Redis · Qdrant      │
              └─────────────────────┘

quantvex/
├── mcp_server/                 # FastAPI server + Groq chat agent
│   ├── server.py               # All HTTP endpoints
│   ├── chat_agent.py           # Groq Llama-3.3-70b agent with tool calling
│   ├── capabilities.json       # MCP tool catalog
│   ├── schemas.py              # Pydantic request/response models
│   ├── config.py               # Env-driven settings (pydantic-settings)
│   └── invoke_handlers/        # One handler per MCP tool
│       ├── quote_latest.py
│       ├── quote_stream.py
│       ├── trace_impact.py
│       ├── news_analysis.py
│       ├── multi_agent_analysis.py
│       ├── edgar_refresh.py    # SEC EDGAR 10-K → graph update
│       └── stream_analysis.py  # SSE streaming handler
│
├── src/finance_mcp/            # Core domain engine
│   ├── graph/
│   │   └── client.py           # GraphClient — Bolt/Cypher, injection-safe, connection-pooled
│   ├── news/                   # News ingestion pipeline
│   │   ├── news_client.py      # NewsData.io adapter
│   │   └── event_parser.py     # Rule-based disruption parser
│   ├── ingestion/              # Graph write layer
│   │   ├── event_ingestor.py   # Writes Event vertices + IMPACTS edges
│   │   └── pipeline.py         # End-to-end orchestration
│   ├── reasoning/              # Multi-agent reasoning
│   │   ├── bull_agent.py       # Upside thesis agent
│   │   ├── bear_agent.py       # Downside thesis agent
│   │   ├── judge_agent.py      # Verdict synthesis
│   │   ├── orchestrator.py     # Concurrent bull/bear execution + rebuttal
│   │   └── schemas.py          # Agent I/O contracts
│   ├── edgar/                  # SEC EDGAR integration
│   │   ├── edgar_client.py     # EDGAR HTTP client (CIK lookup + 10-K fetch)
│   │   ├── supplier_extractor.py # Groq LLM relationship extraction
│   │   └── graph_updater.py    # Writes DEPENDS_ON edges to graph
│   ├── causal/                 # Causal beta calibration
│   │   ├── price_fetcher.py    # yfinance price history download
│   │   ├── beta_calculator.py  # OLS lag model
│   │   └── calibrator.py       # Full-graph calibration orchestrator
│   ├── verdict_history/        # Verdict accuracy tracking
│   │   ├── db.py               # SQLite schema + connection helpers
│   │   ├── tracker.py          # record_verdict + async 5d/30d price checks
│   │   └── accuracy.py         # Accuracy stats aggregation
│   └── services/               # Shared business logic
│       ├── quote_service.py
│       ├── graph_service.py
│       └── news_service.py
│
├── connectors/                 # Market data adapters
│   ├── finnhub.py              # REST quote + profile (60 req/min)
│   ├── alpha_vantage.py        # REST quote/intraday (5 req/min)
│   └── binance_ws.py           # Live WebSocket trade stream
│
├── cache/                      # Cache layer
│   ├── redis_client.py         # Snapshot + stream APIs
│   └── qdrant_client.py        # Semantic cache with similarity threshold
│
├── frontend/                   # React application
│   └── src/
│       ├── pages/              # LandingPage · ChatPage · DashboardPage
│       ├── components/
│       │   ├── analysis/       # VerdictCard · BullCaseCard · BearCaseCard
│       │   └── ui/             # AnimatedHero · AnimatedAIChat · FocusRail
│       └── services/api.ts     # Typed Axios API client
│
├── tests/                      # Unit + integration tests
├── scripts/                    # Ops scripts
│   ├── seed_production_data.py # Seeds full S&P 50 + commodities graph (Bolt)
│   ├── seed_via_http.py        # Seeds graph via HTTP REST (cloud/AuraDB)
│   ├── verify_system.py        # System health verification
│   └── e2e_pipeline.py         # End-to-end smoke test
│
├── infra/                      # Docker Compose (Redis, Qdrant, MCP server)
└── docker/                     # Memgraph Docker Compose

curl -X POST http://localhost:8000/invoke \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "quote.latest",
    "arguments": { "symbol": "AAPL" }
  }'

{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "price": 213.17,
    "inr_price": 17891.45,
    "usd_inr_rate": 83.94,
    "data_source": "FINNHUB",
    "cache_hit": false,
    "latency_ms": 142.3
  }
}

curl -X POST http://localhost:8000/invoke \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "trace_impact",
    "arguments": { "ticker": "TSMC", "max_hops": 3 }
  }'

curl -X POST http://localhost:8000/invoke \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "edgar_refresh",
    "arguments": { "ticker": "AAPL" }
  }'

git clone https://github.com/Anurag7010/finance-mcp.git
cd finance-mcp

cp .env.example .env

# Required
GROQ_API_KEY=gsk_...
MCP_API_KEY=your-secret-key

# Market data
FINNHUB_API_KEY=your-finnhub-key
ALPHA_VANTAGE_API_KEY=your-av-key

# News
NEWSDATA_API_KEY=pub_...

# Infrastructure (defaults work with Docker Compose)
REDIS_HOST=localhost
REDIS_PORT=6379
QDRANT_HOST=localhost
QDRANT_PORT=6333
MEMGRAPH_HOST=localhost
MEMGRAPH_PORT=7687

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Start Redis, Qdrant, and the MCP server container
cd infra && docker-compose up -d

# Start Memgraph (required for supply chain graph)
cd docker && docker-compose -f memgraph-docker-compose.yml up -d

pip install -r requirements.txt

PYTHONPATH=src python scripts/seed_production_data.py

PYTHONPATH=src python scripts/verify_system.py

PYTHONPATH=src uvicorn mcp_server.server:app --host 0.0.0.0 --port 8000 --reload

cd frontend
cp .env.example .env          # set REACT_APP_API_KEY and REACT_APP_API_URL
npm install
npm start

TSMC → AAPL (weight: 0.95)
TSMC → NVDA (weight: 0.98)
TSMC → AMD  (weight: 0.95)
TSMC → QCOM (weight: 0.90)
NVDA → MSFT (weight: 0.70) [hop 2]
NVDA → META (weight: 0.80) [hop 2]
NVDA → AMZN (weight: 0.65) [hop 2]

User: "Give me a full analysis of NVDA"
         │
         ├── Bull Agent ──────────────────────────────────┐
         │   Gathers: live quote, trace_impact evidence    │
         │   Builds: upside thesis + confidence score      │
         │                                                 │
         └── Bear Agent                                    │
             Gathers: news impact, blast radius            │
             Builds: downside thesis + confidence score    │
                         │                                 │
                         ▼                                 │
                    Bull Rebuttal ◄──────────────────────┘
                         │
                         ▼
                    Judge Agent
                    Compares confidence gap
                    Produces: verdict + conviction
                    Returns: structured JSON

# Run all tests
pytest tests/ -v

# Unit tests only (no graph/DB required)
pytest tests/ -v -m "not integration"

# With coverage
pytest tests/ --cov=mcp_server --cov=src/finance_mcp --cov-report=term-missing