使用说明

个人理财追踪器-MCP项目

使用 模型上下文协议（MCP） 使用 快速MCP Python SDK。具有漂亮的web界面，使用OAuth 2.0进行用户身份验证，以及使用 Azure OpenAI.

🌟 特性

身份验证和安全

🔐 用户帐户：每个用户都有独立的私人财务数据
🔑 本地身份验证：电子邮件/密码注册和登录
🌐 谷歌OAuth 2.0：使用Google登录以实现无缝身份验证
🔒 SQLite数据库：为所有用户数据提供安全的基于文件的数据库存储

MCP服务器（FastMCP）

工具：添加支出、收入、管理预算、设定财务目标、生成报告
资源：访问财务数据、月度报告、类别细分
提示：预先构建的支出模式、预算检查、目标进度分析提示

Web应用程序（Flask）

📊 仪表盘：余额、收入、支出和储蓄概述
💳 交易：跟踪和筛选所有交易
📈 预算：设置和监控类别预算
🎯 目标：创建和跟踪储蓄目标
📑 报告：详细的月度财务报告
🧾 税收：扣税跟踪和估算
🤖 AI 聊天：智能金融助理
👤 个人资料：管理帐户设置和首选项

人工智能客户端（Azure OpenAI）

金融查询的自然语言交互
自动工具调用实时数据
智能建议和预算优化
人工智能生成的财务建议的抽样

🏗️ 建筑

┌─────────────────────────────────────────────────────────────┐
│                     Web Interface (Flask)                    │
│  Dashboard │ Transactions │ Budgets │ Goals │ Reports │ Chat │
└─────────────────────────────────────────────────────────────┘
                              │
                        Authentication
                    (Flask-Login + OAuth)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      MCP Client Layer                        │
│         Roots │ Sampling │ Elicitation │ Tool Calls         │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│      MCP Server         │     │     Azure OpenAI        │
│  (FastMCP)              │     │     (GPT-4o-mini)       │
│  • Tools                │     │                         │
│  • Resources            │     │  Natural Language       │
│  • Prompts              │     │  Processing             │
└─────────────────────────┘     └─────────────────────────┘
              │
              ▼
┌─────────────────────────┐
│   SQLite Database       │
│  • users                │
│  • transactions         │
│  • budgets              │
│  • goals                │
│  • tax_deductions       │
│  • tax_profiles         │
└─────────────────────────┘

📁 项目结构

mcp-project/
├── server/                    # MCP Server & Database
│   ├── __init__.py
│   ├── main.py               # FastMCP server with tools, resources, prompts
│   ├── models.py             # Pydantic data models
│   ├── storage.py            # Legacy JSON storage (deprecated)
│   ├── storage_sql.py        # SQLite storage (user-scoped)
│   ├── database.py           # SQLAlchemy models & database setup
│   ├── auth.py               # Authentication module (OAuth, passwords)
│   ├── tax_models.py         # Tax-related data models
│   ├── tax_storage.py        # Legacy tax storage (deprecated)
│   └── tax_storage_sql.py    # SQLite tax storage (user-scoped)
│
├── client/                    # MCP Client
│   ├── __init__.py
│   ├── mcp_client.py         # MCP client wrapper
│   ├── ai_client.py          # Azure OpenAI integration
│   └── multi_agent.py        # Multi-agent orchestration
│
├── web/                       # Flask Web Application
│   ├── app.py                # Flask routes, auth, and API
│   ├── auth_routes.py        # Authentication routes (login, register, OAuth)
│   └── templates/            # HTML templates
│       ├── base.html         # Base template with navigation
│       ├── dashboard.html    # Main dashboard
│       ├── transactions.html # Transaction management
│       ├── budgets.html      # Budget management
│       ├── goals.html        # Financial goals
│       ├── reports.html      # Monthly reports
│       ├── taxes.html        # Tax management
│       ├── chat.html         # AI chat interface
│       ├── 404.html          # Error page
│       └── auth/             # Authentication templates
│           ├── login.html    # Login page
│           ├── register.html # Registration page
│           └── profile.html  # User profile page
│
├── data/                      # Data storage
│   └── finance.db            # SQLite database
│
├── run.py                     # Main entry point
├── requirements.txt           # Python dependencies
├── .env.example              # Environment variables template
└── README.md                 # This file

🚀 快速开始

1.克隆和设置

cd c:\Users\olado\Projects\AI_Projects\mcp-project

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

2.配置环境

# Copy the example environment file
copy .env.example .env

# Edit .env with your Azure OpenAI credentials

编辑 .env 根据您的实际值：

# Required: Azure OpenAI (for AI features)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Required: Flask configuration
FLASK_SECRET_KEY=your-secret-key-here-change-in-production
FLASK_DEBUG=true

