使用说明
ExpenseTracker (FastMCP) 💸 翻译为中文是：“支出追踪器（快速多条件计划）💸”
📝 描述
这个项目是一个基于文件的简单费用追踪应用程序，使用……构建（注：原文在此处截断，未给出具体构建技术或语言，因此翻译也相应保留了这种开放性） fastmcp 框架。它使用SQLite数据库（expenses.db用于存储、管理和查询费用数据。它提供了多个“工具”（函数），这些工具可以通过FastMCP环境被调用，以实现费用的添加、列出、更新、删除、过滤和汇总。
✨ 特点/功能
- 添加费用： 记录新的支出，包括日期、金额、类别、子类别和备注。
- 列出费用： 检索指定日期范围内的所有费用列表。
- 更新与删除： 通过唯一ID修改或删除现有的费用条目。
- 详细视图： 通过ID获取单个费用的所有详细信息。
- 过滤： 按类别和/或子类别筛选费用列表。
- 总结： 获取在指定日期范围内按类别划分的总支出概要。
- 品类管理： 从外部加载费用类别
categories.json文件。
🛠️ 要求
- Python 3.x
fastmcp：pip install fastmcpsqlite3（包含在Python标准库中）
🚀 设置与安装
-
获取代码： 克隆仓库或将代码保存为
main.py。 -
安装依赖项： 唯一的外部依赖是
fastmcp。pip install fastmcp -
创建
categories.json： 在与……相同的目录中main.py，你 必须 创建一个名为（指定名称）的文件categories.json此文件定义了您支出的有效类别和子类别。示例
categories.json：{ "Food": [ "Groceries", "Restaurants", "Coffee", "Takeaway" ], "Transport": [ "Gas", "Public Transit", "Taxi", "Repairs" ], "Housing": [ "Rent", "Utilities", "Insurance" ], "Entertainment": [ "Movies", "Subscriptions" ] } -
运行应用程序：
python main.py这将启动FastMCP服务。脚本将自动创建
expenses.db如果在相同目录下不存在，则创建 SQLite 数据库文件。
🗄️ 数据库模式
该应用程序使用一个SQLite数据库文件（expenses.db) 使用单个表： expenses。
| 列 | 类型 | 约束 | 描述 |
| 分隔符 | 分隔符 | 分隔符 | 分隔符 |
| id | INTEGER | PRIMARY KEY AUTOINCREMENT | 费用的唯一标识符。 |
| date | TEXT | NOT NULL 费用日期（例如，“YYYY-MM-DD”）。 |
| amount | REAL | NOT NULL 该费用的金额。 |
| category | TEXT | NOT NULL | 主要类别（例如，“食品”）。 |
| subcategory | TEXT | DEFAULT '' 可选的子类别（例如，“杂货”）。 |
| note | TEXT | DEFAULT '' | 用于该费用的可选文本说明。 |
🤖 API / 工具参考
FastMCP应用程序提供了以下工具和资源。
add_expense
向数据库中添加一条新的费用记录。
- 工具名称：
add_expense - 参数：
date(str): 费用日期（格式为YYYY-MM-DD）。amount(float): 费用金额。category(str)：主要类别。subcategory(字符串，可选)：子类别。默认值为""。note(字符串, 可选): 一个描述性注释。默认值为""。
- 返回值： 一个包含状态和（其他信息）的字典
id新产生的费用。- 成功：
{"status": "ok", "id": 123}
- 成功：
list_expenses
列出指定日期范围内的所有费用条目，按ID排序。
- 工具名称：
list_expenses - 参数：
start_date(str): 日期范围的开始（格式YYYY-MM-DD）。end_date(str): 日期范围的结束（格式为YYYY-MM-DD）。
- 返回值： 一个字典列表，其中每个字典代表一项支出。
- 示例：
[{"id": 1, "date": "2024-10-25", "amount": 12.50, ...}, ...]
- 示例：
delete_expense
通过唯一ID删除单条费用记录。
- 工具名称：
delete_expense - 参数：
expense_id(int): 要删除的费用的ID。
- 返回值： 一个状态字典。
- 成功：
{"status": "ok", "deleted": 1} - 错误（未找到）：
{"status": "error", "message": "No expense found with id 404"}
- 成功：
update_expense
更新现有费用条目的一个或多个字段。
- 工具名称：
update_expense - 参数：
expense_id(int): 要更新的费用的ID。date(字符串，可选)：新日期。amount(float, 可选): 新的金额。category（字符串，可选）：新类别。subcategory(str, 可选)：新的子类别。note(字符串，可选)：新音符。
- 返回值： 一个状态字典。
- 成功：
{"status": "ok", "updated": 1} - 错误（未找到）：
{"status": "error", "message": "No expense found with id 404"} - 错误（无字段）：
{"status": "error", "message": "No fields to update."}
- 成功：
get_expense
通过ID获取单条费用的所有详细信息。
- 工具名称：
get_expense - 参数：
expense_id(int)：要检索的费用的ID。
- 返回值： 一个包含所有费用字段的字典，或者一条错误消息。
- 成功：
{"id": 1, "date": "2024-10-25", "amount": 12.50, ...} - 错误（未找到）：
{"status": "error", "message": "No expense found with id 404"}
- 成功：
filter_expenses
按类别和/或子类别过滤费用，按日期排序。
- 工具名称：
filter_expenses - 参数：
category（字符串，可选）：用于过滤的类别。subcategory(str, 可选)：用于过滤的子类别。
- 返回值： 符合标准的费用字典列表。
summarize
计算在指定日期范围内，按类别分组的费用总和。
- 工具名称：
summarize - 参数：
start_date(str): 日期范围的开始（格式YYYY-MM-DD）。end_date(str): 日期范围的结束（格式YYYY-MM-DD）。category（字符串，可选）：如果提供，则仅对此特定类别进行汇总。
- 返回值： 一个字典列表，每个字典都包含一个
category以及它的total_amount。- 示例：
[{"category": "Food", "total_amount": 350.75}, {"category": "Transport", "total_amount": 120.00}]
- 示例：
categories （资源）
一个只读资源，提供以下内容： categories.json 文件。
- 资源URI：
expense://categories - MIME 类型：
application/json - 返回： 其原始的JSON字符串内容为
categories.json文件。
