# 📊 Chat with Financial Data

> An AI-powered financial data assistant that uses **LLM agents, LangGraph, and Model Context Protocol (MCP)** to answer questions about stocks and financial markets using real-time financial data tools.

---

## 🚀 Overview

**Chat with Financial Data** is an AI-powered financial assistant designed to help users explore and analyze stock market information through natural language.

Instead of manually searching financial websites or running separate queries, users can simply ask questions such as:

* "Give me information about ASII stock."
* "What are the financial metrics of BBCA?"
* "Show me the historical prices of TLKM."
* "What is the P/E ratio of ASII?"
* "Tell me about Astra International."

The application uses an **AI agent** to understand the user's question and dynamically select only the financial data tools needed to answer it.

The project uses **Model Context Protocol (MCP)** to provide a standardized interface between the AI agent and financial data tools.

---

## ✨ Features

### 🤖 AI-Powered Financial Assistant

Users can interact with financial data using natural language instead of manually calling APIs or writing queries.

### 🔌 MCP-Based Tool Integration

Financial data capabilities are exposed through an MCP server, allowing the AI agent to discover and use available tools dynamically.

### 🧠 Intelligent Tool Selection

The AI agent determines which tools are required based on the user's question.

For example:

```text
User:
"Give me information about ASII stock."

        │
        ▼

AI Agent
        │
        ├── search_stock_tool
        │
        └── stock_info

        │
        ▼

Human-readable response
```

The agent does not need to execute every available tool for every question.

### 📈 Financial Data Tools

The current MCP server provides the following tools:

| Tool                | Description                             |
| ------------------- | --------------------------------------- |
| `search_stock_tool` | Searches for a stock ticker and company |
| `stock_info`        | Retrieves basic company information     |
| `historical_prices` | Retrieves historical stock price data   |
| `financial_metrics` | Retrieves key financial metrics         |
| `ping`              | Checks MCP server availability          |

### 💬 Streamlit Chat Interface

The project provides a user-friendly Streamlit interface with:

* Chat-style conversation
* Persistent chat history during the session
* Natural language questions
* Loading indicators
* Human-readable AI responses
* Financial data analysis through MCP tools

### 📝 Chat Logging

Chat interactions can be logged for monitoring and analysis.

The log can include:

* Timestamp
* User question
* AI response
* Runtime
* Tools used
* Token usage
* Estimated API cost

Example:

| Timestamp  | Question                       | Answer |  Runtime | Tools Used        |   Cost |
| ---------- | ------------------------------ | ------ | -------: | ----------------- | -----: |
| 2026-08-03 | Give me information about ASII | ...    | 4.21 sec | stock_info        | $0.002 |
| 2026-08-03 | What is ASII P/E ratio?        | ...    | 3.15 sec | financial_metrics | $0.001 |

Chat logs are stored locally and are excluded from GitHub using `.gitignore`.

---

## 🏗️ System Architecture

```text
                         ┌──────────────────────┐
                         │      User Question   │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │     Streamlit UI     │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │    Financial Agent   │
                         │      LangGraph       │
                         └──────────┬───────────┘
                                    │
                         Selects required tools
                                    │
                                    ▼
                    ┌──────────────────────────────┐
                    │    LangChain MCP Adapter     │
                    └──────────────┬───────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │   Financial Data MCP Server  │
                    │                              │
                    │  ┌────────────────────────┐  │
                    │  │ search_stock_tool      │  │
                    │  │ stock_info             │  │
                    │  │ historical_prices      │  │
                    │  │ financial_metrics      │  │
                    │  │ ping                   │  │
                    │  └────────────────────────┘  │
                    └──────────────┬───────────────┘
                                   │
                                   ▼
                         Financial Data Source
                                   │
                                   ▼
                          AI-generated Response
                                   │
                    ┌──────────────┴───────────────┐
                    ▼                              ▼
             Streamlit UI                    Chat Logger
                                                   │
                                                   ▼
                                          Local CSV Log
```

---

## 🧩 Technology Stack

### AI & Agent

* Python
* OpenAI
* LangChain
* LangGraph

### MCP

* Model Context Protocol
* MCP Python SDK
* LangChain MCP Adapters

### Financial Data

* Yahoo Finance data source

### Application

* Streamlit
* Python AsyncIO

### Logging

* CSV-based chat history
* Runtime tracking
* Token usage tracking
* Estimated API cost tracking

---

## 📁 Project Structure