# Required for Google OAuth (optional if only using email/password)
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Database (SQLite)
DATABASE_PATH=./data/finance.db

设置Google OAuth

首选谷歌云控制台
创建新项目或选择现有项目
导航到“API和服务”>“凭据”
点击“创建凭据”>“OAuth 2.0客户端ID”
选择“Web应用程序”
添加授权重定向URI： http://localhost:5000/auth/google/callback
将客户端ID和客户端密码复制到您的 .env 文件

3.运行Web应用程序

python run.py web

打开http://localhost:5000在您的浏览器中。

4.替代方案：单独运行组件

# Run MCP server only (stdio mode)
python run.py server

# Run MCP client demo
python run.py client

# Run AI assistant in terminal
python run.py ai

🛠️ MCP服务器组件

工具

工具	说明
`add_expense`	添加新的支出交易记录
`add_income`	添加新的收入交易
`list_transactions`	使用筛选器列出交易记录
`delete_transaction`	删除交易
`get_balance`	获取当前财务余额
`generate_report`	生成月度报告
`get_spending_by_category`	获取类别细分
`set_budget`	为类别设置月度预算
`get_budgets`	获取所有预算及其状态
`delete_budget`	删除预算
`set_financial_goal`	设定储蓄目标
`update_goal_progress`	更新目标进度
`get_goals`	随着进度实现所有目标
`delete_goal`	删除目标

资源

URI	描述
`finance://balance`	当前余额汇总
`finance://report/{year}/{month}`	月度财务报告
`finance://budgets`	预算概述
`finance://goals`	财务目标清单
`finance://categories`	可用类别

提示

提示	描述
`analyze_spending`	分析支出模式
`budget_check`	检查预算合规性
`monthly_summary`	综合月度总结
`goal_progress`	审查财务目标
`spending_category`	深入某一类别
`financial_health_check`	全面财务评估

🤖 AI助手功能

采样

AI助手使用Azure OpenAI生成：

预算优化建议
支出模式分析
个性化财务建议

根

定义数据访问的边界：

财务数据目录
最大交易限额
允许的操作

引出

交互式信息收集：

询问交易详情
确认破坏性操作
验证用户输入

💡 交互示例

网络界面

添加费用：点击“添加费用”→ 输入50美元，类别：食品，描述：“杂货购物”
设定预算：转到预算→ 每月增加500美元的食物费
设定一个目标：转到目标→ 设立目标为5000美元的“应急基金”

AI聊天示例

You: How much did I spend on food this month?
AI: Based on your transactions, you spent $342.50 on food this month...

You: Am I on track with my budgets?
AI: Let me check your budgets... 🟢 Food: $342/$500 (68%)...

You: Add an expense of $25 for coffee at Starbucks
AI: I've added an expense of $25.00 for "coffee at Starbucks" in the food category.

🔧 发展

运行测试

# Test MCP server tools
python -c "from server.main import mcp; print(mcp)"

# Test storage
python -c "from server.storage import get_storage; s = get_storage(); print(s.get_balance())"

添加新工具

在中添加工具功能 server/main.py 随着 @mcp.tool() 装饰器
使用Pydantic定义输入参数 Field
返回一个字典 success 以及相关数据

添加新资源

添加资源函数 @mcp.resource("uri://path")
返回markdown格式的字符串内容

📝 API终点

交易

GET /api/transactions -列出交易记录
POST /api/transactions/expense -增加费用
POST /api/transactions/income -增加收入
DELETE /api/transactions/<id> -删除交易记录

平衡与报告

GET /api/balance -获取当前余额
GET /api/report -获取月度报告
GET /api/category/<category> -获取类别细分

预算

GET /api/budgets -列出预算
POST /api/budgets -设定预算
DELETE /api/budgets/<category> -删除预算

目标

GET /api/goals -列出目标
POST /api/goals -创建目标
POST /api/goals/<id>/progress -更新进度
DELETE /api/goals/<id> -删除目标

AI 聊天

POST /api/chat -向AI发送消息
POST /api/chat/reset -重置对话
GET /api/chat/prompts -列出可用提示
POST /api/chat/suggestion -获取AI建议

🎨 定制

主题

web界面支持暗模式。点击侧边栏中的“切换主题”按钮。

分类

修改中的支出/收入类别 server/models.py:

class ExpenseCategory(str, Enum):
    FOOD = "food"
    # Add more categories...

📄 许可证

麻省理工学院许可证-您可以自由使用此项目进行学习和个人使用。

🙏 致谢

快速MCP -Python MCP SDK
模型上下文协议 -MCP规范
Azure OpenAI -人工智能平台
烧瓶 -Web框架
独自创立 -UI框架