Accounting MCP Server

# 使用指南 - 记账 MCP 工具 ## 🚀 快速开始 ### 1. 环境准备 确保您已安装依赖（在 myenv 环境中）： ```bash conda activate myenv cd /Users/momo/Documents/momo-python/accounting-mcp-demo pip install -r requirements.txt pip install -r requirements-dev.txt ``` ### 2. 验证安装 ```bash python -c "import pytest, mcp, pydantic; print('✅ 环境就绪')" ``` ## 🧪 测试项目 ### 运行单元测试 ```bash # 运行所有测试 python -m pytest -v # 运行特定测试 python -m pytest tests/test_models.py -v python -m pytest tests/test_storage.py -v python -m pytest tests/test_integration.py -v # 生成覆盖率报告 python -m pytest --cov=accounting_mcp --cov-report=html ``` ### 使用交互式测试客户端 ```bash # 启动交互式客户端 python test_client.py # 或直接执行命令 python test_client.py add -50 food "午餐" python test_client.py balance python test_client.py list 10 python test_client.py summary python test_client.py test # 运行完整测试套件 ``` ## 🔧 MCP 服务器使用 ### 直接启动服务器 ```bash # 使用默认配置 python -m accounting_mcp.server # 自定义参数 python -m accounting_mcp.server --data-dir ./my_data --log-level DEBUG ``` ### JSON-RPC 测试示例 ```bash # 添加支出交易 echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"add_transaction","arguments":{"amount":-50,"category":"food","description":"午餐"}},"id":1}' | python -m accounting_mcp.server # 查询余额 echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_balance","arguments":{"detailed":true}},"id":2}' | python -m accounting_mcp.server ``` ## 🤖 Claude Code CLI 集成 ### 1. MCP 服务器配置 在 Claude Code CLI 中，MCP 服务器会被自动识别和加载。确保您的项目结构正确： ``` accounting-mcp-demo/ ├── accounting_mcp/ │ ├── __init__.py │ ├── server.py # MCP 服务器入口 │ ├── models.py # 数据模型 │ ├── storage.py # 存储层 │ ├── tools.py # MCP 工具 │ └── resources.py # MCP 资源 ├── test_client.py # 测试客户端 └── ... ``` ### 2. 启动和使用 **在项目目录中启动 Claude Code CLI：** ```bash cd /Users/momo/Documents/momo-python/accounting-mcp-demo # Claude Code 会自动检测并加载 MCP 服务器 ``` **通过自然语言交互：** Claude Code 会自动识别您的 MCP 服务器，然后您可以直接对话： **基础记账**： - "帮我记录一笔35元的午餐费用" - "添加1000元的工资收入" - "我花了20元坐地铁" **查询功能**： - "我现在还有多少钱？" - "显示详细的账户信息" - "查看最近5笔交易记录" - "显示本月的支出统计" **分析功能**： - "我这个月在餐饮上花了多少钱？" - "显示所有可用的分类" - "生成月度财务报表" ### 3. MCP 服务器状态 Claude Code 会在加载时显示 MCP 服务器状态： ``` ✅ MCP Server: accounting-mcp loaded - 5 tools available - 3 resources available ``` ## 📊 MCP 工具说明 ### 可用工具 1. **add_transaction** - 添加交易记录 - `amount`: 金额（正数=收入，负数=支出） - `category`: 分类（food, transport, entertainment 等） - `description`: 描述（可选） - `date`: 交易日期（可选，默认今天） 2. **get_balance** - 获取账户余额 - `detailed`: 是否返回详细统计（可选） 3. **list_transactions** - 查询交易记录 - `limit`: 返回条数（默认20） - `offset`: 偏移量（分页用） - `category`: 分类筛选（可选） - `start_date/end_date`: 日期范围（可选） 4. **get_monthly_summary** - 月度汇总 - `year`: 年份（可选，默认当前年） - `month`: 月份（可选，默认当前月） 5. **get_categories** - 获取分类列表 ### 可用资源 1. **transactions://all** - 所有交易记录（JSON格式） 2. **categories://list** - 分类列表（JSON格式） 3. **summary://current** - 当前汇总信息（JSON格式） ## 🎯 支持的分类 - **餐饮** (food) 🍽️ - 餐费、外卖、聚餐等 - **交通** (transport) 🚗 - 公交、地铁、打车等 - **娱乐** (entertainment) 🎬 - 电影、游戏、旅游等 - **购物** (shopping) 🛍️ - 服装、日用品、电子产品等 - **医疗** (healthcare) 🏥 - 医院、药品、体检等 - **教育** (education) 📚 - 培训、课程、书籍等 - **收入** (income) 💰 - 工资、奖金、投资收益等 - **其他** (other) 📝 - 其他未分类项目 ## 🔍 故障排除 ### 常见问题 **1. 模块导入错误** ```bash # 确保在正确的conda环境中 conda activate myenv python -c "import mcp; print('MCP SDK 已安装')" ``` **2. 数据文件权限** ```bash # 检查数据目录权限 ls -la data/ # 如果需要，修复权限 chmod 755 data/ chmod 644 data/*.json ``` **3. Claude Desktop 连接失败** - 检查配置文件路径是否正确 - 确认项目目录的绝对路径 - 重启 Claude Desktop - 查看日志文件：`mcp_server.log` **4. 测试失败** ```bash # 清理测试缓存 rm -rf .pytest_cache/ rm -rf __pycache__/ # 重新运行测试 python -m pytest -v --tb=short ``` ### 调试模式 启用详细日志： ```bash python -m accounting_mcp.server --log-level DEBUG ``` 查看日志文件： ```bash tail -f mcp_server.log ``` ## 📈 性能指标 - **响应时间**：单次交易 < 100ms - **吞吐量**：支持 100+ 交易/秒 - **内存使用**：< 50MB - **存储限制**：支持 10,000+ 交易记录 ## 🛠️ 开发扩展 ### 添加新分类 编辑 `data/categories.json` 文件，添加新的分类定义。 ### 添加新工具 1. 在 `accounting_mcp/tools.py` 中实现工具函数 2. 在 `get_tool_definitions()` 中添加工具定义 3. 在 `server.py` 中添加工具调用逻辑 ### 添加新资源 1. 在 `accounting_mcp/resources.py` 中实现资源函数 2. 在 `get_resource_definitions()` 中添加资源定义 ## 📝 更多信息 - **项目文档**：[PRD.md](./PRD.md) - **开发计划**：[TDD_PLAN.md](./TDD_PLAN.md) - **GitHub**：[项目地址](#) - **问题反馈**：[Issues](#) --- **祝您使用愉快！** 🎉 如果您有任何问题或建议，欢迎通过以上渠道联系我们。