内容
# 🦁 拉维拉媒体引擎
> **AI驱动的Safari营销内容引擎** — 生成品牌Instagram帖子、视频和音频，完全可通过MCP服务器控制，该服务器直接连接到Claude Desktop或任何MCP兼容的AI代理。
[](https://github.com/jaguar999paw-droid/lavira-media-engine/actions/workflows/build-desktop.yml) [](https://nodejs.org)
[](https://docker.com)
[](https://modelcontextprotocol.io)
[](LICENSE)
---
## 功能概述
拉维拉媒体引擎自动完成Safari营销的全内容流程：
- **获取真实的库存媒体** 从Pexels（照片+视频）和GIPHY
- **合成品牌图像** — 叠加徽标、目的地、钩子文本、联系信息 — 以Instagram/Facebook/TikTok分辨率
- **生成AI字幕** 使用Claude（Anthropic）生成钩子、哈希标签和CTA
- **处理音频** — 归一化为广播标准（-16 LUFS），导出OGG/MP3
- **直接发布** 到Instagram、Facebook和TikTok（使用令牌）
- **运行调度器** — 自动生成每日促销，时间：06:00 EAT
- **暴露52个MCP工具** 以便Claude Desktop（或任何AI代理）可以通过对话控制整个流程
---
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ 您的机器/服务器 │
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ lavira-engine │ │ lavira-mcp │ │
│ │ :4005 │ │ :4006 │ │
│ │ │ │ │ │
│ │ Express HTTP │ │ MCP Server │ │
│ │ ├─ Web UI (/) │ │ ├─ SSE → /sse │ │
│ │ ├─ REST API │ │ ├─ RPC → /rpc │ │
│ │ │ /api/* │ │ └─ Health → /health │ │
│ │ └─ 静态文件 │ │ │ │
│ │ /outputs/* │ │ 52个工具暴露 │ │
│ └────────┬─────────┘ └──────────┬───────────────┘ │
│ │ │ │
│ └──────── lavira-net ───────┘ │
│ （Docker桥） │
│ 共享SQLite卷 │
└─────────────────────────────────────────────────────────┘
↑ ↑
浏览器 / curl Claude Desktop
（Web UI + REST） （MCP客户端）
```
### 关键文件
```
lavira-media-engine/
├── src/
│ ├── server.js # Express — Web UI + REST API (:4005)
│ ├── config.js # 所有配置来自环境变量（零硬编码）
│ ├── mcp/server.js # MCP服务器 — stdio或HTTP+SSE (:4006)
│ ├── engines/
│ │ ├── promo.js # 核心品牌图像生成
│ │ ├── compositor.js # 多层Sharp合成
│ │ ├── card-templates.js # 10个SVG卡片模板
│ │ ├── external-media.js # Pexels照片+视频搜索
│ │ ├── giphy.js # GIPHY GIF获取
│ │ ├── audio.js # FFmpeg音频处理
│ │ └── video.js # FFmpeg视频处理
│ ├── orchestrator/
│ │ ├── brand.js # 品牌字典（编辑您的品牌）
│ │ ├── memory.js # SQLite作业历史
│ │ └── settings.js # 管理员设置（持久化）
│ ├── content/
│ │ ├── ai-captions.js # Claude字幕生成
│ │ └── captions.js # 模板字幕（无需API）
│ ├── routes/
│ │ ├── intake.js # /api/intake/* — 上传，giphy，自动
│ │ └── output.js # /api/job/*, /api/files/*
│ ├── publishing/
│ │ ├── instagram.js # Instagram Graph API
│ │ └── index.js # 多平台发布器
│ └── scheduler/index.js # node-cron每日促销，时间：06:00
├── public/index.html # 单文件Web UI（无需构建步骤）
├── docker-compose.yml # 双服务栈
├── Dockerfile # Node 20 + FFmpeg + Sharp
├── start.sh # ✅ 标准启动脚本
├── mcp-stdio.sh # Claude Desktop_stdio模式包装器
├── .env.example # 复制 → .env并填写密钥
└── .gitignore
```
### 端口映射
| 端口 | 容器 | 目的 |
|------|-----------|---------|
| `4005` | `lavira-media-engine` | Web UI + REST API |
| `4006` | `lavira-mcp` | MCP服务器（SSE + RPC） |
---
## 先决条件
| 需求 | 版本 | 注意 |
|-------------|---------|-------|
| Docker | 24+ | 推荐设置所需 |
| Docker Compose | v2（捆绑） | `docker compose`（不是`docker-compose`） |
| Node.js | 20+ | 仅本地/开发模式需要 |
| FFmpeg | 任意 | 仅本地/开发模式需要 |
---
## 设置 — Docker（推荐，所有平台）
### Linux / macOS
```bash
# 1. 克隆
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
# 2. 配置
cp .env.example .env
nano .env # 填写您的API密钥（参见下面的环境变量）
# 3. 启动
bash start.sh
# 4. 打开
# Web UI： http://localhost:4005
# MCP SSE： http://localhost:4006/sse
```
### Windows — 快速设置 ⭐ 推荐
> **Windows用户的最快路径。** 一个zip文件，一个双击。
**[⬇ 下载 `lavira-media-engine-windows-setup.zip`](https://github.com/jaguar999paw-droid/lavira-media-engine/releases/latest)**
1. 安装 **[Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)** — 免费，~500 MB — 然后重启您的PC
2. 解压zip文件到任意位置，例如 `C:\LaviraMedia\`
3. 双击 **`start.bat`**
该脚本检查Docker，自动创建您的`.env`（打开记事本填写API密钥），拉取镜像，启动引擎，并在您的浏览器中打开 **http://localhost:4005**。有关完整指南，请参见zip文件中的`SETUP.md`，包括Claude Desktop MCP设置。
---
### Windows（PowerShell）
```powershell
# 1. 克隆
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
# 2. 配置
Copy-Item .env.example .env
notepad .env # 填写您的API密钥
# 3. 启动（必须运行Docker Desktop）
docker compose down --remove-orphans
docker compose up -d
# 4. 打开浏览器 → http://localhost:4005
```
### Windows（WSL2）— 推荐用于Windows用户
```bash
# 在WSL2终端中：
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
cp .env.example .env && nano .env
bash start.sh
# 浏览器： http://localhost:4005
```
> **Windows用户注意：** 安装带有WSL2后端启用的[Docker Desktop](https://www.docker.com/products/docker-desktop/)。不要使用旧的Hyper-V后端。
### 验证它是否正在运行
```bash
curl http://localhost:4005/api/health
# 预期： {"status":"ok","engine":"Lavira Media Engine v3.0",...}
curl http://localhost:4006/health
# 预期： {"status":"ok","tools":52}
```
---
## 设置 — 本地开发（无Docker）
如果您想在不重建容器的情况下修改代码，请使用此方法。
### Linux / macOS
```bash
# 安装Node.js 20（如果需要）
# macOS： brew install node
# Ubuntu： sudo apt install nodejs npm
# 或使用nvm： https://github.com/nvm-sh/nvm
# 安装FFmpeg
# macOS： brew install ffmpeg
# Ubuntu： sudo apt install ffmpeg
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
npm install
cp .env.example .env && nano .env
# 终端1 — Web UI + API
node src/server.js
# 终端2 — MCP服务器（HTTP模式）
node src/mcp/server.js --http 4006
```
### Windows（原生，无WSL）
```powershell
# 安装Node.js从https://nodejs.org （LTS）
# 从https://ffmpeg.org/download.html安装FFmpeg
# 将FFmpeg添加到PATH（系统环境变量）
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
npm install
Copy-Item .env.example .env
notepad .env
# PowerShell — 终端1
node src/server.js
# PowerShell — 终端2
node src/mcp/server.js --http 4006
```
### macOS（Homebrew）
```bash
brew install node ffmpeg git
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
npm install
cp .env.example .env && open -e .env # 在TextEdit中打开
node src/server.js &
node src/mcp/server.js --http 4006 &
```
---
## 环境变量
复制`.env.example` → `.env`并填写您的值。引擎在没有可选密钥的情况下会以降级模式运行（字幕回退到模板，媒体搜索被禁用等）。
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `PORT` | 否（默认：4005） | Web UI + API端口 |
| `UPLOADS_DIR` | 否 | 上传文件路径 |
| `OUTPUTS_DIR` | 否 | 生成文件路径 |
| `ASSETS_DIR` | 否 | 品牌资产路径（徽标，字体） |
| `DB_PATH` | 否 | SQLite数据库路径 |
| `ANTHROPIC_API_KEY` | **推荐** | Claude AI — 字幕+视频脚本。在[console.anthropic.com](https://console.anthropic.com)获取 |
| `PEXELS_API_KEY` | **推荐** | Stock photos + videos.在[pexels.com/api](https://www.pexels.com/api/)获取免费额度 |
| `GIPHY_API_KEY` | 可选 | GIF搜索+下载。在[developers.giphy.com](https://developers.giphy.com)获取 |
| `INSTAGRAM_ACCESS_TOKEN` | 可选 | 发布到Instagram。需要Meta Developer App |
| `INSTAGRAM_USER_ID` | 可选 | 您的Instagram Business账户ID |
| `FACEBOOK_ACCESS_TOKEN` | 可选 | 发布到Facebook页面 |
| `FACEBOOK_PAGE_ID` | 可选 | 您的Facebook页面ID |
| `TIKTOK_ACCESS_TOKEN` | 可选 | 发布到TikTok |
---
## MCP集成
MCP服务器是AI代理的主要接口。它公开了**52个工具**，涵盖了整个内容流程。
### 连接Claude Desktop
**选项A — stdio（本地安装，无Docker）**
编辑 `~/.config/Claude/claude_desktop_config.json`（Linux/macOS）或
`%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"lavira-media-engine": {
"command": "bash",
"args": ["/absolute/path/to/lavira-media-engine/mcp-stdio.sh"],
"env": {
"ANTHROPIC_API_KEY": "your-key-here",
"PEXELS_API_KEY": "your-key-here",
"GIPHY_API_KEY": "your-key-here"
}
}
}
```
> 在Windows上使用`"command": "bash"`与Git Bash或WSL，或`"command": "node"`与`"args": ["C:\\path\\to\\src\\mcp\\server.js"]`
**选项B — HTTP/SSE（Docker或远程服务器）
```json
{
"mcpServers": {
"lavira-media-engine": {
"url": "http://localhost:4006/sse"
}
}
```
编辑后，**重启Claude Desktop**。您应该在工具面板中看到Lavira工具列表。
### 连接其他MCP客户端
```
SSE端点： http://localhost:4006/sse
RPC端点： http://localhost:4006/rpc
健康检查： http://localhost:4006/health
```
### 可用的MCP工具（26）
| 类别 | 工具 | 功能 |
|----------|------|-------------|
| **工作流程** | `create_post_workflow` | 端到端：获取媒体 → 品牌 → 字幕 → 包 |
| | `generate_auto_promo` | 零输入：选择目的地，获取库存图像，品牌化 |
| | `generate_promo_package` | AI字幕 + 钩子 + CTA + 哈希标签 任意目的地 |
| | `generate_marketing_payload` | 完整的营销内容包 |
| **媒体** | `fetch_optimal_media` | 为目的地获取最佳匹配的Pexels照片/视频 |
| | `search_stock_images` | 按关键字搜索Pexels |
| | `search_external_media` | 带有智能排名的Pexels + Unsplash搜索 |
| | `process_image` | 裁剪，旋转，颜色校正上传的照片 |
| | `process_video` | 自动裁剪 + 水印视频 |
| | `process_audio` | 将音频规范化为广播标准 |
| **品牌** | `apply_overlay` | 添加徽标 + 联系栏到任意图像 |
| | `make_ready_to_post` | 完整的品牌化叠加层 + 钩子 + 目的地 + Promo类型 |
| | `generate_branded_media` | 分析 + 品牌化一步到位 |
| | `generate_card_template` | 10个SVG卡片设计 |
| | `generate_all_cards` | 所有10个卡片变体 |
| **GIPHY** | `search_giphy` | 搜索Safari GIF |
| | `use_giphy` | 下载GIF + 生成品牌化促销 |
| **作业** | `list_recent_jobs` | 已生成内容历史 |
| | `get_job_status` | 轮询特定作业 |
| | `approve_job` | 标记作业已批准，记录它 |
| | `reject_job` | 标记作业需要重做 |
| **发布** | `post_to_instagram` | 发布到Instagram（需要令牌） |
| | `post_to_facebook` | 发布到Facebook页面 |
| | `post_to_tiktok` | 发布到TikTok |
| | `publish_job` | 一次发布到多个平台 |
| | `schedule_post` | 安排到特定时间 |
| **系统** | `get_brand_info` | 完整的品牌字典 |
| | `get_api_status` | 哪些集成处于活动状态 |
| | `get_safari_packages` | 带有定价的所有Safari套餐 |
| | `get_destinations_to_feature` | LRU排名的目的地推荐 |
| | `get_daily_schedule` | 今日自动生成的计划 |
| | `trigger_daily_promo` | 立即运行每日促销 |
| | `get_admin_settings` | 读取持久化设置 |
| | `update_admin_settings` | 更新设置 |
| **缓存** | `cache_stats` | 外部媒体缓存信息 |
| | `cache_clear` | 清除所有缓存媒体 |
| | `cache_prune` | 删除过时缓存条目 |
### 示例对话Claude
连接后，您可以说：
```
"为今天的Amboseli生成一个Instagram帖子"
"为Masai Mara创建一个带有大象照片的品牌帖子"
"今天我应该重点介绍哪个目的地？"
"为Diani Beach生成所有10个卡片模板"
"搜索一个Safari GIF并准备发布"
"显示我过去5个作业"
"将作业abc123发布到Instagram"
```
---
## Web UI
在启动后，在浏览器中打开 `http://localhost:4005`。
UI 让您：
- **上传** 照片，视频或音频
- **自动生成** 带有一步点击的品牌帖子
- **浏览** 生成的输出并下载每个平台的文件
- **批准/拒绝** 作业
- **搜索GIPHY** 并将GIF变成品牌促销
- **配置** 管理员设置和社会令牌
---
## 避免端口冲突（重要）
引擎使用4005和4006端口。如果您在UI上看到“连接中...”或MCP连接失败：
```bash
# 检查端口上运行的内容
sudo lsof -i :4005 -i :4006
# 杀死裸金属节点上的非Docker进程
kill $(lsof -ti :4005 :4006)
# 或仅运行启动脚本 — 它会自动处理
bash start.sh
```
**永远不要同时运行 `node src/server.js` 和Docker — 它们将在端口4005上冲突。**
---
## 为您的品牌定制（自定义）
编辑 `src/orchestrator/brand.js` — 这是品牌词典：
```javascript
const BRAND = {
name: '您的公司名称',
website: 'https://yourwebsite.com',
phone: '+1 234 567 8900',
email: 'info@yourcompany.com',
destinations: ['地点 A', '地点 B', ...],
// ...
};
```
所有叠加层，字幕和卡片模板都从此文件中提取。无需编辑其他文件即可重新品牌化。
---
## 故障排除
| 问题 | 原因 | 修复 |
|---------|-------|-----|
| UI 卡在“连接中...” | 引擎容器未运行 | `bash start.sh` |
| UI 卡在“连接中...” | 端口冲突（裸金属节点 vs Docker） | `kill $(lsof -ti :4005)` 然后 `bash start.sh` |
| MCP 工具未显示在Claude中 | 配置文件路径错误或输入错误 | 检查 `claude_desktop_config.json`，重启Claude |
| `SQLITE_BUSY` 错误 | 两个写入者位于同一数据库 | 始终使用 `bash start.sh` — 它以只读模式启动MCP |
| `sharp` 安装错误 | 缺失原生依赖项 | 使用Docker — 它干净地处理原生依赖项 |
| FFmpeg 未找到（本地模式） | FFmpeg 未安装 / 未在PATH中 | 为您的操作系统安装FFmpeg（参见设置部分） |
| `/mcp` 端点上的 401 错误 | ssh-shell-mcp 身份验证令牌 | 与 Lavira 无关 — 这是另一个 MCP 服务器 |
---
## 项目结构（完整）
```
lavira-media-engine/
├── src/
│ ├── config.js
│ ├── server.js # Web UI + REST API
│ ├── mcp/server.js # MCP服务器
│ ├── engines/
│ │ ├── audio.js
│ │ ├── card-templates.js # 10个SVG卡片设计
│ │ ├── compositor.js
│ │ ├── dynamic-templates.js
│ │ ├── external-media.js # Pexels集成
│ │ ├── giphy.js
│ │ ├── image.js
│ │ ├── media-augmentation.js
│ │ ├── media-cache.js
│ │ ├── media-library.js
│ │ ├── media-mixer.js
│ │ ├── promo.js
│ │ ├── video.js
│ │ ├── video-script.js
│ │ ├── card-templates.js # 3种布局家族（Minimal Float，Split Panel，Immersive Overlay）
│ │ ├── image-vision.js # Claude Vision — 安全文本区域 + 场景分析
│ │ ├── post-defaults.js # 智能默认值解析器（情绪/季节/LRU）
│ │ └── context-pools.js # 曲目词汇（钩子，CTA，角度）
| ├── orchestrator/
| │ ├── brand.js # ← 编辑此文件以适应您的品牌 |
| │ ├── memory.js # SQLite 作业历史
| │ └── settings.js
| ├── content/
| │ ├── ai-captions.js
| │ └── captions.js
| ├── routes/
| │ ├── intake.js
| │ └── output.js
| ├── publishing/
| │ ├── index.js
| │ └── instagram.js
| └── scheduler/index.js
├── public/index.html # Web UI（无需构建步骤）
├── assets/ # 品牌资产（徽标，字体）
├── samples/ # 测试样本媒体
├── docker-compose.yml
├── Dockerfile
├── start.sh # ← 始终使用此命令启动
├── start-clean.sh # 完整重建 + 重启
├── mcp-stdio.sh # Claude Desktop stdio 包装器
├── package.json
├── .env.example # 复制到 .env
└── .gitignore
```
## 桌面应用程序 (Windows / macOS / Linux)
> **无需终端，无需 Docker，无需 Node.js。** 桌面应用程序包含所有必要组件。
从 [**发布页面**](https://github.com/jaguar999paw-droid/lavira-media-engine/releases/latest) 下载适用于您平台的安装程序：
| 平台 | 文件 | 操作步骤 |
|---|---|---|
| **Windows 10/11** | `Lavira-Media-Setup-*.exe` | 双击 → 下一步 → 完成 → 从桌面打开 |
| **macOS 12+** | `Lavira-Media-Setup-*.dmg` | 打开 DMG → 拖拽到应用程序 → 启动 |
| **Linux** | `Lavira-Media-Setup-*.AppImage` | `chmod +x *.AppImage` → 双击 |
| **Linux (deb)** | `Lavira-Media-Setup-*.deb` | `sudo dpkg -i *.deb` → 在应用程序菜单中找到 |
### 桌面应用程序与 Docker 的不同之处
Electron 包装器在同一个应用程序包中以子进程启动 Express 引擎。您可以在 `localhost:4005` 访问完全相同的 Web 界面，在 `localhost:4006` 访问 MCP 服务器 — 但您不需要终端和 Docker，只需双击图标即可。
```
┌─────────────────────────────────────────────────────┐
│ Lavira Media (Electron 窗口) │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Web 界面 — http://localhost:4005 │ │
│ │ （完整的 studio，在应用程序中渲染） │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ 系统托盘图标 → 右键单击： │
│ 打开 Lavira | 在浏览器中打开 | 退出 │
└─────────────────────────────────────────────────────┘
↑
MCP 服务器仍然在 :4006 — 以与 Docker 设置相同的方式连接 Claude 桌面应用程序
```
### 首次启动 — 设置向导
首次运行时，设置向导会在启动引擎之前询问您的 API 密钥：
| 密钥 | 是否必填 | 获取地址 |
|---|---|---|
| **Anthropic API 密钥** | ✅ | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) |
| **Pexels API 密钥** | 可选（免费） | [pexels.com/api](https://www.pexels.com/api/) |
| **GIPHY API 密钥** | 可选（免费） | [developers.giphy.com](https://developers.giphy.com/) |
密钥保存在应用程序数据目录中的 `.env` 文件中。您可以在 Web 界面的设置面板中随时更新它们。
### 从源代码构建
```bash
# 1. 克隆并安装根目录依赖
git clone https://github.com/jaguar999paw-droid/lavira-media-engine.git
cd lavira-media-engine
npm install
# 2. 安装 Electron 构建依赖
cd electron && npm install && cd ..
# 3. 在开发模式下运行（打开窗口，使用本地 .env）
cd electron && npm start
# 4. 为当前平台构建安装程序
cd electron
npm run build:win # Windows → electron/dist/*.exe
npm run build:mac # macOS → electron/dist/*.dmg
npm run build:linux # Linux → electron/dist/*.AppImage + *.deb
```
## 贡献
欢迎提交拉取请求。请将密钥保存在 `.env` 文件中，切勿保存在源代码中。测试前请运行 `bash start.sh`。
---
*为 [Lavira Safaris](https://lavirasafaris.com) 构建 · 由 Node.js、FFmpeg、Sharp、Anthropic Claude 和 Pexels 提供支持*
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器