PRD.md•7.43 kB
# 记账类 MCP 工具 - 产品需求文档 (PRD)
## 1. 项目概述
### 1.1 产品定义
基于 Model Context Protocol (MCP) 开发的个人记账管理工具，通过标准化的 MCP 接口为 AI 助手提供记账功能，支持收支管理、分类统计和余额查询。
### 1.2 核心目标
- **学习目标**: 深入理解 MCP 协议的设计思想和实现方式
- **技术目标**: 掌握 MCP Tools 和 Resources 的开发模式
- **应用目标**: 构建可实际使用的记账 MCP 服务器
### 1.3 技术架构
- **传输协议**: stdio (JSON-RPC 2.0)
- **数据存储**: JSON 文件
- **开发语言**: Python 3.11+
- **核心依赖**: mcp Python SDK
## 2. 功能需求
### 2.1 MCP Tools（工具功能）
#### 2.1.1 add_transaction - 添加交易记录
```python
{
"name": "add_transaction",
"description": "添加一笔收入或支出记录",
"inputSchema": {
"type": "object",
"properties": {
"amount": {"type": "number", "description": "金额，正数为收入，负数为支出"},
"category": {"type": "string", "description": "分类：food, transport, entertainment, shopping, income, other"},
"description": {"type": "string", "description": "描述信息"},
"date": {"type": "string", "format": "date", "description": "交易日期，默认为今天"}
},
"required": ["amount", "category"]
}
}
```
**业务逻辑**:
- 验证金额格式（支持小数点后2位）
- 验证分类是否在预定义列表中
- 自动生成唯一 ID
- 更新账户余额
- 记录时间戳
#### 2.1.2 get_balance - 获取账户余额
```python
{
"name": "get_balance",
"description": "获取当前账户余额信息",
"inputSchema": {
"type": "object",
"properties": {
"detailed": {"type": "boolean", "description": "是否返回详细的分类统计", "default": false}
}
}
}
```
**返回信息**:
- 当前总余额
- detailed=true 时包含：
- 本月收入总计
- 本月支出总计
- 各分类支出统计
#### 2.1.3 list_transactions - 查询交易记录
```python
{
"name": "list_transactions",
"description": "查询交易记录，支持筛选条件",
"inputSchema": {
"type": "object",
"properties": {
"category": {"type": "string", "description": "按分类筛选"},
"start_date": {"type": "string", "format": "date", "description": "开始日期"},
"end_date": {"type": "string", "format": "date", "description": "结束日期"},
"limit": {"type": "integer", "description": "返回记录数限制", "default": 20}
}
}
}
```
#### 2.1.4 get_monthly_summary - 获取月度汇总
```python
{
"name": "get_monthly_summary",
"description": "获取指定月份的收支汇总统计",
"inputSchema": {
"type": "object",
"properties": {
"year": {"type": "integer", "description": "年份，默认当前年"},
"month": {"type": "integer", "description": "月份，默认当前月"}
}
}
}
```
### 2.2 MCP Resources（资源访问）
#### 2.2.1 transactions://all - 所有交易记录
- **URI**: `transactions://all`
- **内容类型**: `application/json`
- **描述**: 返回所有交易记录的 JSON 数据
#### 2.2.2 categories://list - 分类列表
- **URI**: `categories://list`
- **内容类型**: `application/json`
- **描述**: 返回所有支持的分类及其描述
#### 2.2.3 summary://current - 当前汇总信息
- **URI**: `summary://current`
- **内容类型**: `application/json`
- **描述**: 返回账户余额、交易数量等汇总信息
## 3. 数据模型
### 3.1 Transaction（交易记录）
```python
{
"id": "unique_identifier", # 唯一标识符
"amount": -50.00, # 金额（负数为支出，正数为收入）
"category": "food", # 分类
"description": "午餐", # 描述
"date": "2025-01-15", # 交易日期
"timestamp": "2025-01-15T12:30:00Z" # 记录时间戳
}
```
### 3.2 Category（分类定义）
```python
{
"id": "food",
"name": "餐饮",
"description": "餐费、外卖、聚餐等饮食相关支出",
"type": "expense" # expense | income
}
```
### 3.3 Account（账户信息）
```python
{
"balance": 1450.50, # 当前余额
"total_transactions": 156, # 总交易数
"last_updated": "2025-01-15T14:20:00Z",
"created_at": "2024-12-01T00:00:00Z"
}
```
## 4. 数据存储设计
### 4.1 文件结构
```
data/
├── transactions.json # 交易记录
├── account.json # 账户信息
└── categories.json # 分类定义
```
### 4.2 transactions.json 格式
```json
{
"transactions": [
{
"id": "txn_20250115_001",
"amount": -50.00,
"category": "food",
"description": "午餐",
"date": "2025-01-15",
"timestamp": "2025-01-15T12:30:00Z"
}
]
}
```
### 4.3 account.json 格式
```json
{
"balance": 1450.50,
"total_transactions": 1,
"last_updated": "2025-01-15T12:30:00Z",
"created_at": "2025-01-15T12:30:00Z"
}
```
## 5. 用户场景
### 5.1 基础记账场景
**用户**: "我刚花了35元买了午餐"
**AI 处理**: 调用 add_transaction
**系统响应**: 添加支出记录，更新余额
### 5.2 余额查询场景
**用户**: "我现在还有多少钱？"
**AI 处理**: 调用 get_balance
**系统响应**: 返回当前余额和简要统计
### 5.3 支出分析场景
**用户**: "我这个月在餐饮上花了多少钱？"
**AI 处理**: 调用 list_transactions(category="food") + get_monthly_summary
**系统响应**: 返回餐饮分类的详细统计
## 6. 错误处理
### 6.1 数据验证错误
- **无效金额**: 非数字或精度超过2位小数
- **无效分类**: 不在预定义分类列表中
- **无效日期**: 格式错误或未来日期
### 6.2 文件操作错误
- **文件不存在**: 自动创建初始数据文件
- **权限错误**: 返回明确的错误信息
- **数据损坏**: 提供备份和恢复机制
### 6.3 MCP 协议错误
- **方法不存在**: 返回标准 JSON-RPC 错误
- **参数错误**: 详细的参数验证信息
- **内部错误**: 记录日志但不暴露敏感信息
## 7. 性能要求
### 7.1 响应时间
- 单次交易添加: < 100ms
- 余额查询: < 50ms
- 交易记录查询: < 200ms (100条记录内)
### 7.2 数据量限制
- 支持最多 10,000 条交易记录
- JSON 文件大小限制在 10MB 以内
- 内存使用不超过 50MB
## 8. 扩展性设计
### 8.1 分类系统
- 支持用户自定义分类
- 分类的层级结构（父子分类）
- 分类的颜色和图标配置
### 8.2 多账户支持
- 现金账户、银行账户、信用卡等
- 账户间转账功能
- 不同账户的独立统计
### 8.3 数据导入导出
- CSV 格式导入导出
- 与主流记账软件的数据迁移
- 备份和恢复功能
## 9. 开发优先级
### Phase 1 (MVP)
1. ✅ 基础的 add_transaction 工具
2. ✅ get_balance 查询功能
3. ✅ JSON 文件存储
4. ✅ 基本的错误处理
### Phase 2 (增强)
1. ✅ list_transactions 筛选查询
2. ✅ get_monthly_summary 统计
3. ✅ MCP Resources 实现
4. ✅ 完整的单元测试
### Phase 3 (完善)
1. 🔄 交互式测试客户端
2. 🔄 Claude Desktop 集成配置
3. 🔄 性能优化和错误恢复
4. 🔄 使用文档和演示
---
*本 PRD 基于 MCP 1.0 协议标准，遵循 TDD 开发原则，确保每个功能都有对应的测试用例。*