Skip to main content
Glama
annie25726

Accounting MCP

by annie25726

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

-
security - not tested
F
license - not found
-
quality - not tested

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/annie25726/accounting-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server