# 🤖 Finance Agent + MCP

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![MCP](https://img.shields.io/badge/MCP-server-7b5cff)
![Tool use](https://img.shields.io/badge/LLM-tool%20use-orange)

An LLM **agent** that answers finance questions by calling **tools** (it never
does the math itself), and exposes those same tools as an **MCP server** so any
MCP client — like Claude Desktop — can use them too.

> **The idea worth stealing:** the tools live in **one registry** and are
> exposed **twice** — to the agent loop *and* to MCP. Define once, no drifting
> schemas. That's the kind of structure that scales on a team.

## ✨ Features

- **Tool-use agent loop** with multi-step tool calls and a printed tool trace.
- **MCP server** (FastMCP) exposing the same tools to any MCP host.
- **Provider-swappable** — Anthropic Claude (default) or OpenAI, one env var.
- **Deterministic finance tools**, unit-tested with **no API key**.

## 🧰 Tools

| Tool | What it computes |
|---|---|
| `compound_interest` | future value of a lump sum |
| `cagr` | compound annual growth rate (%) |
| `loan_payment` | monthly payment for an amortizing loan |
| `future_value_of_savings` | future value of monthly contributions |
| `convert_currency` | FX conversion (static sample rates) |

## 🏗️ Architecture

```mermaid
flowchart LR
    R["Shared tool registry<br/>(finagent.tools)"] --- Agent["Agent loop<br/>Claude / OpenAI"]
    R --- MCP["MCP server<br/>(FastMCP)"]
    U[User] --> Agent --> Ans[Answer + tool trace]
    Host["MCP client<br/>(Claude Desktop)"] --> MCP
```

More in [`docs/architecture.md`](docs/architecture.md).

## 🚀 Quickstart

```bash
# Install (Python 3.10+)
pip install -e .
pip install -r requirements.txt

# Configure
cp .env.example .env       # add ANTHROPIC_API_KEY (or set LLM_PROVIDER=openai)

# Ask the agent (it will call tools and show its work)
python scripts/chat.py "If I save $300/month at 8% for 25 years, how much will I have?"
python scripts/chat.py "Monthly payment on a $250k mortgage at 6.5% over 30 years?"
python scripts/chat.py "Convert 5000 BRL to USD, then grow it at 10% for 5 years."
```

Example output:

```
=== Tool calls ===
  • future_value_of_savings({'monthly_contribution': 300, 'annual_rate_pct': 8, 'years': 25}) -> {'future_value': 285809.08, ...}
=== Answer ===
Saving $300/month at 8% for 25 years grows to about $285,809.
```

## 🔌 Use it from Claude Desktop (MCP)

Run the server:

```bash
python -m finagent.mcp_server
```

Then add it to your Claude Desktop config (`claude_desktop_config.json`). Use the
Python from the env where you installed the package:

```json
{
  "mcpServers": {
    "finance-agent": {
      "command": "python",
      "args": ["-m", "finagent.mcp_server"]
    }
  }
}
```

Claude can now call `compound_interest`, `loan_payment`, etc. directly.

## 🗂️ Project structure

```
finance-agent-mcp/
├── src/finagent/
│   ├── tools.py        # the shared tool registry (pure functions + schemas)
│   ├── agent.py        # provider-swappable tool-use loop
│   ├── mcp_server.py   # exposes the registry over MCP (FastMCP)
│   └── config.py
├── scripts/chat.py     # CLI agent
├── tests/test_tools.py # pure unit tests (no key)
└── docs/architecture.md
```

## ✅ Tests

```bash
pytest -q     # tests the finance math directly — no API key required
```

## 🧭 Roadmap

- [x] Tool registry + 5 finance tools (unit-tested)
- [x] Tool-use agent loop (Claude / OpenAI)
- [x] MCP server exposing the same tools
- [ ] Add a live FX-rate tool + a market-data tool
- [ ] Streaming responses + a small web UI
- [ ] Trace/observability hooks (tie in with project #3)

## 📄 License

MIT — see [LICENSE](LICENSE).

---

Built by **Arturio Amorim Sobrinho** — AI/LLM Engineer.
[GitHub](https://github.com/arturio-amorim) · [LinkedIn](https://www.linkedin.com/in/arturio-amorim-33b60736/)