记账 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（推荐，最快）
# 激活您的 conda 环境
conda activate myenv
# 使用 uv 快速安装依赖
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt
方案 2: 纯 conda
# 激活环境
conda activate myenv
# 安装 Python 依赖
pip install -r requirements.txt
pip install -r requirements-dev.txt
方案 3: 纯虚拟环境
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # macOS/Linux
# 安装依赖
pip install -r requirements.txt
pip install -r requirements-dev.txt
运行服务器
# 直接运行 MCP 服务器
python -m accounting_mcp.server
# 或者运行交互式测试客户端
python test_client.py
测试示例
# 添加一笔支出
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），遵循"红-绿-重构"循环：
- 红阶段: 先写失败的测试用例
- 绿阶段: 编写最小实现使测试通过
- 重构阶段: 优化代码质量和结构
运行测试
# 运行所有测试
pytest
# 运行特定测试文件
pytest tests/test_models.py
# 生成覆盖率报告
pytest --cov=accounting_mcp --cov-report=html
# 类型检查
mypy accounting_mcp/
代码质量检查
# 格式化代码
black accounting_mcp/ tests/
# 风格检查
flake8 accounting_mcp/ tests/
# 运行所有质量检查
pre-commit run --all-files
MCP 集成
Claude Desktop 配置
在 Claude Desktop 的配置文件中添加：
{
"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 文件存储
- 支持事务性操作
- 自动备份和恢复
错误处理
- 完善的输入验证
- 优雅的错误恢复
- 详细的错误日志
扩展和定制
添加新的工具
- 在
tools.py中定义新的工具函数 - 在
server.py中注册工具 - 编写对应的测试用例
自定义分类
修改 data/categories.json 文件，添加自定义的支出分类。
数据导入导出
未来版本将支持 CSV 格式的数据导入导出功能。
许可证
本项目仅用于学习和演示目的，基于 MIT 许可证开源。
贡献
欢迎提交 Issues 和 Pull Requests 来改进项目。
构建于 MCP 1.0 协议之上，遵循最佳实践和 TDD 开发原则。