Expense Tracker Agent

一个由 AI 驱动的个人支出追踪器，可将自然语言请求转化为结构化的数据库操作。该项目结合了响应式 Streamlit 界面、Claude 工具调用、MCP 服务器和本地 SQLite 存储。

本项目演示的内容

• 面向真实数据库工作流的代理式多步工具调用

• 语言模型、MCP 传输层和数据层之间清晰的分离

• 无需编排框架的直接 Claude 工具调用循环

• 输入验证、受限的助手行为以及安全的本地数据处理

• 自动化冒烟测试和持续集成

• 用于录入、对话和支出洞察的响应式用户界面

Related MCP server: Expense Tracker MCP Server

产品功能

• 通过表单或自然语言请求添加支出

• 存储每笔交易的日期、金额、类别和描述

• 通过 MCP 工具搜索、更新、删除和汇总支出

• 查看总额、近期交易和类别级支出

• 向专注的财务助手询问基于数据库的洞察

• 将支出数据保存在本地 SQLite 文件中

架构

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude 从不直接访问 SQLite。它从 MCP 工具模式中进行选择，而服务器负责所有经过验证的数据库读写操作。

示例代理工作流

技术

快速开始

要求：

• Python 3.11 或更高版本

• 用于助手的 Anthropic API 密钥

创建并激活虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

对于 macOS 或 Linux，使用以下命令激活环境：

source .venv/bin/activate

创建本地环境文件并添加 ANTHROPIC_API_KEY：

Copy-Item .env.example .env

创建数据库模式和初始类别，然后启动应用：

python db_setup.py
streamlit run streamlit_app.py

MCP 服务器使用 stdio，并在客户端连接时自动启动。

质量检查

安装开发依赖并运行 CI 中使用的相同检查：

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py 会运行全部 18 个 MCP 工具，并在冒烟测试结束时删除其临时记录。

MCP 工具

服务器提供 18 个工具：

• 类别管理：list_categories, add_category, rename_category, delete_category, get_category_name

• 支出管理：add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• 支持查询：current_date, find_category, get_expense, expenses_between

项目结构

配置

.env 文件和 expenses.db 被 Git 排除。API 密钥和个人支出数据保留在存储库之外。

要使用空支出表重新创建数据库：

python db_setup.py --reset