内容
# D5 MCP
通过AI提示从Model Context Protocol（MCP）构建Divi / Elegant Themes WordPress页面的可行性验证（MVP）。
该软件包包含两个部分：
1. `mcp-server/` — 一个TypeScript MCP服务器，提供基于提示的Divi页面构建工具。
2. `wordpress-plugin/divi-ai-bridge/` — 一个WordPress插件，提供安全的REST端点用于创建/更新Divi Builder页面。
MVP默认创建**草稿页面**，采用**原生Divi 5序列化块格式**（`wp:divi/*`块），传统Divi 4短代码可通过`format: "divi4"`获得。在发布前，您可以在WordPress/Divi中审查页面。
---
## 本MVP的功能
- 检查与您的WordPress站点的连接。
- 读取基本站点上下文。
- 根据提示生成结构化的页面计划。
- 将验证的页面计划JSON渲染为原生Divi 5序列化块（默认）或传统Divi 4短代码。
- 创建或更新WordPress页面为Divi Builder草稿。
- 仅在您明确调用发布工具时发布。
批准的章节类型：
- `hero_luxury_split`
- `hero_centered_minimal`
- `logo_cloud`
- `services_3_cards`
- `services_grid_6`
- `about_image_text`
- `process_steps`
- `testimonials`
- `faq_accordion`
- `lead_capture_form`
- `cta_banner`
- `footer_minimal`
---
## 重要限制
这是生产就绪的MVP，而不是官方Elegant Themes产品。
它使用WordPress REST端点和Divi 5的序列化块存储格式（`<!-- wp:divi/section {...} -->`），这是Divi 5 Visual Builder保存的相同格式。生成的块仅使用验证的块类型和属性路径（`divi/section`，`divi/row`，`divi/column`，`divi/text`）；按钮、卡片、FAQ和CTA在`divi/text`模块内呈现为样式化的HTML，以确保可靠性，并且可以在Visual Builder中替换为原生按钮/手风琴/联系表单模块。
已知的Divi 5问题：通过编程方式创建的页面（而不是通过Visual Builder）可以在前端正确渲染，但Visual Builder可能不会在其图层面板中列出每个块以进行编辑。如果完整的可编辑性比原生D5存储更重要，请传递`format: "divi4"` — 传统短代码页面由Divi 5的官方迁移工具在您首次在构建器中打开它们时转换。
---
## 要求
- 具有HTTPS的WordPress站点。
- 已安装并激活Divi主题或Divi Builder。
- 本地计算机或服务器上的Node.js 20+。
- 具有编辑页面权限的WordPress用户。
- 该用户的WordPress应用程序密码。
- 兼容MCP的客户端，例如Claude Desktop、Cursor、Windsurf或其他可以运行stdio MCP服务器的客户端。
---
## 第1部分 — 安装WordPress桥接插件
### 选项A：使用FTP或主机文件管理器上传
1. 打开您的WordPress文件。
2. 进入：
```text
wp-content/plugins/
```
3. 上传此文件夹：
```text
wordpress-plugin/divi-ai-bridge
```
最终路径应为：
```text
wp-content/plugins/divi-ai-bridge/divi-ai-bridge.php
```
4. 登录到WordPress管理员。
5. 进入 **插件**。
6. 激活 **Divi AI Bridge**。
### 选项B：以ZIP文件上传
1. 将文件夹`wordpress-plugin/divi-ai-bridge`压缩为`divi-ai-bridge.zip`。
2. 在WordPress管理员中，进入 **插件 → 添加新 → 上传插件**。
3. 上传并激活它。
---
## 第2部分 — 创建WordPress应用程序密码
1. 在WordPress管理员中，创建一个专用用户，例如：
```text
用户名：divi_ai_editor
角色：编辑者
```
2. 进入 **用户 → 配置文件**，用于该用户。
3. 找到 **应用程序密码**。
4. 创建一个名为：
```text
Divi Elegant MCP
```
的密码
5. 立即复制它。WordPress只会显示一次。
仅使用HTTPS。应用程序密码使用基本身份验证，因此不得通过纯HTTP发送。
---
## 第3部分 — 安装MCP服务器
从软件包根目录：
```bash
cd mcp-server
npm install
cp .env.example .env
```
编辑`.env`：
```env
WP_BASE_URL=https://yourwebsite.com
WP_USERNAME=divi_ai_editor
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
DEFAULT_PAGE_STATUS=draft
```
构建服务器：
```bash
npm run build
```
在本地测试：
```bash
npm run dev
```
服务器使用stdio，因此它将“等待”MCP消息。这是正常的。
---
## 第4部分 — 手动测试WordPress插件
替换以下值：
```bash
curl --user "divi_ai_editor:YOUR_APPLICATION_PASSWORD" \
https://yourwebsite.com/wp-json/divi-ai/v1/health
```
预期响应：
```json
{
"ok": true,
"plugin": "Divi AI Bridge",
"version": "0.1.0",
"user": "divi_ai_editor",
"can_edit_pages": true
}
```
然后测试站点上下文：
```bash
curl --user "divi_ai_editor:YOUR_APPLICATION_PASSWORD" \
https://yourwebsite.com/wp-json/divi-ai/v1/site
```
---
## 第5部分 — 将MCP服务器添加到您的AI客户端
### Claude Desktop示例
打开您的Claude Desktop MCP配置文件。
macOS：
```text
~/Library/Application Support/Claude/claude_desktop_config.json
```
Windows：
```text
%APPDATA%\Claude\claude_desktop_config.json
```
添加：
```json
{
"mcpServers": {
"divi-elegant": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/divi-elegant-mcp/mcp-server/dist/index.js"],
"env": {
"WP_BASE_URL": "https://yourwebsite.com",
"WP_USERNAME": "divi_ai_editor",
"WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
"DEFAULT_PAGE_STATUS": "draft"
}
}
}
}
```
重启Claude Desktop。
### Cursor / Windsurf样式示例
使用相同的命令和参数：
```json
{
"divi-elegant": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/divi-elegant-mcp/mcp-server/dist/index.js"],
"env": {
"WP_BASE_URL": "https://yourwebsite.com",
"WP_USERNAME": "divi_ai_editor",
"WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
}
}
}
```
确切的配置屏幕因客户端而异，但命令相同。
---
## MCP服务器公开的工具
### `health_check`
检查插件是否安装以及身份验证是否有效。
### `get_site_context`
返回站点名称、URL、活动主题和REST URL。
### `list_approved_divi_sections`
返回允许的章节库。
### `generate_page_plan`
在不写入WordPress的情况下创建结构化的页面计划。
示例提示：
```text
使用Divi Elegant MCP为位于安曼的豪华牙科诊所首页生成页面计划。受众：家庭和专业人士。提供：美容牙科、植入物、正畸。语气：优雅和令人放心。
```
### `render_divi_layout`
在不写入WordPress的情况下，将验证的页面计划转换为Divi布局（默认情况下为Divi 5块，使用`format: "divi4"`时为短代码）。
### `create_divi_draft_page`
从页面计划创建或更新WordPress草稿页面。
### `build_elegant_divi_page_from_prompt`
一步MVP：生成页面计划，渲染Divi布局，并创建一个草稿页面。
示例提示：
```text
使用Divi Elegant MCP为迪拜的一家精品招聘机构创建优雅的Divi草稿首页。受众：CEO和人力资源主管。提供：高管搜索、人力资源咨询、薪酬咨询。语气：高级、温暖、自信。网址：home。品牌主题：黑色、暖米色、金色装饰、Playfair Display标题、Inter正文。不要发布。
```
### `publish_page_after_approval`
发布ID的页面。仅在手动审查和明确批准后使用。
---
## 推荐的工作流程
1. 要求AI调用`health_check`。
2. 要求它调用`get_site_context`。
3. 要求它生成页面计划。
4. 审查计划。
5. 要求它创建Divi草稿页面。
6. 在WordPress中打开预览/编辑链接。
7. 在Divi Visual Builder中审查。
8. 手动发布或调用`publish_page_after_approval`。
---
## 示例品牌主题
```json
{
"brandName": "HR180 Business Solutions",
"style": "elegant, minimal, premium consulting",
"colors": {
"primary": "#111111",
"secondary": "#F6F1EA",
"accent": "#C7A76C",
"text": "#202020",
"muted": "#747474",
"white": "#FFFFFF"
},
"fonts": {
"heading": "Playfair Display",
"body": "Inter"
},
"spacing": {
"sectionDesktop": "96px",
"sectionTablet": "72px",
"sectionMobile": "52px"
},
"buttons": {
"radius": "999px",
"style": "outlined"
}
}
```
---
## 安全检查清单
- 使用专用的WordPress用户，而不是您的主要管理员帐户。
- 授予用户所需的最低角色。从编辑者开始。
- 仅使用HTTPS。
- 将`.env`或MCP客户端环境配置中的应用程序密码保密。
- 不要将`.env`提交到GitHub。
- 默认创建页面为草稿。
- 发布前审查每个页面。
- 保留插件和MCP服务器日志。
- 定期轮换应用程序密码。
- 不需要时禁用或删除应用程序密码。
- 在生产前在测试环境中测试。
---
## 故障排除
### 来自WordPress的401或403
检查：
- `WP_USERNAME`是WordPress登录用户名，而不是显示名称。
- 应用程序密码复制正确。
- 站点是HTTPS。
- WordPress用户可以编辑页面。
- 安全插件没有阻止REST API基本身份验证。
### 插件端点未找到
检查：
- 插件处于活动状态。
- 固定链接有效。
- 尝试访问：
```text
https://yourwebsite.com/wp-json/divi-ai/v1/health
```
### 页面已创建，但Divi无法正确打开
检查：
- Divi主题或Divi Builder处于活动状态。
- 打开页面编辑器并手动启用Divi Builder。
- 保存页面。
- 先测试一个简单的生成页面。
### 布局看起来过于简单
此MVP优先考虑安全生成。通过在`mcp-server/src/divi/sectionLibrary.ts`中扩展更丰富的Divi模块、自定义CSS类和您的保存设计系统来改进它。
---
## 如何扩展为完整的生产产品
下一个改进：
1. 添加媒体上传支持。
2. 添加菜单创建和首页分配。
3. 添加完整的网站生成：首页、关于、服务、博客、联系。
4. 为客户添加保存的品牌配置文件。
5. 添加更丰富的章节库。
6. 添加自定义CSS生成，并严格允许列表。
7. 添加回滚/版本历史。
8. 如果您的Elegant Themes帐户/工作流程支持，请添加Divi Cloud或保存的布局集成。
9. 添加质量保证工具：检查损坏的按钮、缺少的CTA、移动间距、SEO标题长度、重复的slug。
10. 添加预发布/生产分离。
---
## 文件映射
```text
divi-elegant-mcp/
README.md
examples/
homepage-plan.json
mcp-server/
package.json
tsconfig.json
.env.example
src/
index.ts
wordpress/client.ts
schemas/theme.ts
schemas/page.ts
divi/blocks.ts
divi/sectionLibrary5.ts
divi/shortcodes.ts
divi/sectionLibrary.ts
divi/layoutBuilder.ts
prompts/elegant-homepage.md
wordpress-plugin/
divi-ai-bridge/
divi-ai-bridge.php
```
---
## 远程部署（Docker / VPS）
服务器在两种模式下运行：
- **stdio** （默认）：由Claude Desktop/Cursor本地启动。使用`WP_*`环境变量。
- **可流式HTTP** （当设置`PORT`时）：远程端点`POST /mcp/<key>`，可从任何地方用作Claude自定义连接器。
### 多租户密钥
- `MCP_AUTH_TOKEN` — 管理员密钥；请求到`/mcp/<MCP_AUTH_TOKEN>`使用`WP_*`环境凭证。
- `USERS_FILE` （`data/users.json`）— 每用户密钥到其自己的WordPress站点凭证的JSON映射。每个用户在其站点上安装`divi-ai-bridge`插件，创建应用程序密码，并获取其自己的密钥/URL。参见`data/users.json.example`。该文件在每次请求时重新读取，因此您可以添加用户而无需重启。
### 使用Docker Compose部署
```bash
git clone https://github.com/moeadas/D5MCP.git && cd D5MCP
cp .env.example .env # 填写MCP_AUTH_TOKEN（openssl rand -hex 32）+ WP_* 凭证
cp data/users.json.example data/users.json # 可选：添加每用户站点
docker compose up -d --build
curl http://localhost:3111/ # {"ok":true,...}
```
端点：`http://<server>:3111/mcp/<key>`。在使用它作为Claude自定义连接器之前，请将其放在HTTPS后面（反向代理、Cloudflare Tunnel或您的面板代理）——claude.ai需要HTTPS。
### 安全注意事项
- 密钥是URL路径中的长随机字符串；像密码一样对待。
- 使用编辑者级别的WordPress用户，绝不能使用管理员。
- `data/users.json`保存凭证 — 将其排除在git之外（已经忽略）并且仅对容器可读（以只读方式挂载）。
