内容
# moengage-mcp
一款适用于 [MoEngage](https://www.moengage.com) 营销平台的 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器。通过 stdio 提供活动和电子邮件模板工具，基于 [FastMCP](https://github.com/jlowin/fastmcp) 构建。
与 MoEngage 官方 MCP（分析导向、交互式 OAuth）不同，该服务器使用记录在案的 [Campaign/Content API](https://www.moengage.com/docs/api/introduction)，采用纯 API 密钥身份验证 — 它运行在无头模式下，并且读取 **活动定位**（通过 `search_campaigns` 的完整 `segmentation_details` 过滤器树），这是官方服务器未公开的。
## 工具
### 活动（9）
| 工具 | 是否修改 | 目的 |
|---|---|---|
| `search_campaigns` | 否 | 搜索/筛选活动；返回配置 **包括完整的定位过滤器树** (`segmentation_details`)。除非 `include_content=true`，否则电子邮件 `html_content` 将被字节数取代 |
| `get_campaign_meta` | 否 | 简洁身份视图：状态、渠道、投送类型、团队、标签、日期（无定位） |
| `get_child_executions` | 否 | 循环（定期）活动的单个运行 |
| `get_personalized_preview` | 否 | 渲染活动内容，带有为样本属性解析的占位符 |
| `get_campaign_stats` | 否 | ⚠ 上游禁用 — 除非 `MOENGAGE_ENABLE_STATS=true`，否则隐藏；当 MoEngage 重新启用该端点时重新启用 |
| `create_campaign` | **是** | 创建活动 |
| `update_campaign` | **是** | 更新活动配置 |
| `change_campaign_status` | **是** | 激活 / 暂停 / 停止活动 |
| `test_campaign` | **是** | 向命名收件人发送真正的测试推送/电子邮件 |
### 电子邮件模板（9）
| 工具 | 是否修改 | 目的 |
|---|---|---|
| `search_templates` | 否 | 搜索模板，带有过滤器和分页 |
| `analyze_template` | 否 | 将模板 HTML 解析为结构化内容节点 |
| `compare_templates` | 否 | 两个模板的结构化差异 |
| `build_email_template` | 否 | 构建 + 验证模板，返回结构化预览（不发布）；`autofix=true` 修复机械布局问题（隔离间距、缺失免责声明/页脚） |
| `get_server_info` | 否 | 数据中心 + 仪表盘基准 URL |
| `publish_template` | **是** | 构建 + 验证 + 发布到 MoEngage |
| `update_template` | **是** | 更新现有模板 |
| `localize_template` | **是** | 发布翻译的市场变体 |
| `patch_template_text` | **是** | 修改特定文本节点，无需重建 |
工具返回结构化预览，从不返回原始 HTML — 大型负载将溢出代理的上下文窗口。
**权限控制写入：** 服务器提供所有工具；请在您的 MCP 客户端中限制修改工具（例如 Claude Code `permissions.allow` 仅列出读取工具）。读取和写入工具共享 MoEngage 的活动 API 速率限制（5/分钟，25/小时，100/天）— 避免分散调用。
## 安装和运行
```bash
pip install git+https://github.com/poddubnyoleg/moengage_mcp.git
moengage-mcp # stdio
```
Claude Code / Claude Desktop 配置：
```json
{
"mcpServers": {
"moengage": {
"type": "stdio",
"command": "moengage-mcp"
}
}
}
```
## 配置
环境变量（或本地 `.env`，参见 `.env.example`）：
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `MOENGAGE_API_KEY` | 是 | 活动/Content API 密钥（仪表盘 → 设置 → APIs） |
| `MOENGAGE_WORKSPACE_ID` | 是 | 工作区（应用）ID |
| `MOENGAGE_DATA_CENTER` | 是 | 区域数据中心，例如 `02` 表示 `dashboard-02.moengage.com` |
| `MOENGAGE_FOOTER_CONFIG` | 否 | 电子邮件页脚组件的品牌链接 — 内联 JSON 或文件路径（模式在 `footer.py` 中）；如果没有，则页脚仅包含取消订阅链接 |
| `MOENGAGE_ENABLE_STATS` | 否 | 设置为 `true` 以注册 `get_campaign_stats`（默认情况下隐藏，因为上游端点已禁用） |
API 错误（包括轮换密钥时的 401）以结构化错误字典返回，因此消耗代理可以报告它们而不是不透明地失败。
## 备注
- `content/email/TEMPLATE_GUIDELINES.md` 记录了一个示例房屋样式，模板验证器强制执行（组件顺序、CTA 合规性、Jinja 规则）— 适应您的品牌。
- 只有 MoEngage 为一次性计划活动返回受众可达性计数，不适用于周期性活动。
## 许可证
MIT
