MCP Agent - AI Expense Tracker

# Expense Tracker Telegram Bot A simple Telegram bot that connects to the Agno Agent API to provide expense tracking functionality through Telegram messages. ## 🚀 Features - **Natural Language Interface**: Chat with your expense tracker using natural language - **Real-time Responses**: Get instant responses from the Agno agent - **Session Management**: Maintains conversation context per user - **Error Handling**: Graceful error handling with user-friendly messages - **Status Monitoring**: Check bot and agent connectivity - **Markdown Support**: Rich text formatting in responses ## 📋 Prerequisites 1. **Telegram Bot Token**: Get one from [@BotFather](https://t.me/BotFather) on Telegram 2. **Agno Agent**: Running expense tracker agent at `http://localhost:7777` 3. **Python 3.8+**: Required for the bot ## 🛠️ Setup ### 1. Install Dependencies ```bash pip install -r requirements.txt ``` ### 2. Configure Environment Variables Copy the example config and set your values: ```bash cp config.env.example config.env ``` Edit `config.env` with your settings: ```bash # Required: Get from @BotFather TELEGRAM_BOT_TOKEN=your_bot_token_here # Optional: Agno agent configuration AGNO_API_URL=http://localhost:7777 AGENT_ID=expense-tracker-agent DEFAULT_USER_ID=MUHAMMAD ``` ### 3. Set Environment Variables ```bash # Load from config file export $(cat config.env | xargs) # Or set directly export TELEGRAM_BOT_TOKEN="your_bot_token_here" export AGNO_API_URL="http://localhost:7777" export AGENT_ID="expense-tracker-agent" export DEFAULT_USER_ID="MUHAMMAD" ``` ### 4. Run the Bot ```bash python bot.py ``` ## 🤖 Bot Commands ### Available Commands - `/start` - Welcome message and introduction - `/help` - Show help and usage examples - `/status` - Check bot and agent connectivity status ### Example Conversations ``` User: What was my last expense? Bot: Your last record is: - Title: Uber Ride - Amount: $18.75 (expense) - Category: Transportation - Description: Ride to airport User: Show me my spending summary Bot: Here's your financial summary: - Total Income: $6,350.00 - Total Expenses: $1,915.05 - Net Balance: $4,434.95 User: Add a $25 coffee expense Bot: ✅ Transaction added successfully! - Title: Coffee expense - Amount: $25.00 - Type: Expense ``` ## 🔧 Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `TELEGRAM_BOT_TOKEN` | *Required* | Bot token from @BotFather | | `AGNO_API_URL` | `http://localhost:7777` | Agno agent API endpoint | | `AGENT_ID` | `expense-tracker-agent` | Agent ID to use | | `DEFAULT_USER_ID` | `MUHAMMAD` | Default user ID for agent | ### API Integration The bot uses the Agno Agent API endpoint: ``` POST /agents/{agent_id}/runs ``` With form data: - `message`: User's message - `stream`: false (synchronous responses) - `session_id`: telegram_{user_id} - `user_id`: {DEFAULT_USER_ID}_{telegram_user_id} ## 🔍 Troubleshooting ### Common Issues 1. **Bot Token Error** ``` Error: Please set TELEGRAM_BOT_TOKEN environment variable ``` Solution: Get token from @BotFather and set the environment variable 2. **Agent Connection Failed** ``` Error: Failed to connect to Agno agent ``` Solution: Ensure Agno agent is running at the configured URL 3. **API Timeout** ``` Error: Request timeout ``` Solution: Check if the expense tracker MCP server is running ### Debug Mode Enable debug logging by modifying the logging level in `bot.py`: ```python logging.basicConfig(level=logging.DEBUG) ``` ### Testing Connection Use the `/status` command to check connectivity: - ✅ All systems operational - ⚠️ Partial service (bot works, agent issues) - ❌ Service unavailable ## 📊 Usage Examples ### Expense Tracking - "Add $50 grocery expense" - "Record a $25 coffee purchase" - "I spent $100 on gas today" ### Queries - "What's my balance?" - "Show last 5 transactions" - "How much did I spend on food?" - "What was my biggest expense?" ### Analytics - "Show spending by category" - "Monthly expense summary" - "Compare this month to last month" ## 🔒 Security Notes - Bot tokens should be kept secret - User IDs are combined with Telegram user IDs for isolation - Sessions are scoped per Telegram user - No sensitive data is logged (only metadata) ## 🛠️ Development ### File Structure ``` telegram-bot/ ├── bot.py # Main bot application ├── requirements.txt # Python dependencies ├── config.env.example # Configuration template └── README.md # This documentation ``` ### Extending the Bot - Add new commands in the `main()` function - Modify message handling in `handle_message()` - Customize response formatting - Add user authentication/authorization - Implement conversation state management ## 📚 Dependencies - **python-telegram-bot**: Telegram Bot API wrapper - **requests**: HTTP client for Agno API calls ## 🤝 Integration Flow 1. User sends message to Telegram bot 2. Bot forwards message to Agno Agent API 3. Agent processes message using expense tracker tools 4. Agent returns formatted response 5. Bot sends response back to user The bot maintains session continuity by using consistent session IDs per user, allowing for contextual conversations about expenses and financial data.