記帳 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（推薦，最快）

# 啟用您的 conda 環境
conda activate myenv

# 使用 uv 快速安裝依賴
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt

方案 2: 純 conda

# 啟用環境
conda activate myenv

# 安裝 Python 依賴
pip install -r requirements.txt
pip install -r requirements-dev.txt

方案 3: 純虛擬環境

# 建立虛擬環境
python -m venv venv
source venv/bin/activate  # macOS/Linux

# 安裝依賴  
pip install -r requirements.txt
pip install -r requirements-dev.txt

執行伺服器

# 直接執行 MCP 伺服器
python -m accounting_mcp.server

# 或執行互動式測試客戶端
python test_client.py

測試範例

# 新增一筆支出
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. 重構階段: 優化程式碼品質與結構

執行測試

# 執行所有測試
pytest

# 執行特定測試檔
pytest tests/test_models.py

# 產生覆蓋率報告
pytest --cov=accounting_mcp --cov-report=html

# 型別檢查
mypy accounting_mcp/

程式碼品質檢查

# 格式化程式碼
black accounting_mcp/ tests/

# 風格檢查
flake8 accounting_mcp/ tests/

# 執行所有品質檢查
pre-commit run --all-files

MCP 整合

Claude Desktop 設定

在 Claude Desktop 的設定檔中加入：

{
  "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 開發原則。