Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Accounting MCPRecord a $15 lunch expense in the food category"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
記帳 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),遵循「紅-綠-重構」循環:
紅階段: 先寫失敗的測試案例
綠階段: 編寫最小實作使測試通過
重構階段: 優化程式碼品質與結構
執行測試
# 執行所有測試
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-filesMCP 整合
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 檔案儲存
支援事務性操作
自動備份與復原
錯誤處理
完整的輸入驗證
優雅的錯誤復原
詳細的錯誤日誌
擴充與客製化
新增新的工具
在
tools.py中定義新的工具函式在
server.py中註冊工具編寫對應的測試案例
自訂分類
修改 data/categories.json 檔案,新增自訂的支出分類。
資料匯入匯出
未來版本將支援 CSV 格式的資料匯入匯出功能。
授權
本專案僅用於學習與示範目的,基於 MIT 授權開源。
貢獻
歡迎提交 Issues 和 Pull Requests 來改進專案。
建構於 MCP 1.0 協定之上,遵循最佳實務與 TDD 開發原則。