# 🏦 Financial Intelligence MCP Server

A **production-grade Model Context Protocol (MCP) server** that exposes financial ML tools to any MCP-compatible AI client (Claude Desktop, Cursor, etc.).

Built entirely with **free, open-source tools** — no paid APIs required.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│              MCP-Compatible Client                              │
│         (Claude Desktop / Cursor / Any LLM)                     │
└─────────────────────┬───────────────────────────────────────────┘
                      │ MCP Protocol (stdio)
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                  financial-mcp-server                           │
│                     server.py                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Tool Router                           │   │
│  └──┬────────────┬────────────┬───────────┬─────────────────┘   │
│     │            │            │           │           │          │
│     ▼            ▼            ▼           ▼           ▼          │
│ ┌───────┐  ┌─────────┐  ┌────────┐  ┌────────┐  ┌─────────┐   │
│ │  RAG  │  │Anomaly  │  │Contract│  │Vendor  │  │ Drift   │   │
│ │Search │  │Detect.  │  │Summary │  │ Graph  │  │Monitor  │   │
│ └───┬───┘  └────┬────┘  └───┬────┘  └───┬────┘  └────┬────┘   │
└─────┼───────────┼───────────┼───────────┼────────────┼─────────┘
      │           │           │           │            │
      ▼           ▼           ▼           ▼            ▼
   FAISS +    sklearn       Ollama      Neo4j /    Evidently
 sentence-  IsolationF.   (local LLM)  NetworkX    AI / KS
transformers  (free)      (free)       (free)      Test (free)
```

---

## 🛠️ Tools

| Tool | Description | Free Stack Used |
|------|-------------|-----------------|
| `search_financial_docs` | RAG over financial PDFs/docs | FAISS + sentence-transformers + Ollama |
| `analyze_expense_pattern` | Anomaly detection on transactions | scikit-learn IsolationForest |
| `summarize_contract` | Extract key clauses from contracts | Ollama Mistral + regex fallback |
| `get_vendor_relationships` | Query vendor knowledge graph | Neo4j Community + NetworkX fallback |
| `monitor_model_drift` | Detect data/feature drift in models | Evidently AI + scipy KS test fallback |

---

## 💸 100% Free Stack

| Component | Tool | Cost |
|-----------|------|------|
| LLM | Ollama + Mistral 7B (local) | **FREE** |
| Embeddings | sentence-transformers all-MiniLM-L6-v2 | **FREE** |
| Vector Store | FAISS (Meta) | **FREE** |
| Anomaly Detection | scikit-learn IsolationForest | **FREE** |
| Graph Database | Neo4j Community Edition | **FREE** |
| Drift Monitoring | Evidently AI open-source | **FREE** |
| MCP Framework | Anthropic MCP Python SDK | **FREE** |

---

## 🚀 Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/YOUR_USERNAME/financial-mcp-server.git
cd financial-mcp-server

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Start Ollama (free local LLM)

```bash
# Install Ollama from https://ollama.com (free)
ollama serve
ollama pull mistral   # ~4GB download, one time
```

### 3. Add Your Documents (optional)

```bash
# Drop any .txt, .md, or .pdf files into:
data/sample_docs/

# Index them (auto-happens on first run, or manually):
python -c "from tools.rag_search import _load_or_build_index; _load_or_build_index()"
```

### 4. Run the MCP Server

```bash
python server.py
```

### 5. Connect to Claude Desktop

Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "financial-intelligence": {
      "command": "python",
      "args": ["/absolute/path/to/financial-mcp-server/server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/financial-mcp-server"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see the 🔧 tools icon appear.

---

## 🐳 Docker Setup (with Neo4j)

```bash
# Start Neo4j Community Edition + MCP server
docker-compose up -d

# Check logs
docker-compose logs -f mcp-server
```

Neo4j browser available at: http://localhost:7474

---

## 🧪 Run Tests

```bash
pip install pytest
pytest tests/ -v
```

---

## 💬 Example Claude Desktop Conversations

Once connected, ask Claude:

> *"Search my financial documents for information about payment terms with TechVendor Solutions"*

> *"Analyze these transactions for anomalies: [paste JSON list]"*

> *"Summarize this contract and flag any risky clauses: [paste contract text]"*

> *"What vendors are related to TechVendor Solutions and what's their risk level?"*

> *"Check if the fraud_detector model has drifted and whether it needs retraining"*

---

## 📁 Project Structure

```
financial-mcp-server/
├── server.py                  # MCP server — tool registry & routing
├── tools/
│   ├── rag_search.py          # search_financial_docs
│   ├── anomaly_detection.py   # analyze_expense_pattern
│   ├── contract_summary.py    # summarize_contract
│   ├── vendor_graph.py        # get_vendor_relationships
│   └── drift_monitor.py       # monitor_model_drift
├── data/
│   └── sample_docs/           # Drop your financial docs here
├── tests/
│   └── test_tools.py          # pytest test suite
├── .github/workflows/
│   └── ci.yml                 # GitHub Actions CI
├── Dockerfile
├── docker-compose.yml         # Includes Neo4j Community Edition
├── requirements.txt
└── claude_desktop_config.json # Copy into Claude Desktop config
```

---

## 🔗 Related Projects

- [Financial-RAG-Pipeline](https://github.com/BharathiDonku7/Financial-Rag-Pipeline) — Standalone RAG system (precursor to this project)

---

## 📄 License

MIT License — free to use, modify, and distribute.