README.md•5.41 kB
# 记账 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 开发原则。*