MCP Wygiwyh

🚀 WYGIWYH API MCP Server

這是一個生產就緒的模型上下文協議（MCP）服務器，它為WYGIWYH費用跟蹤API提供了一個通用接口。該服務器可根據OpenAPI規範動態生成75個MCP工具，使AI代理和自動化平臺（如n8n）能夠通過標準化的工具調用與費用跟蹤系統進行交互。

WYGIWYH 的原始倉庫

✨ 主要特性

• 🔄 動態工具生成：根據OpenAPI規範自動生成75個MCP工具
• 🔐 安全認證：MCP端點採用Bearer令牌認證，API訪問採用基本認證
• 🚀 HTTP可流式傳輸：與n8n和其他MCP客戶端完全兼容
• 🐳 生產就緒的Docker：經過優化的多階段構建，並帶有健康檢查
• ⚡ 異步/等待機制：高效的非阻塞API通信
• 📊 全面的API覆蓋：所有WYGIWYH API端點都作為工具公開

🎯 使用場景

• 使用n8n自動化費用跟蹤工作流程
• 構建管理財務數據的AI助手
• 創建與WYGIWYH API的自定義集成
• 實現語音控制的費用記錄
• 開發自動化報告系統

📦 安裝指南

前提條件

• Docker和Docker Compose
• WYGIWYH API憑證
• MCP Bearer令牌

安裝步驟

1. 克隆倉庫

   git clone https://github.com/ReNewator/MCP-WYGIWYH.git
   cd MCP-WYGIWYH
   

2. 配置環境

   cp .env.example .env
   # 使用你的憑證編輯.env文件
   # 別忘了在server.py中更改你的WYGIWYH URL
   

3. 使用Docker部署

   ./deploy.sh
   

   或者手動部署：

   docker-compose up -d
   

4. 驗證部署

   curl http://localhost:5000/health
   

🔧 配置

創建一個包含以下變量的 .env 文件：

# WYGIWYH API憑證
API_USERNAME=your_email@example.com
API_PASSWORD=your_password_here

# MCP服務器認證
MCP_TOKEN=your_mcp_bearer_token_here

🌐 n8n集成

配置n8n MCP客戶端節點：

• 端點：http://your-server:5000/
• 傳輸方式：HTTP可流式傳輸
• 認證方式：頭認證
  • 名稱：Authorization
  • 值：Bearer YOUR_MCP_TOKEN

🛠️ 可用工具

服務器公開了按類別組織的 75個MCP工具：

賬戶管理

• account-groups_* - 賬戶組操作（6個工具）
• accounts_* - 賬戶CRUD操作（6個工具）

交易管理

• transactions_* - 交易操作（6個工具）
• recurring-transactions_* - 定期交易管理（6個工具）
• installment-plans_* - 分期付款計劃處理（6個工具）

金融工具

• categories_* - 費用類別管理（6個工具）
• tags_* - 交易標籤（6個工具）
• currencies_* - 貨幣管理（6個工具）
• exchange-rates_* - 匯率操作（6個工具）

投資功能

• dca_* - 成本平均策略（15個工具）
• entities_* - 實體管理（6個工具）

使用 tools/list 方法查看所有可用工具及其模式。

📁 項目結構

.
├── mcp_sse_server.py      # 帶有HTTP可流式傳輸的主MCP服務器
├── server.py              # 核心MCP實現
├── test_server.py         # 驗證腳本
├── Dockerfile             # 生產Docker鏡像
├── docker-compose.yml     # Docker Compose配置
├── deploy.sh              # 自動化部署腳本
├── requirements.txt       # Python依賴項
├── DEPLOYMENT.md          # 詳細的部署指南
├── PROJECT.md             # 技術文檔
└── attached_assets/
    └── WYGIWYH API.yaml   # OpenAPI規範

🚀 部署

Docker（推薦）

# 構建並運行
docker-compose up -d

# 查看日誌
docker-compose logs -f

# 停止服務器
docker-compose down

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wygiwyh-mcp-server
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: mcp-server
        image: wygiwyh-mcp-server:latest
        ports:
        - containerPort: 5000
        env:
        - name: API_USERNAME
          valueFrom:
            secretKeyRef:
              name: wygiwyh-secrets
              key: api-username

雲平臺

• AWS ECS/Fargate：使用帶有環境變量的Docker鏡像
• Google Cloud Run：作為容器部署，並進行密鑰管理
• Azure Container Instances：直接從Docker Hub部署

詳細的雲部署說明請參閱 DEPLOYMENT.md。

🧪 測試

運行驗證腳本來驗證設置：

python test_server.py

這將顯示按類別分組的所有75個生成的MCP工具。

📊 API端點

• POST / - MCP JSON-RPC端點（需要Bearer令牌）
• GET /health - 健康檢查（無需認證）

🔒 安全特性

• ✅ MCP訪問採用Bearer令牌認證
• ✅ WYGIWYH API請求採用基本認證
• ✅ 非根容器用戶
• ✅ 通過環境變量管理密鑰
• ✅ 日誌中不暴露憑證

🏗️ 架構

動態工具生成

服務器根據OpenAPI規範自動生成MCP工具：

1. 解析WYGIWYH API的OpenAPI YAML文件
2. 將模式轉換為JSON Schema格式
3. 為所有操作創建工具對象
4. 處理複雜類型的 allOf 合併
5. 通過MCP協議公開工具

優點：

• 單一事實來源（OpenAPI規範）
• API更改時自動更新
• 無需手動定義端點
• 工具模式一致

認證流程

┌─────────────┐     Bearer Token     ┌─────────────┐
│   n8n/MCP   │ ──────────────────> │  MCP Server │
│   Client    │                      │             │
└─────────────┘                      └─────────────┘
                                            │
                                            │ Basic Auth
                                            ▼
                                     ┌─────────────┐
                                     │  WYGIWYH    │
                                     │     API     │
                                     └─────────────┘

🐛 故障排除

服務器無法啟動

# 檢查日誌
docker-compose logs

# 驗證環境
cat .env

認證錯誤

• 確保 API_USERNAME 是你的WYGIWYH電子郵件
• 驗證 API_PASSWORD 是否正確
• 檢查 MCP_TOKEN 是否與客戶端配置匹配

連接被拒絕

# 檢查服務器狀態
docker-compose ps

# 測試健康端點
curl http://localhost:5000/health

📚 詳細文檔

• DEPLOYMENT.md - 全面的部署指南
• PROJECT.md - 技術架構文檔

🤝 貢獻

歡迎貢獻代碼！請遵循以下指南：

1. 分叉倉庫
2. 創建功能分支
3. 進行更改並添加測試
4. 提交拉取請求

📄 許可證

版權所有 (c) 2025 ReNewator.com。保留所有權利。

🔗 鏈接

• WYGIWYH API文檔
• 模型上下文協議
• n8n自動化

💬 支持

如有問題，請：

• 在GitHub上創建問題
• 查看現有文檔
• 查看部署日誌

由ReNewator.com用心打造 ❤️