Accounting MCP

# 記帳類 MCP 工具 - 產品需求文件 (PRD) ## 1. 專案概述 ### 1.1 產品定義 基於 Model Context Protocol (MCP) 開發的個人記帳管理工具，透過標準化的 MCP 介面為 AI 助手提供記帳功能，支援收支管理、分類統計和餘額查詢。 ### 1.2 核心目標 - **學習目標**: 深入理解 MCP 協定的設計思想與實作方式 - **技術目標**: 掌握 MCP Tools 和 Resources 的開發模式 - **應用目標**: 建構可實際使用的記帳 MCP 伺服器 ### 1.3 技術架構 - **傳輸協定**: stdio (JSON-RPC 2.0) - **資料儲存**: JSON 檔案 - **開發語言**: Python 3.11+ - **核心依賴**: mcp Python SDK ## 2. 功能需求 ### 2.1 MCP Tools（工具功能） #### 2.1.1 add_transaction - 新增交易記錄 ```python { "name": "add_transaction", "description": "新增一筆收入或支出記錄", "inputSchema": { "type": "object", "properties": { "amount": {"type": "number", "description": "金額，正數為收入，負數為支出"}, "category": {"type": "string", "description": "分類：food, transport, entertainment, shopping, income, other"}, "description": {"type": "string", "description": "描述資訊"}, "date": {"type": "string", "format": "date", "description": "交易日期，預設為今天"} }, "required": ["amount", "category"] } } ``` **業務邏輯**: - 驗證金額格式（支援小數點後 2 位） - 驗證分類是否在預定義清單中 - 自動產生唯一 ID - 更新帳戶餘額 - 記錄時間戳 #### 2.1.2 get_balance - 取得帳戶餘額 ```python { "name": "get_balance", "description": "取得目前帳戶餘額資訊", "inputSchema": { "type": "object", "properties": { "detailed": {"type": "boolean", "description": "是否回傳詳細的分類統計", "default": false} } } } ``` **回傳資訊**: - 目前總餘額 - detailed=true 時包含： - 本月收入總計 - 本月支出總計 - 各分類支出統計 #### 2.1.3 list_transactions - 查詢交易記錄 ```python { "name": "list_transactions", "description": "查詢交易記錄，支援篩選條件", "inputSchema": { "type": "object", "properties": { "category": {"type": "string", "description": "按分類篩選"}, "start_date": {"type": "string", "format": "date", "description": "開始日期"}, "end_date": {"type": "string", "format": "date", "description": "結束日期"}, "limit": {"type": "integer", "description": "回傳記錄數限制", "default": 20} } } } ``` #### 2.1.4 get_monthly_summary - 取得月度彙總 ```python { "name": "get_monthly_summary", "description": "取得指定月份的收支彙總統計", "inputSchema": { "type": "object", "properties": { "year": {"type": "integer", "description": "年份，預設當前年"}, "month": {"type": "integer", "description": "月份，預設當前月"} } } } ``` ### 2.2 MCP Resources（資源存取） #### 2.2.1 transactions://all - 所有交易記錄 - **URI**: `transactions://all` - **內容類型**: `application/json` - **描述**: 回傳所有交易記錄的 JSON 資料 #### 2.2.2 categories://list - 分類清單 - **URI**: `categories://list` - **內容類型**: `application/json` - **描述**: 回傳所有支援的分類及其描述 #### 2.2.3 summary://current - 目前彙總資訊 - **URI**: `summary://current` - **內容類型**: `application/json` - **描述**: 回傳帳戶餘額、交易數量等彙總資訊 ## 3. 資料模型 ### 3.1 Transaction（交易記錄） ```python { "id": "unique_identifier", # 唯一識別碼 "amount": -50.00, # 金額（負數為支出，正數為收入） "category": "food", # 分類 "description": "午餐", # 描述 "date": "2025-01-15", # 交易日期 "timestamp": "2025-01-15T12:30:00Z" # 記錄時間戳 } ``` ### 3.2 Category（分類定義） ```python { "id": "food", "name": "餐飲", "description": "餐費、外賣、聚餐等飲食相關支出", "type": "expense" # expense | income } ``` ### 3.3 Account（帳戶資訊） ```python { "balance": 1450.50, # 目前餘額 "total_transactions": 156, # 總交易數 "last_updated": "2025-01-15T14:20:00Z", "created_at": "2024-12-01T00:00:00Z" } ``` ## 4. 資料儲存設計 ### 4.1 檔案結構 ``` data/ ├── transactions.json # 交易記錄 ├── account.json # 帳戶資訊 └── categories.json # 分類定義 ``` ### 4.2 transactions.json 格式 ```json { "transactions": [ { "id": "txn_20250115_001", "amount": -50.00, "category": "food", "description": "午餐", "date": "2025-01-15", "timestamp": "2025-01-15T12:30:00Z" } ] } ``` ### 4.3 account.json 格式 ```json { "balance": 1450.50, "total_transactions": 1, "last_updated": "2025-01-15T12:30:00Z", "created_at": "2025-01-15T12:30:00Z" } ``` ## 5. 使用者情境 ### 5.1 基礎記帳情境 **使用者**: "我剛花了35元買了午餐" **AI 處理**: 呼叫 add_transaction **系統回應**: 新增支出記錄，更新餘額 ### 5.2 餘額查詢情境 **使用者**: "我現在還有多少錢？" **AI 處理**: 呼叫 get_balance **系統回應**: 回傳目前餘額與簡要統計 ### 5.3 支出分析情境 **使用者**: "我這個月在餐飲上花了多少錢？" **AI 處理**: 呼叫 list_transactions(category="food") + get_monthly_summary **系統回應**: 回傳餐飲分類的詳細統計 ## 6. 錯誤處理 ### 6.1 資料驗證錯誤 - **無效金額**: 非數字或精度超過 2 位小數 - **無效分類**: 不在預定義分類清單中 - **無效日期**: 格式錯誤或未來日期 ### 6.2 檔案操作錯誤 - **檔案不存在**: 自動建立初始資料檔案 - **權限錯誤**: 回傳明確的錯誤資訊 - **資料損壞**: 提供備份與復原機制 ### 6.3 MCP 協定錯誤 - **方法不存在**: 回傳標準 JSON-RPC 錯誤 - **參數錯誤**: 詳細的參數驗證資訊 - **內部錯誤**: 記錄日誌但不暴露敏感資訊 ## 7. 效能需求 ### 7.1 回應時間 - 單次交易新增: < 100ms - 餘額查詢: < 50ms - 交易記錄查詢: < 200ms (100 條記錄內) ### 7.2 資料量限制 - 支援最多 10,000 條交易記錄 - JSON 檔案大小限制在 10MB 以內 - 記憶體使用不超過 50MB ## 8. 擴充性設計 ### 8.1 分類系統 - 支援使用者自訂分類 - 分類的層級結構（父子分類） - 分類的顏色與圖示設定 ### 8.2 多帳戶支援 - 現金帳戶、銀行帳戶、信用卡等 - 帳戶間轉帳功能 - 不同帳戶的獨立統計 ### 8.3 資料匯入匯出 - CSV 格式匯入匯出 - 與主流記帳軟體的資料遷移 - 備份與復原功能 ## 9. 開發優先級 ### Phase 1 (MVP) 1. ✅ 基礎的 add_transaction 工具 2. ✅ get_balance 查詢功能 3. ✅ JSON 檔案儲存 4. ✅ 基本的錯誤處理 ### Phase 2 (增強) 1. ✅ list_transactions 篩選查詢 2. ✅ get_monthly_summary 統計 3. ✅ MCP Resources 實作 4. ✅ 完整的單元測試 ### Phase 3 (完善) 1. 🔄 互動式測試客戶端 2. 🔄 Claude Desktop 整合設定 3. 🔄 效能優化與錯誤復原 4. 🔄 使用文件與示範 --- *本 PRD 基於 MCP 1.0 協定標準，遵循 TDD 開發原則，確保每個功能都有對應的測試案例。*