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用心打造 ❤️