# 记账 MCP 工具演示项目

基于 Model Context Protocol (MCP) 的个人记账管理工具，为 AI 助手提供财务管理功能。

## 项目概述

这是一个学习和演示 MCP 协议开发的项目，通过构建实用的记账工具来深入理解：
- MCP Tools 和 Resources 的设计模式  
- JSON-RPC 协议在 AI 工具开发中的应用
- TDD 驱动的高质量代码开发流程
- AI 助手与外部工具的标准化集成方式

## 功能特性

### MCP Tools（AI 可调用的工具）
- `add_transaction` - 添加收支记录
- `get_balance` - 查询账户余额
- `list_transactions` - 查询交易记录（支持筛选）
- `get_monthly_summary` - 获取月度财务汇总

### MCP Resources（AI 可访问的数据）  
- `transactions://all` - 所有交易记录
- `categories://list` - 支出分类列表
- `summary://current` - 账户汇总信息

## 快速开始

### 环境要求
- Python 3.11+
- conda（推荐）或 uv/pip

### 安装依赖

**方案 1: 使用 conda + uv（推荐，最快）**
```bash
# 激活您的 conda 环境
conda activate myenv

# 使用 uv 快速安装依赖
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt
```

**方案 2: 纯 conda**
```bash
# 激活环境
conda activate myenv

# 安装 Python 依赖
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

**方案 3: 纯虚拟环境**
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # macOS/Linux

# 安装依赖  
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

### 运行服务器
```bash
# 直接运行 MCP 服务器
python -m accounting_mcp.server

# 或者运行交互式测试客户端
python test_client.py
```

### 测试示例
```bash
# 添加一笔支出
echo '{"jsonrpc":"2.0","method":"add_transaction","params":{"amount":-50,"category":"food","description":"午餐"},"id":1}' | python -m accounting_mcp.server

# 查询余额
echo '{"jsonrpc":"2.0","method":"get_balance","params":{},"id":2}' | python -m accounting_mcp.server
```

## 项目结构

```
accounting-mcp-demo/
├── accounting_mcp/          # 核心代码
│   ├── __init__.py         # 包初始化
│   ├── server.py           # MCP 服务器主程序  
│   ├── models.py           # 数据模型定义
│   ├── storage.py          # JSON 文件存储
│   └── tools.py            # MCP 工具实现
├── tests/                   # 测试代码
│   ├── test_models.py      # 模型测试
│   ├── test_storage.py     # 存储测试
│   ├── test_tools.py       # 工具测试
│   └── test_server.py      # 服务器测试
├── data/                    # 数据文件
│   ├── transactions.json   # 交易记录
│   ├── account.json        # 账户信息
│   └── categories.json     # 分类定义
├── docs/                    # 文档
├── PRD.md                   # 产品需求文档
├── TDD_PLAN.md             # TDD 开发计划
├── requirements.txt         # 项目依赖
├── requirements-dev.txt     # 开发依赖
└── test_client.py          # 交互测试客户端
```

## 开发指南

### TDD 开发流程
本项目采用测试驱动开发（TDD），遵循"红-绿-重构"循环：

1. **红阶段**: 先写失败的测试用例
2. **绿阶段**: 编写最小实现使测试通过
3. **重构阶段**: 优化代码质量和结构

### 运行测试
```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_models.py

# 生成覆盖率报告
pytest --cov=accounting_mcp --cov-report=html

# 类型检查
mypy accounting_mcp/
```

### 代码质量检查
```bash
# 格式化代码
black accounting_mcp/ tests/

# 风格检查
flake8 accounting_mcp/ tests/

# 运行所有质量检查
pre-commit run --all-files
```

## MCP 集成

### Claude Desktop 配置
在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "accounting": {
      "command": "python",
      "args": ["/path/to/accounting-mcp-demo/accounting_mcp/server.py"],
      "env": {}
    }
  }
}
```

### 使用示例
配置完成后，可以通过自然语言与 AI 助手交互：

```
用户: "帮我记录一笔35元的午餐费用"
Claude: 已为您添加35元的餐饮支出，当前余额为1,965元。

用户: "我这个月在食物上花了多少钱？"
Claude: 根据记录，您本月在餐饮分类上总计支出285元。
```

## 技术架构

### MCP 协议实现
- **传输层**: stdio（标准输入输出）
- **协议层**: JSON-RPC 2.0
- **应用层**: 工具注册和资源管理

### 数据存储
- 轻量级 JSON 文件存储
- 支持事务性操作
- 自动备份和恢复

### 错误处理
- 完善的输入验证
- 优雅的错误恢复
- 详细的错误日志

## 扩展和定制

### 添加新的工具
1. 在 `tools.py` 中定义新的工具函数
2. 在 `server.py` 中注册工具
3. 编写对应的测试用例

### 自定义分类
修改 `data/categories.json` 文件，添加自定义的支出分类。

### 数据导入导出
未来版本将支持 CSV 格式的数据导入导出功能。

## 许可证

本项目仅用于学习和演示目的，基于 MIT 许可证开源。

## 贡献

欢迎提交 Issues 和 Pull Requests 来改进项目。

---

*构建于 MCP 1.0 协议之上，遵循最佳实践和 TDD 开发原则。*