# 記帳 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: 已為您新增餐飲支出 NTD 35，目前餘額為 NTD 1,965。
使用者: "我這個月在食物上花了多少錢？"
Claude: 根據記錄，您本月在餐飲分類上總計支出 NTD 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 開發原則。*
