MCP Agent - AI Expense Tracker

MCP代理 - AI费用追踪器

一个使用自定义MCP服务器实现AI代理的实际演示。

这个项目展示了如何使用模型上下文协议（MCP）构建智能AI代理。通过一个实际的费用跟踪应用程序，您将看到AI代理如何与工具、数据库和API进行交互，以通过自然对话执行复杂任务。

🎯 这表明了什么

• 自定义MCP服务器使用FastAPI构建你自己的MCP服务器
• AI代理集成通过MCP协议将AI代理连接到工具
• 实际应用实际的费用跟踪用例
• 自然语言接口与AI聊天来管理你的数据
• 工具发现AI自动发现并使用可用工具

🏗️ 建筑学

graph TB
    subgraph "Backend"
        API[API Server
FastAPI + SQLite
Port: 8002]
        MCP[MCP Server
FastAPI-MCP
Port: 9002]
    end

    subgraph "AI Layer"
        Agent[AI Agent
Agno Framework
Port: 7777]
        LLM[LLM]
    end

    subgraph "Client Layer"
        UI[Web UI
Next.js + React
Port: 3000]
        Telegram[Telegram Bot
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

📖（书本的符号，可翻译为“书”或根据上下文具体含义进行翻译，但在此仅提供符号对应的直观表达） 如需详细的架构文档、请求流程以及部署选项，请参阅 ARCHITECTURE.md 翻译为中文是：“架构.md”（这里的“.md”通常表示Markdown文件格式，但在中文语境下，我们通常不会特别翻译文件扩展名，除非有特定的翻译需求或习惯）。所以，完整的翻译可以是“架构文档（Markdown格式）”或简单地称为“架构.md”（如果上下文已经明确了这是Markdown文件）

🚀 功能

• AI驱动的智能体使用OpenAI GPT-4进行自然语言支出追踪
• SQLite 数据库所有交易的持久化存储
• 自动初始化使用种子数据自动设置数据库
• MCP 集成可扩展的人工智能代理工具系统
• REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口）费用管理的完整CRUD操作
• 多个客户端网页用户界面、Telegram机器人和直接代理接口
• 智能分类自动费用分类及深入见解
• 不依赖特定货币清理后的数字格式，不包含货币符号

📁 项目结构

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

🏃 快速入门

1. 安装依赖项

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

2. 设置环境变量

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

3. 初始化并启动服务器

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. 运行AI代理

cd agent
python agent.py

访问代理的方式为：

💬 使用示例

与AI代理聊天：

• “增加50元的杂货费用”
• “我昨晚晚餐花了75（元/美元等，根据上下文确定具体货币单位）。”
• “我这个月在食物上花了多少钱？”
• “给我看一下我的财务总结”
• “我最大的开销类别是什么？”
• “增加5000元的工资收入”

🛠️ 技术栈

• 协议模型上下文协议（MCP）- 自定义服务器实现
• 代理框架: 阿尼奥
• 人工智能模型OpenAI GPT-4
• MCP服务器FastAPI-MCP（将REST API转换为MCP工具）
• 后端FastAPI + SQLite
• 前端Next.js + React
• 机器人Python Telegram 机器人

🔌 这里MCP的工作原理

1. FastAPI 后端 (server/main.py标准的REST API，支持CRUD操作
2. MCP 服务器 (server/mcp_server.py- 包装API并将其作为MCP工具暴露出来
3. 人工智能代理 (agent/agent.py- 连接到MCP服务器并自动发现工具
4. 自然语言 - 用户与客服聊天，客服使用工具完成任务

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

📊 API 接口

• GET /transactions - 列出所有交易
• POST /transactions - 创建新交易
• PUT /transactions/{id} - 更新交易
• DELETE /transactions/{id} - 删除交易
• GET /transactions/search?q= - 搜索交易
• GET /summary - 财务概要
• GET /summary/categories - 类别细分
• GET /health - 健康检查

完整的API文档：

🎯 服务器命令

这个（或“该”） start.py 脚本管理服务器的初始化和启动：

# 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

什么 start.py does: （这个短语本身在中文里没有直接对应的翻译，因为它是一个英文疑问词或助动词的用法提示，可能需要根据上下文来具体翻译。如果单独翻译，可以理解为“做：”或者作为引导问题的一部分，如“Does he like apples?”翻译为“他喜欢苹果吗？”）

• ✅ 检查所有必需的依赖项
• ✅ 验证环境变量
• ✅ 初始化SQLite数据库
• ✅ 种子数据库，包含示例交易（仅首次运行时）
• ✅ 启动请求的服务器（们）

🤖 代理能力

该人工智能代理可以：

• 创建、读取、更新和删除支出
• 按关键词搜索交易
• 生成财务摘要和见解
• 按类别分析支出模式
• 提供预算编制建议
• 按日期、类型或类别筛选交易

🔧 配置

环境变量 (.env)

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/config.py）

• 服务器主机/端口设置
• 数据库路径
• MCP服务器配置

代理配置（agent/agent.py)

• AI模型选择（默认：gpt-4.1）
• 系统提示自定义
• 代理行为设置
• 数据库位置

🔍 故障排除

缺少依赖项？

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

数据库未初始化？

cd server && python start.py

端口已被使用？

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

代理无法连接到MCP？

• 确保MCP服务器正在运行： python start.py --mcp
• 检查MCP URL中的（内容/设置等，具体根据上下文确定） agent/agent.py （默认： )

📊 演示文稿

这个项目包括一场关于实际AI代理实现的演示：

🌐 实时演示

在线查看幻灯片 →

📁 本地文件

• 英文幻灯片： docs/en/index.html 翻译成中文是：“文档/英文/索引.html” 或者更简洁地表达为 “英文文档索引页面”
• 俄罗斯幻灯片： docs/ru/index.html 翻译为中文是：“文档/俄文版/索引.html” 或者更简洁地表达为：“俄文文档索引页面”。不过，在实际技术文档或网站结构中，我们通常不会直接翻译文件路径，而是保持原样使用，因为文件路径是技术性的标识符，不直接对应到自然语言的翻译。但在这里，为了满足翻译要求，给出了上述解释

打开幻灯片以了解更多关于人工智能代理和MCP协议的信息。

📚 资源

这个项目是基于并受以下杰出开源项目的启发而构建的：

• 模型上下文协议（MCP） - 连接AI代理到工具的标准协议
• FastAPI-MCP - 为MCP服务器集成FastAPI
• 阿尼奥 - 构建AI代理的现代框架
• 代理用户界面（Agent UI） - 人工智能代理的精美聊天界面

特别感谢 感谢这些项目及其维护者，让AI代理开发变得触手可及且乐趣无穷！ 🙏

📝 许可证

麻省理工学院（MIT）

______________________________________________________________________

使用AI代理和MCP，用心打造