记账 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），遵循"红-绿-重构"循环：

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

运行测试

# 运行所有测试
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 文件存储
• 支持事务性操作
• 自动备份和恢复

错误处理

• 完善的输入验证
• 优雅的错误恢复
• 详细的错误日志

扩展和定制

添加新的工具

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

自定义分类

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

数据导入导出

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

许可证

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

贡献

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

---

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