MCP Agent - AI Expense Tracker

# System Architecture This document describes the architecture of the MCP Agent - AI Expense Tracker system. ## High-Level 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 ``` ## Request Flow ```mermaid sequenceDiagram participant User participant UI as Web UI participant Agent as AI Agent participant LLM as OpenAI GPT-4 participant MCP as MCP Server participant API as API Server participant DB as SQLite DB User->>UI: "Add 50 expense for groceries" UI->>Agent: Send message Agent->>LLM: Process natural language LLM->>Agent: Intent: create_transaction Agent->>MCP: Request tools MCP->>Agent: Available tools list Agent->>MCP: Call create_transaction tool MCP->>API: POST /transactions API->>DB: INSERT transaction DB->>API: Success API->>MCP: Transaction created MCP->>Agent: Tool result Agent->>LLM: Format response LLM->>Agent: Natural language response Agent->>UI: "Added 50.00 expense for groceries" UI->>User: Display response ``` ## Component Breakdown ### 1. API Server (`server/main.py`) **Purpose**: Core backend with REST API and database operations **Technology**: FastAPI + SQLite **Port**: 8002 **Endpoints**: - `GET /transactions` - List transactions - `POST /transactions` - Create transaction - `PUT /transactions/{id}` - Update transaction - `DELETE /transactions/{id}` - Delete transaction - `GET /transactions/search` - Search transactions - `GET /summary` - Financial summary - `GET /summary/categories` - Category breakdown ### 2. MCP Server (`server/mcp_server.py`) **Purpose**: Converts REST API endpoints into MCP tools for AI agents **Technology**: FastAPI-MCP **Port**: 9002 **Function**: - Automatically exposes all FastAPI routes as MCP tools - Handles tool discovery and execution - Provides standardized MCP protocol interface ### 3. AI Agent (`agent/agent.py`) **Purpose**: Intelligent agent that understands natural language and executes tasks **Technology**: Agno Framework + OpenAI GPT-4 **Port**: 7777 **Capabilities**: - Natural language understanding - Tool selection and execution - Context management - Response generation - Multi-turn conversations ### 4. LLM (OpenAI GPT-4) **Purpose**: Language model for understanding and generation **Technology**: OpenAI GPT-4 API **Function**: - Process natural language input - Understand user intent - Select appropriate tools - Generate natural language responses ### 5. Web UI (`client/agent-ui/`) **Purpose**: Modern chat interface for interacting with AI agent **Technology**: Next.js + React + TypeScript **Port**: 3000 **Features**: - Real-time chat interface - Message streaming - Tool call visualization - Responsive design ### 6. Telegram Bot (`client/telegram-bot/`) **Purpose**: Alternative interface via Telegram messaging platform **Technology**: Python Telegram Bot **Features**: - Natural language interaction - Mobile-first experience - Push notifications ### 7. Any MCP Client **Purpose**: Any application that implements MCP protocol can connect **Examples**: - Claude Desktop - Custom MCP clients - Other AI agent frameworks ## Data Flow ```mermaid flowchart LR A[User Input] --> B[Client Interface] B --> C[AI Agent] C --> D{Needs Tool?} D -->|Yes| E[MCP Server] D -->|No| F[Direct Response] E --> G[API Server] G --> H[SQLite Database] H --> G G --> E E --> C C --> I[LLM Processing] I --> C C --> B B --> J[User Output] F --> B style A fill:#E0E7FF style J fill:#E0E7FF style C fill:#FF6600,color:#fff style E fill:#00AA66,color:#fff style G fill:#0066CC,color:#fff ``` ## Technology Stack | Component | Technology | Purpose | |-----------|------------|---------| | **Agent Framework** | Agno | AI agent orchestration | | **LLM** | OpenAI GPT-4 | Natural language processing | | **Protocol** | MCP (Model Context Protocol) | Tool integration standard | | **MCP Integration** | FastAPI-MCP | Convert REST API to MCP | | **Backend** | FastAPI | REST API server | | **Database** | SQLite | Data persistence | | **Frontend** | Next.js + React | Web interface | | **Bot** | Python Telegram Bot | Telegram integration | | **Language** | Python + TypeScript | Implementation | ## Key Features ### 🔌 Model Context Protocol (MCP) MCP is the key innovation that makes this architecture extensible: 1. **Standardized Interface**: All tools use the same protocol 2. **Automatic Discovery**: AI agents automatically discover available tools 3. **Type Safety**: Tools include schemas for inputs and outputs 4. **Extensibility**: Easy to add new tools without changing agent code 5. **Interoperability**: Any MCP-compatible client can use the tools ### 🤖 AI Agent Intelligence The AI agent provides: 1. **Natural Language Understanding**: Users chat in plain English/Russian 2. **Intent Recognition**: Understands what users want to do 3. **Tool Selection**: Automatically chooses appropriate tools 4. **Error Handling**: Gracefully handles failures and retries 5. **Context Awareness**: Maintains conversation context ### 📊 Multi-Client Support The architecture supports multiple client types: 1. **Web UI**: Full-featured browser interface 2. **Telegram Bot**: Mobile-first messaging experience 3. **Direct API**: Programmatic access via REST 4. **MCP Clients**: Any MCP-compatible application ## Deployment Options ### Local Development ```bash # Terminal 1: MCP Server cd server && python start.py --mcp # Terminal 2: API Server cd server && python start.py --api # Terminal 3: AI Agent cd agent && python agent.py # Terminal 4: Web UI (optional) cd client/agent-ui && pnpm dev ``` ### Production Deployment 1. **Backend**: Deploy API and MCP servers to cloud (Railway, Render, Fly.io) 2. **Agent**: Deploy as separate service or container 3. **UI**: Deploy to Vercel, Netlify, or static hosting 4. **Bot**: Deploy to any Python hosting service ## Security Considerations 1. **API Keys**: Stored in `.env`, never committed to git 2. **CORS**: Configured in FastAPI for allowed origins 3. **Input Validation**: Pydantic models validate all inputs 4. **Database**: SQLite for simplicity, can upgrade to PostgreSQL 5. **Authentication**: Currently open, add OAuth/JWT for production ## Scalability ### Current Architecture - Suitable for single-user or small team use - SQLite handles thousands of transactions efficiently - Single-instance deployment ### Scaling Options 1. **Database**: Migrate to PostgreSQL for concurrent users 2. **Caching**: Add Redis for frequently accessed data 3. **Load Balancing**: Multiple API server instances behind LB 4. **Queue System**: Add Celery for async task processing 5. **Monitoring**: Add logging, metrics, and alerts --- **Last Updated**: 2025 **Version**: 1.0.0