🚀 WhatsApp Flows API MCP Server

🚀 WhatsApp Flows API MCP 服务

✨ 功能特性

• 🐳 Docker 化架构 - 完整的容器化配置，包含 Redis 和后台处理
• 🔧 模块化 ERP 集成 - 支持 Business Central、SAP、Oracle 和自定义 ERP 系统
• ⚡ 后台处理 - 异步任务处理，支持处理大型客户列表
• 📱 WhatsApp Flow 管理 - 通过 WhatsApp Business API 创建并发送交互式调查
• 📊 监控工具 - 内置任务监控和 Redis 管理仪表板
• 🔄 开发支持 - 热重载和开发容器，支持快速迭代

🚀 快速开始

前置条件

开始之前，请确保已准备好：

• ✅ 已安装 Docker 和 Docker Compose
• ✅ WhatsApp Business API 凭据
• ✅ 已配置环境变量

1️⃣ 克隆并配置

git clone https://github.com/Ronnie-Leon76/whatsapp-flows-mcp-server.git
cd whatsapp-flows-mcp-server

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your WhatsApp Business API credentials

2️⃣ 启动服务

🏭 生产模式

make start
# or
./scripts/start.sh

🛠️ 开发模式（支持热重载）

make start-dev
# or
./scripts/start-dev.sh

3️⃣ 访问服务

🏗️ 架构

Docker 服务概览

graph TB
    A[MCP Server] --> D[Redis Job Queue]
    B[Job Worker 1] --> D
    C[Job Worker 2] --> D
    D --> E[Job Dashboard]
    D --> F[Redis Commander]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#f3e5f5
    style D fill:#ffebee
    style E fill:#e8f5e8
    style F fill:#fff3e0

核心服务

🛠️ 命令参考

Make 命令

NPM 脚本

npm run docker:build      # Build Docker images
npm run docker:start      # Start production services
npm run docker:start-dev  # Start development services
npm run docker:stop       # Stop all services
npm run docker:logs       # View logs

⚙️ 配置

🔑 必需的环境变量

# WhatsApp Business API Configuration
WHATSAPP_ACCESS_TOKEN=your_access_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id_here
WHATSAPP_BUSINESS_ACCOUNT_ID=your_business_account_id_here
WHATSAPP_VERIFY_TOKEN=your_verify_token_here

🔧 可选的环境变量

# Redis Configuration (auto-configured in Docker)
REDIS_URL=redis://redis:6379/0

# Worker Configuration
WORKER_CONCURRENCY=5

# Dashboard Configuration
PORT=3001

# Paths (auto-configured in Docker)
CONFIG_PATH=/app/config
SURVEYS_PATH=/app/surveys

🛠️ 开发

热重载开发

# Start development environment with hot reload
make start-dev

# View development logs
docker-compose -f docker-compose.dev.yml logs -f

本地开发（不使用 Docker）

# Start Redis locally
docker run -d -p 6379:6379 redis:7-alpine

# Install dependencies
npm install

# Start MCP server
npm run dev

# Start worker (in separate terminal)
cd celery_app
celery -A tasks worker --loglevel=info

📊 监控与调试

📈 任务仪表板

访问 **http://localhost:3001**，即可：

• ✅ 监控进行中和已完成的任务
• 📋 查看任务详情和进度
• 👥 监控工作进程状态
• ⚡ 实时跟踪任务执行情况

💾 Redis Commander

访问 **http://localhost:8081**，即可：

• 🔍 浏览 Redis 键
• 📊 监控 Redis 性能
• 👁️ 查看存储的数据
• 🔧 调试 Redis 问题

🔧 新增 MCP 工具

• send-survey - 为大型客户列表处理后台作业
• get-job-status - 监控后台作业进度
• get-queue-stats - 查看作业队列统计信息

📜 查看日志

# All services
make logs

# Specific service
docker-compose logs -f mcp-server
docker-compose logs -f job-worker
docker-compose logs -f redis

# Follow logs in real-time
docker-compose logs -f --tail=100

🚀 生产环境部署

Docker Compose 生产环境

# Start production services
make start

# Scale workers
docker-compose up -d --scale job-worker=4

# Update services
docker-compose pull
docker-compose up -d

🏥 健康检查

所有服务都包含全面的健康检查：

💾 持久化数据

通过 Docker 卷持久化数据：

🔧 故障排除

常见问题

# Check Docker status
docker-compose ps

# View service logs
make logs

# Check system resources
docker stats

# Test Redis connection
make redis-cli
ping

# Check Redis logs
docker-compose logs redis

# Check worker status
make logs-celery

# Access job dashboard
open http://localhost:3001

# Check Redis queue
make redis-cli
LLEN job_queue

# Verify .env file exists and is configured
cat .env

# Restart services
make restart

# Check environment in container
docker-compose exec mcp-server env | grep WHATSAPP

🔍 调试

# Access container shells
make shell-mcp      # MCP server container
make shell-celery   # Worker container

# View container resources
docker stats

# Inspect container configuration
docker-compose config

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。