JinDaGe - mcp-wygiwyh MCP Details

article

README

🚀 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令牌

安装步骤

克隆仓库

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

配置环境

cp .env.example .env
# 使用你的凭证编辑.env文件
# 别忘了在server.py中更改你的WYGIWYH URL

使用Docker部署
```
./deploy.sh
```
或者手动部署：
```
docker-compose up -d
```
验证部署
```
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工具：

解析WYGIWYH API的OpenAPI YAML文件
将模式转换为JSON Schema格式
为所有操作创建工具对象
处理复杂类型的 allOf 合并
通过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 - 技术架构文档

🤝 贡献

欢迎贡献代码！请遵循以下指南：

分叉仓库
创建功能分支
进行更改并添加测试
提交拉取请求

📄 许可证

🔗 链接

💬 支持

如有问题，请：

在GitHub上创建问题
查看现有文档
查看部署日志

由ReNewator.com用心打造 ❤️

mcp-wygiwyh