# MCP Agent - AI Expense Tracker

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![GitHub stars](https://img.shields.io/github/stars/dev-muhammad/MCPAgent.svg?style=social&label=Star)](https://github.com/dev-muhammad/MCPAgent)
[![Presentation](https://img.shields.io/badge/Slides-Live-green.svg)](https://dev-muhammad.github.io/MCPAgent/)

**A practical demonstration of AI Agent implementation with custom MCP server.**

This project showcases how to build intelligent AI agents using the Model Context Protocol (MCP). Through a real-world expense tracking application, you'll see how AI agents can interact with tools, databases, and APIs to perform complex tasks through natural conversation.

## 🎯 What This Demonstrates

- **Custom MCP Server**: Build your own MCP server using FastAPI
- **AI Agent Integration**: Connect AI agents to tools via MCP protocol
- **Real-world Application**: Practical expense tracking use case
- **Natural Language Interface**: Chat with AI to manage your data
- **Tool Discovery**: AI automatically discovers and uses available tools

## 🏗️ Architecture

```mermaid
graph TB
    subgraph "Backend"
        API[API Server<br/>FastAPI + SQLite<br/>Port: 8002]
        MCP[MCP Server<br/>FastAPI-MCP<br/>Port: 9002]
    end

    subgraph "AI Layer"
        Agent[AI Agent<br/>Agno Framework<br/>Port: 7777]
        LLM[LLM]
    end

    subgraph "Client Layer"
        UI[Web UI<br/>Next.js + React<br/>Port: 3000]
        Telegram[Telegram Bot<br/>Python Telegram Bot]
        AnyClient[Any MCP Client]
    end

    subgraph "End Users"
        User1[User]
        User2[User]
        User3[User]
    end

    API -->|Exposes REST API| MCP
    MCP -->|MCP Protocol| Agent
    MCP -.->|MCP Protocol| AnyClient
    Agent -->|API Calls| LLM
    Agent -->|Serves| UI
    Agent -->|Serves| Telegram
    UI -->|Interacts| User1
    Telegram -->|Interacts| User2
    AnyClient -.->|Interacts| User3

    style API fill:#0066CC,color:#fff
    style MCP fill:#00AA66,color:#fff
    style Agent fill:#FF6600,color:#fff
    style LLM fill:#8B5CF6,color:#fff
    style UI fill:#06B6D4,color:#fff
    style Telegram fill:#06B6D4,color:#fff
```

> 📖 **For detailed architecture documentation, request flows, and deployment options, see [ARCHITECTURE.md](ARCHITECTURE.md)**

## 🚀 Features

- **AI-Powered Agent**: Natural language expense tracking using OpenAI GPT-4
- **SQLite Database**: Persistent storage for all transactions
- **Auto-Initialization**: Automatic database setup with seed data
- **MCP Integration**: Extensible tool system for AI agents
- **REST API**: Full CRUD operations for expense management
- **Multiple Clients**: Web UI, Telegram bot, and direct agent interface
- **Smart Categorization**: Automatic expense categorization and insights
- **Currency-Agnostic**: Clean numerical formatting without currency symbols

## 📁 Project Structure

```text
MCPAgent/
├── .env.example       # Environment variables template
├── .env               # Your configuration (create from .env.example)
├── agent/             # AI Agent with Agno framework
│   ├── agent.py       # Main agent with system prompts
│   └── agno.db        # Agent's SQLite database
├── server/            # FastAPI backend with MCP server
│   ├── main.py        # API routes and endpoints
│   ├── store.py       # SQLite data store
│   ├── models.py      # Pydantic data models
│   ├── config.py      # Configuration settings
│   ├── mcp_server.py  # MCP protocol server
│   ├── start.py       # Server initialization & startup
│   └── expenses.db    # Transactions database
└── client/
    ├── agent-ui/      # Next.js web interface
    └── telegram-bot/  # Telegram bot client
```

## 🏃 Quick Start

### 1. Install Dependencies

```bash
# Install Python dependencies
pip install -r server/requirements.txt
pip install agno openai python-dotenv
```

### 2. Set Environment Variables

```bash
# Copy example and add your API key
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
```

### 3. Initialize and Start Servers

```bash
cd server

# Check dependencies and initialize database with seed data
python start.py

# Start MCP server (in one terminal)
python start.py --mcp

# Start API server (in another terminal)
python start.py --api
```

### 4. Run the AI Agent

```bash
cd agent
python agent.py
```

Access the agent at: <http://localhost:7777>

## 💬 Usage Examples

Chat with the AI agent:

- "Add a 50 grocery expense"
- "I spent 75 on dinner last night"
- "How much did I spend on food this month?"
- "Show me my financial summary"
- "What's my biggest expense category?"
- "Add income of 5000 from salary"

## 🛠️ Tech Stack

- **Protocol**: Model Context Protocol (MCP) - Custom server implementation
- **Agent Framework**: [Agno](<https://docs.agno.com/>)
- **AI Model**: OpenAI GPT-4
- **MCP Server**: FastAPI-MCP (converts REST API to MCP tools)
- **Backend**: FastAPI + SQLite
- **Frontend**: Next.js + React
- **Bot**: Python Telegram Bot

## 🔌 How MCP Works Here

1. **FastAPI Backend** (`server/main.py`) - Standard REST API with CRUD operations
2. **MCP Server** (`server/mcp_server.py`) - Wraps the API and exposes it as MCP tools
3. **AI Agent** (`agent/agent.py`) - Connects to MCP server and automatically discovers tools
4. **Natural Language** - User chats with agent, agent uses tools to complete tasks

```text
User Input → AI Agent → MCP Server → FastAPI → SQLite
              ↓
         Tool Selection & Execution
              ↓
         Natural Language Response
```

## 📊 API Endpoints

- `GET /transactions` - List all transactions
- `POST /transactions` - Create new transaction
- `PUT /transactions/{id}` - Update transaction
- `DELETE /transactions/{id}` - Delete transaction
- `GET /transactions/search?q=` - Search transactions
- `GET /summary` - Financial summary
- `GET /summary/categories` - Category breakdown
- `GET /health` - Health check

Full API docs: <http://localhost:8002/docs>

## 🎯 Server Commands

The `start.py` script manages server initialization and startup:

```bash
# Check dependencies and initialize database
python start.py

# Start MCP server only
python start.py --mcp

# Start API server only  
python start.py --api

# Custom ports
python start.py --api --port 8000
python start.py --mcp --port 9000
```

**What `start.py` does:**

- ✅ Checks all required dependencies
- ✅ Verifies environment variables
- ✅ Initializes SQLite database
- ✅ Seeds database with sample transactions (first run only)
- ✅ Starts requested server(s)

## 🤖 Agent Capabilities

The AI agent can:

- Create, read, update, and delete expenses
- Search transactions by keyword
- Generate financial summaries and insights
- Analyze spending patterns by category
- Provide budgeting recommendations
- Filter transactions by date, type, or category

## 🔧 Configuration

### Environment Variables (`.env`)

```bash
OPENAI_API_KEY=your_key_here    # Required for AI agent
HOST=localhost                  # Server host
PORT=8002                       # API server port
MCP_HOST=localhost              # MCP server host
MCP_PORT=9002                   # MCP server port
```

### Server Configuration (`server/config.py`)

- Server host/port settings
- Database path
- MCP server configuration

### Agent Configuration (`agent/agent.py`)

- AI model selection (default: gpt-4.1)
- System prompt customization
- Agent behavior settings
- Database location

## 🔍 Troubleshooting

**Dependencies missing?**

```bash
pip install -r server/requirements.txt
pip install agno openai python-dotenv
```

**Database not initialized?**

```bash
cd server && python start.py
```

**Port already in use?**

```bash
python start.py --api --port 8003
python start.py --mcp --port 9003
```

**Agent can't connect to MCP?**

- Ensure MCP server is running: `python start.py --mcp`
- Check MCP URL in `agent/agent.py` (default: <http://localhost:9002/mcp>)

## 📊 Presentation

This project includes a presentation about practical AI agent implementation:

### 🌐 Live Demo

**[View Slides Online →](https://dev-muhammad.github.io/MCPAgent/)**

### 📁 Local Files

- **English Slides**: [docs/en/index.html](docs/en/index.html)
- **Russian Slides**: [docs/ru/index.html](docs/ru/index.html)

Open the slides to learn more about AI agents and MCP protocol.

## 📚 Resources

This project is built with and inspired by amazing open-source projects:

- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io)** - Standard protocol for connecting AI agents to tools
- **[FastAPI-MCP](https://github.com/jlowin/fastapi-mcp)** - FastAPI integration for MCP servers
- **[Agno](https://docs.agno.com)** - Modern framework for building AI agents
- **[Agent UI](https://github.com/agno-agi/agent-ui)** - Beautiful chat interface for AI agents

**Special thanks** to these projects and their maintainers for making AI agent development accessible and enjoyable! 🙏

## 📝 License

MIT

---

Built with ❤️ using AI agents and MCP