# 記帳 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 開發原則。*