# MCP-Powered Financial Intelligence Server

A lightweight financial intelligence server built with **Python and FastAPI** that exposes financial-data capabilities as modular tools. The project combines a tool-based architecture with an interactive agent that interprets user queries, selects the appropriate financial tool, resolves company names to stock/crypto symbols, and retrieves market information using **Yahoo Finance**.

## 🚀 Features

* **Financial Data Retrieval** — Fetch current price, daily percentage change, market state, market capitalization, and trading volume.
* **Intelligent Tool Selection** — Determines which financial tool should handle a user's query.
* **Company & Ticker Resolution** — Converts common company names such as `Apple` or `Tesla` into their corresponding symbols using fuzzy matching.
* **Stock & Cryptocurrency Support** — Supports selected equities and cryptocurrencies such as Apple, Tesla, Microsoft, Infosys, Bitcoin, and Ethereum.
* **Specific Metric Extraction** — Retrieve individual metrics such as price, market cap, volume, or daily change.
* **REST API** — Financial capabilities are exposed through FastAPI endpoints.
* **Interactive CLI Agent** — Query the server through a simple command-line interface.
* **Basic Tool Demonstration** — Includes greeting, addition, and multiplication tools to demonstrate modular tool integration.
* **Error Handling** — Handles invalid symbols, unavailable metrics, and external API/network errors.

## 🏗️ Architecture

```text
                         User Query
                              │
                              ▼
                       ┌─────────────┐
                       │    Agent    │
                       │  agent.py   │
                       └──────┬──────┘
                              │
                    Select Financial Tool
                              │
                 ┌────────────┴────────────┐
                 ▼                         ▼
       FinancialDataFinder        GetFinancialMetric
                 │                         │
                 └────────────┬────────────┘
                              ▼
                    Symbol Resolution
                       RapidFuzz
                              │
                              ▼
                    Financial Data Fetch
                         yfinance
                              │
                              ▼
                    Structured Response
                              │
                              ▼
                           User
```

## 🛠️ Technologies Used

* **Python**
* **FastAPI**
* **Uvicorn**
* **Requests**
* **RapidFuzz**
* **yfinance**
* **REST APIs**

## 📁 Project Structure

```text
MCP_Finance_Server/
│
├── agent.py                  # Interactive agent and tool-selection logic
├── config.py                 # API configuration and request headers
├── main.py                   # FastAPI application and API endpoints
├── requirements.txt          # Python dependencies
│
├── tools/
│   ├── basic_tools.py        # Basic demonstration tools
│   └── finance_tools.py      # Financial data and metric tools
│
└── utils/
    ├── fetch_data.py         # Yahoo Finance data retrieval
    └── matcher.py            # Company/ticker resolution using RapidFuzz
```

## ⚙️ Installation

### 1. Clone the repository

```bash
git clone https://github.com/YOUR_USERNAME/MCP_Finance_Server.git
cd MCP_Finance_Server
```

### 2. Create a virtual environment

```bash
python -m venv venv
```

### 3. Activate the virtual environment

**Windows:**

```bash
venv\Scripts\activate
```

**Linux/macOS:**

```bash
source venv/bin/activate
```

### 4. Install dependencies

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

## ▶️ Running the Server

Start the FastAPI server using Uvicorn:

```bash
uvicorn main:app --reload
```

The server will be available at:

```text
http://127.0.0.1:8000
```

FastAPI's interactive API documentation is available at:

```text
http://127.0.0.1:8000/docs
```

## 📊 API Endpoints

### Health Check

```http
GET /
```

Returns a message confirming that the server is running.

### Greeting

```http
GET /greet?name=Jo
```

### Addition

```http
GET /add?a=10&b=20
```

### Multiplication

```http
GET /multiply?a=10&b=20
```

### Financial Data

```http
GET /tool/FinancialDataFinder?symbol=AAPL
```

Example response:

```json
{
  "Asset Name": "Apple Inc.",
  "Symbol": "AAPL",
  "Current Price": 000.00,
  "Daily Change (%)": 0.00,
  "Market State": "REGULAR",
  "Market Summary": "Apple Inc. is currently trading at ...",
  "Reference": "https://finance.yahoo.com/quote/AAPL"
}
```

### Specific Financial Metric

```http
GET /tool/GetFinancialMetric?symbol=AAPL&metric=marketcap
```

Supported metrics:

```text
price
change
marketcap
volume
```

Example response:

```json
{
  "Symbol": "AAPL",
  "Metric": "marketcap",
  "Value": 0000000000000
}
```

## 🤖 Using the Interactive Agent

Start the agent separately:

```bash
python agent.py
```

The agent accepts natural-language-style queries and determines which financial tool should be used.

Example:

```text
💬 Ask something: price AAPL
```

The agent identifies the appropriate tool, extracts the symbol, calls the FastAPI server, and displays the resulting financial information.

It also supports explicit function-style requests:

```text
FinancialDataFinder("TSLA")
```

or:

```text
GetFinancialMetric("AAPL","MarketCap")
```

## 🔍 Symbol Resolution

The project includes a fuzzy-matching layer using **RapidFuzz**.

For example, known company names can be resolved to their corresponding symbols:

| Company / Asset | Symbol  |
| --------------- | ------- |
| Apple           | AAPL    |
| Google          | GOOG    |
| Tesla           | TSLA    |
| Infosys         | INFY    |
| Microsoft       | MSFT    |
| Bitcoin         | BTC-USD |
| Ethereum        | ETH-USD |

This allows the financial tools to accept either recognized company names or ticker symbols.

## 🔄 How It Works

1. The user enters a financial query.
2. The agent analyzes the query and determines the required tool.
3. The requested symbol/company is extracted.
4. The symbol resolver validates or maps the input to a known ticker.
5. The financial tool requests market information through `yfinance`.
6. Relevant financial metrics are extracted.
7. The server returns a structured JSON response.
8. The agent displays the result to the user.

## 🎯 Project Objective

The goal of this project is to demonstrate how financial capabilities can be organized into **modular, callable tools** and exposed through a lightweight API server. It provides a foundation for integrating financial data retrieval with agent-based applications and MCP-style tool architectures.

## 🔮 Future Enhancements

* Expand support for additional stocks, ETFs, indices, and cryptocurrencies.
* Replace rule-based tool selection with an LLM-based agent.
* Implement the official MCP protocol for native MCP client compatibility.
* Add authentication and API access control.
* Add caching to reduce repeated financial-data requests.
* Add historical price and charting capabilities.
* Add Docker-based deployment.
* Add automated testing and CI/CD.
* Build a web interface for interacting with the financial tools.

## 📌 Disclaimer

Financial information retrieved by this project is intended for **educational and software-development purposes only**. It should not be considered financial advice. Market data may be delayed, incomplete, or unavailable depending on the external data provider.

## 👩‍💻 Author

**Shanthini Joshitha**

Built as a software engineering project exploring **FastAPI, financial APIs, intelligent tool selection, and MCP-style architectures**.