# FinChat - MCP-Powered Personal Finance Assistant

FinChat is an AI-powered personal finance assistant built using the **Model Context Protocol (MCP)**. It exposes financial management and analytics capabilities as reusable tools that can be discovered and executed by MCP-compatible AI clients.

The project demonstrates how Large Language Models (LLMs) can interact with external systems through structured tools to perform tasks such as transaction management, spending analysis, financial insights generation, and savings goal tracking.

> **Note:** This project currently uses synthetic/dummy financial data for demonstration purposes. It does not connect to real bank accounts or personal financial information.

---

## ✨ Features at a Glance

- **Transaction Management** – Add, retrieve, and query financial transactions
- **Spending Analytics** – Analyze spending by category and generate financial insights
- **Goal Tracking** – Set, update, and monitor progress toward savings goals
- **MCP Integration** – Discover and execute tools through standardized protocol
- **AI-Ready** – Works seamlessly with MCP-compatible AI clients (Claude, Cursor, etc.)

---

## 🚀 Project Overview

Traditional chatbots can answer questions but often lack access to user-specific data and external capabilities.

FinChat addresses this by providing an MCP server that exposes financial tools to AI agents. Instead of hardcoding every workflow, the AI agent can understand user requests, select the appropriate tool, execute it, and generate meaningful responses.

**Example User Interaction:**

```
User: "How much did I spend on groceries in July?"

Agent Workflow:
  User Request → AI Agent → MCP Tool Discovery → 
  get_spending_summary() → Financial Analysis → Response
```

---

## 🏗️ Architecture

```
         User Input
            |
            ▼
   MCP-Compatible AI Client
   (Claude / Cursor / Agent)
            |
            ▼
       MCP Protocol
            |
            ▼
    FinChat MCP Server
            |
    ┌───────┼───────┐
    ▼       ▼       ▼
Transactions Analytics Goals
    |       |       |
    └───────┼───────┘
            ▼
   Financial Data Storage
      (Synthetic JSON)
```

---

## 🔌 Why Model Context Protocol (MCP)?

MCP provides a standardized interface for AI applications to discover and interact with external tools.

**Benefits:**

- ✓ Standardized tool discovery and execution
- ✓ Structured tool inputs and outputs
- ✓ Separation between AI reasoning and application logic
- ✓ Reusable tools across different AI clients
- ✓ Easier development of agent-based applications

---

## 🧠 MCP Server Design

The project follows a clean separation-of-concerns architecture:

```
mcp_server.py          tools/
├─ Register tools      ├─ add_transactions.py
├─ Expose schemas      ├─ query_transactions.py
└─ Handle I/O          ├─ spending_summary.py
                       ├─ financial_insights.py
                       ├─ set_financial_goal.py
                       ├─ update_financial_goal.py
                       └─ get_goal_progress.py
```

This keeps the MCP layer independent from the underlying financial logic.

---

## 🛠️ Tech Stack

| Category | Technology |
|----------|------------|
| **Protocol** | Model Context Protocol (MCP) |
| **Framework** | FastMCP |
| **Language** | Python 3.8+ |
| **Data Storage** | JSON (development), SQLite (planned) |
| **IDE** | VS Code |

---

## 🔌 Available MCP Tools

### Transaction Management

#### `add_transactions`
Adds financial transactions into the system.

**Example:**
```
User: "Add a $50 grocery expense at Walmart today"
```

#### `get_transactions`
Retrieves stored financial transactions with filtering capabilities.

**Example queries:**
- "Show my transactions from July"
- "Show all restaurant expenses"

---

### 📊 Spending Analytics

#### `get_spending_summary`
Generates spending summaries and category-based analysis.

**Example queries:**
- "How much did I spend this month?"
- "Show my grocery spending in July"
- "Break down expenses by category"

#### `get_financial_insights`
Analyzes spending behavior and generates financial observations.

**Example queries:**
- "Where am I spending the most?"
- "What expenses can I reduce?"
- "Analyze my spending patterns"

---

### 🎯 Financial Goal Management

#### `set_financial_goal`
Creates new financial goals.

**Example:**
```
User: "I want to save $50,000 by 2028"
```

**Stores:**
- Goal name
- Target amount
- Current savings
- Target date

#### `update_financial_goal`
Updates an existing financial goal.

**Example:**
```
User: "I saved another $5,000 toward my savings goal"
```

#### `get_goal_progress`
Tracks progress toward financial goals.

**Example queries:**
- "How much progress have I made?"
- "How much do I need to save monthly?"

---

## 📂 Project Structure

```
FinChat/
│
├── mcp_server.py              # MCP server entry point
│
├── tools/                      # Business logic & calculations
│   ├── add_transactions.py
│   ├── query_transactions.py
│   ├── spending_summary.py
│   ├── financial_insights.py
│   ├── set_financial_goal.py
│   ├── update_financial_goal.py
│   └── get_goal_progress.py
│
├── data/                       # Data storage
│   ├── transactions.json
│   └── financial_goals.json
│
├── requirements.txt
├── pyproject.toml
└── README.md
```

---

## ⚙️ Installation & Setup

**1. Clone the repository:**
```bash
git clone <repository-url>
cd FinChat
```

**2. Create and activate virtual environment:**

*Windows (PowerShell):*
```bash
python -m venv .venv
.venv\Scripts\activate
```

*macOS/Linux:*
```bash
python -m venv .venv
source .venv/bin/activate
```

**3. Install dependencies:**
```bash
pip install -r requirements.txt
```

---

## ▶️ Running the MCP Server

```bash
python mcp_server.py
```

The MCP server runs using stdio transport and communicates with MCP-compatible AI clients.

---

## 💡 Quick Usage Example

Once the server is running, connect via an MCP client:

```python
# Example: Query spending by category
user_message = "How much did I spend on groceries in July?"

# Agent discovers available tools → selects get_spending_summary
# → executes with filters → returns analysis
```

---

## 🔐 Data Privacy & Security

**Current implementation (development only):**
- ✓ Synthetic financial data only
- ✗ No real bank connections
- ✗ No personal financial records
- ✗ No external financial APIs

**Production requirements:**
- Secure authentication (OAuth 2.0)
- Encrypted data storage
- Database-level access control
- Banking API integrations
- Compliance & regulatory review

---

## ⚠️ Current Limitations

- Uses local JSON storage (single-user)
- Designed for demonstration purposes
- Does not connect to banking providers
- Does not provide regulated financial advice
- Requires manually provided transaction data

---

## 🔮 Future Improvements

- [ ] Replace JSON with SQLite/PostgreSQL
- [ ] Add multi-user support with authentication
- [ ] Integrate real banking APIs (Plaid, etc.)
- [ ] Build automated savings recommendations
- [ ] Add interactive web dashboard
- [ ] Implement advanced financial planning
- [ ] Add budget forecasting
- [ ] Generate monthly financial reports

---

## 👨‍💻 About This Project

Built as a hands-on exploration of:

- Model Context Protocol (MCP) architecture
- LLM tool integration and function calling
- AI agent design patterns
- Structured data interaction with AI systems

**Learning Goals:**
- Understand how AI agents discover and execute external tools
- Build production-ready MCP servers
- Design AI-ready application architectures
- Implement secure tool orchestration

---

## 📝 License

MIT License

---

*Built as a portfolio project to demonstrate AI/ML capabilities and modern LLM application architecture.*