```text
chat-with-financial-data/
│
├── app/
│   ├── __init__.py
│   │
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── agent.py
│   │   ├── graph.py
│   │   └── mcp_client.py
│   │
│   ├── mcp_servers/
│   │   ├── __init__.py
│   │   │
│   │   └── financial_data/
│   │       ├── __init__.py
│   │       ├── server.py
│   │       └── tools.py
│   │
│   └── logging/
│       ├── __init__.py
│       └── chat_logger.py
│
├── logs/
│   └── .gitkeep
│
├── tests/
│   ├── test_agent.py
│   ├── test_financial_tools.py
│   ├── test_financial_mcp.py
│   └── test_langchain_mcp.py
│
├── .env.example
├── .gitignore
├── LICENSE
├── README.md
├── requirements.txt
└── streamlit_app.py
```

---

## ⚙️ Installation

### 1. Clone the Repository

```bash
git clone https://github.com/fifah123/chat-with-financial-data.git

cd chat-with-financial-data
```

---

### 2. Create a Virtual Environment

#### Windows

```powershell
python -m venv .venv
```

Activate the environment:

```powershell
.venv\Scripts\Activate.ps1
```

If PowerShell blocks script execution, you can activate using:

```powershell
.venv\Scripts\activate
```

---

### 3. Install Dependencies

```powershell
pip install -r requirements.txt
```

---

### 4. Configure Environment Variables

Create a `.env` file in the project root:

```env
OPENAI_API_KEY=your_openai_api_key
```

You can use `.env.example` as a template.

> ⚠️ Never commit your `.env` file or expose your API key publicly.

---

## ▶️ Running the Application

Start the Streamlit application:

```powershell
streamlit run streamlit_app.py
```

The application will open in your browser.

You can then ask questions such as:

```text
Give me information about ASII stock.
```

```text
What are the financial metrics of BBCA?
```

```text
Show me the historical prices of TLKM.
```

```text
What is the P/E ratio of ASII?
```

---

## 🔌 Running the MCP Server

The Financial Data MCP server can be started with:

```powershell
python -m app.mcp_servers.financial_data.server
```

The MCP server communicates through **stdio**, so it may not display a visible response when started directly.

The server is designed to be launched and consumed by the MCP client.

---

## 🧪 Testing

### Test Financial Tools

```powershell
python tests/test_financial_tools.py
```

### Test MCP Server

```powershell
python tests/test_financial_mcp.py
```

### Test LangChain MCP Integration

```powershell
python tests/test_langchain_mcp.py
```

### Test Financial Agent

```powershell
python tests/test_agent.py
```

---

## 🔄 Example Workflow

Suppose the user asks:

```text
Give me information about ASII stock.
```

The system processes the request as follows:

### Step 1 — User Input

```text
Give me information about ASII stock.
```

### Step 2 — AI Agent Understands the Question

The agent identifies that the user is asking for basic stock information.

### Step 3 — Agent Selects Required MCP Tools

The agent may call:

```text
search_stock_tool
stock_info
```

It does not need to call:

```text
historical_prices
financial_metrics
```

unless the question requires them.

### Step 4 — MCP Server Executes the Tools

The MCP server retrieves the requested financial data.

### Step 5 — AI Generates a Human-Friendly Answer

The raw tool output is converted into a natural-language response.

Example:

```text
Astra International Tbk (ASII.JK) is an Indonesian company
listed on the Indonesia Stock Exchange.

Sector: Industrials
Industry: Conglomerates
Currency: IDR
Country: Indonesia
Exchange: Jakarta Stock Exchange
```

---

## 📊 Example Financial Metrics

For example, the `financial_metrics` tool may return:

```text
Ticker: ASII.JK
Market Cap: 203,323,869,233,152
P/E Ratio: 6.47
Forward P/E: 6.61
Price-to-Book: 0.87
Dividend Yield: 7.65%
Return on Equity: 11.98%
Profit Margin: 9.35%
Debt-to-Equity: 41.13
```

The AI agent can then transform this raw data into an understandable financial summary.

---

## 📝 Chat Logging

The application records chat interactions locally.

Example log structure:

```text
logs/
└── chat_history.csv
```

Typical information captured includes:

```text
timestamp
question
answer
runtime_seconds
tools_used
input_tokens
output_tokens
total_tokens
estimated_cost_usd
```

The log file is intentionally excluded from GitHub to prevent personal conversation data and potentially sensitive information from being committed.


---
## ⚠️ Disclaimer

This project is intended for **educational and informational purposes only**.

The financial information provided by the application may be delayed, incomplete, or inaccurate. Nothing in this application should be considered financial, investment, or trading advice.

Always conduct your own research and consult a qualified financial professional before making investment decisions.

---



## ⭐ Acknowledgements

This project uses open-source technologies including:

* OpenAI
* LangChain
* LangGraph
* Model Context Protocol (MCP)
* Streamlit
* Yahoo Finance