┌─────────────────────────────────────────────────────────┐
│                   CLIENT LAYER                          │
│   Claude Desktop  │  Gradio UI  │  CLI  │  Telegram     │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol (JSON-RPC)
┌────────────────────────▼────────────────────────────────┐
│              LANGGRAPH AGENT (Orchestrator)              │
│  Multi-step reasoning · Report generation · Triage      │
│  Claude API · StateGraph · Human-in-the-loop            │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Tool Calls
┌────────────────────────▼────────────────────────────────┐
│              FINWATCH MCP SERVER                        │
│                                                         │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │ get_portfolio │ │ analyze_risk │ │ detect_anomaly │  │
│  └──────────────┘ └──────────────┘ └────────────────┘  │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │search_filings│ │get_market_kpi│ │compliance_check│  │
│  └──────────────┘ └──────────────┘ └────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                    DATA LAYER                            │
│  SQLite (prices, KPIs)  │  ChromaDB (SEC filings, RAG)  │
│  Alpha Vantage · Finnhub · FRED · SEC EDGAR             │
└─────────────────────────────────────────────────────────┘

# Clone the repo
git clone https://github.com/geraldo96/finwatch-mcp.git
cd finwatch-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev]"

# Copy environment template
cp .env.example .env
# Edit .env with your API keys

# Start the MCP server (Streamable HTTP)
uv run python -m src.mcp_server.server

# The server runs on http://localhost:8080/mcp

{
  "mcpServers": {
    "finwatch": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

# Interactive CLI mode
uv run python -m src.agent.cli

# Example queries:
# > What's my current portfolio allocation?
# > Is my tech exposure within compliance limits?
# > Show me anomalies from the last week and explain them

docker compose up
# MCP server: http://localhost:8080/mcp
# Gradio UI:  http://localhost:7860

finwatch-mcp/
├── src/
│   ├── mcp_server/
│   │   ├── server.py          # MCP server entrypoint (Streamable HTTP)
│   │   ├── tools/
│   │   │   ├── portfolio.py   # get_portfolio tool
│   │   │   ├── risk.py        # analyze_risk tool
│   │   │   ├── anomaly.py     # detect_anomaly tool
│   │   │   ├── filings.py     # search_filings tool (RAG)
│   │   │   ├── market_kpi.py  # get_market_kpi tool
│   │   │   └── compliance.py  # compliance_check tool
│   │   └── config.py          # Server configuration
│   ├── agent/
│   │   ├── graph.py           # LangGraph StateGraph definition
│   │   ├── nodes.py           # Agent nodes (reason, act, report)
│   │   ├── state.py           # Agent state schema
│   │   └── cli.py             # Interactive CLI client
│   ├── data/
│   │   ├── ingester.py        # Data fetching & sync logic
│   │   ├── models.py          # SQLAlchemy / Pydantic models
│   │   └── db.py              # Database connection & queries
│   └── rag/
│       ├── embeddings.py      # BAAI embedding pipeline
│       ├── indexer.py         # SEC filing indexer
│       └── retriever.py       # ChromaDB retrieval
├── tests/
│   ├── test_tools.py          # Unit tests for MCP tools
│   ├── test_agent.py          # Agent integration tests
│   └── test_data.py           # Data layer tests
├── scripts/
│   ├── seed_data.py           # Seed DB with sample portfolio
│   ├── ingest_filings.py      # Download & index SEC filings
│   └── demo.py                # Full demo walkthrough
├── docs/
│   ├── ARCHITECTURE.md        # Detailed architecture docs
│   └── TOOLS.md               # MCP tool specifications
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── .env.example
└── README.md