# 使用指南 - 記帳 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 --detailed
python test_client.py list 10
python test_client.py summary
python test_client.py categories
```
## 🔧 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](#)
---
**祝您使用愉快！** 🎉
如果您有任何問題或建議，歡迎透過以上管道聯繫我們。
