AI导哈

AI个人财务助手

AI驱动的个人财务助手，支持跟踪支出、同步银行数据并通过自然语言获取财务洞察。

  • by Lakshaychauhan1811
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Lakshaychauhan1811/TrackExpensio

使用说明

TrackExpensio

人工智能驱动的个人理财助理——跟踪支出、同步银行，并通过自然语言获得洞察力。

技术栈

层 技术
后端 Python、FastAPI、Uvicorn
AI/代理 Groq（Llama 3.3）、FastMCP、函数调用
数据库 MongoDB（异步电机）
Auth Google OAuth、API密钥、来宾会话
整合 Plaid、Gmail、雅虎财经、Whisper
前端 HTML、CSS、香草JS

特征

  • AI聊天 --用简明英语添加费用、设置预算和查询数据
  • 银行同步 --通过Plaid连接帐户；自动导入和消除重复事务
  • 印度银行支持 --账户聚合器（Setu/Finvu/OneMoney）+用于印度银行警报的短信解析器
  • Gmail解析 --从银行提醒电子邮件中提取真实交易，过滤掉促销活动
  • 收据上传 --RAG管道从账单图像/PDF中提取商家、金额和日期
  • 语音命令 --通过Whisper语音转文本说出费用
  • 预算和目标 --设定类别预算并跟踪节省进度
  • 投资与债务 --投资组合跟踪、债务偿还记录
  • 税务估算 --多管辖区发动机（IN、US、GB、CA、AU、DE、FR、SG、AE、CH）
  • 外汇兑换 --使用MongoDB缓存的历史汇率
  • 报告 --以PDF格式导出的月度财务摘要
  • 安全 --bcrypt密码、速率限制、IP阻止、审计日志

快速开始

先决条件： Python 3.10+，MongoDB

git clone <repo-url> && cd project
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

创建 .env 文件：

MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=ai_expense_tracker
GROQ_API_KEY=your_groq_api_key
GROQ_AGENT_MODEL=llama-3.3-70b-versatile

# Optional
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
PLAID_CLIENT_ID=...
PLAID_SECRET=...
OPENAI_API_KEY=...         # for Whisper voice
SMTP_HOST=smtp.gmail.com   # for bill reminders

python run_app.py
# → http://127.0.0.1:8080

项目结构

├── main.py              # 44 MCP tools (expenses, budgets, investments, …)
├── api.py               # FastAPI routes and middleware
├── chat_agent.py        # Groq agent with function-calling
├── database.py          # MongoDB operations
├── auth.py              # API key + session authentication
├── security.py          # Rate limiting, IP blocking, bcrypt
├── tax_rules.py         # Multi-jurisdiction tax engine
├── fx_timing.py         # Historical FX rate management
├── audit_logger.py      # Action audit trail
├── services/
│   ├── bank_plaid.py        # Plaid Link + transaction sync
│   ├── account_aggregator.py # India AA integration
│   ├── gmail_bills.py        # Gmail receipt parsing
│   ├── sms_parser.py         # Indian bank SMS parser
│   ├── transaction_filters.py # Promo / credit filtering
│   ├── notifications.py      # Email bill reminders
│   └── pdf_reports.py        # PDF report generation
└── static/
    ├── plaid_link.js
    ├── india_bank_sync.js
    └── voice_recording.js

MCP在TrackExpensio中的工作原理

MCP（模型上下文协议） 是AI层的骨干。每个财务操作都被注册为一个类型化的Python函数，而不是硬编码人工智能可以做什么 工具 --代理可以在运行时发现和调用。

模式

User message → Groq agent reads tool schemas → picks the right tool(s) → Python executes → MongoDB writes

AI从不直接写入数据库。它提出了一个工具调用；Python验证并执行它。这使AI层保持无状态，业务逻辑安全且可测试。

如何定义工具(main.py)

@mcp.tool()
async def add_expense(
    api_key: str, date: str, amount: float,
    category: str, note: str, merchant: str
) -> dict:
    """Add a new expense entry."""
    user_id = await auth.authenticate_user(api_key=api_key)
    return await db.add_expense(user_id, date, amount, category, note, merchant)

每 @mcp.tool() 装饰器将函数注册到 TOOL_REGISTRY 其名称、docstring和参数schema都会自动暴露给代理。

Agent如何使用工具(chat_agent.py)

Groq代理接收完整的工具注册表作为函数模式。当用户说 "Add ₹500 在Swiggy吃午饭”，代理人：

  1. 从消息中解析意图
  2. 选择 add_expense 从注册表
  3. 填写 amount=500, merchant="Swiggy", category="Food", date=today
  4. 返回一个结构化的工具调用——Python执行它

对于复杂的消息，如 “添加午餐费用并显示本月的总费用”，代理问题 并行工具调用 — add_expense 和 list_expenses 同时奔跑。

调用工具的三种方法

方法 如何
AI聊天 代理自动选择和调用工具
REST API POST /api/mcp/<tool_name> JSON正文
克劳德桌面 python mcp_server.py --在STDIO模式下运行

为什么这个架构

添加新功能意味着编写一个Python函数 @mcp.tool()。代理可以立即使用它-不需要提示更改，也不需要新的API路由。它使系统具有自然的可扩展性。

MCP工具（共44个）

费用·预算·收入·经常性·储蓄目标·债务·投资·报告·税务·信用评分·账单提醒·多币种·外汇兑换·雅虎财经·银行同步·审计日志·用户管理

所有工具都可以通过聊天、REST API调用(POST /api/mcp/<tool>)，或克劳德桌面（STDIO模式）。

API终点

方法 端点 描述
POST /api/chat 与AI助手聊天
POST /api/mcp/{tool_name} 直接调用任何MCP工具
POST /api/session/create 创建访客会话
GET /api/user/profile 获取用户资料（登录谷歌后）
GET /api/health 健康检查

任选附件

# Receipt RAG + local Whisper (~3.5 GB)
pip install -r requirements-ml.txt

# Standalone MCP server for Claude Desktop
python mcp_server.py

部署

通过渲染一键部署 render.yaml.Set MONGODB_URI, GROQ_API_KEY，以及Render仪表板中的其他秘密——永远不要提交。

许可证

麻省理工学院

相关 MCP