# EvaCloud Web MCP 集成指南

## 概述

EvaCloud Web 提供 19 个 MCP 工具，可通过 Hermes Desktop (EvaCloud) 集成，实现 AI 驱动的智能建站管理。

## MCP 端点

- **URL**: https://3or.cc/api/mcp
- **认证**: x-api-key header（全局管理密钥）或 x-tenant-token header（租户级令牌，推荐数字员工使用）
- **密钥**: evacloud-web-mcp-key-2026
- **协议**: JSON-RPC 2.0

## 添加到 Hermes Desktop

```bash
hermes mcp add evacloud-web \
  --url https://3or.cc/api/mcp \
  --api-key evacloud-web-mcp-key-2026
```

## 租户级 MCP 令牌（v7.2 新增）

全局 x-api-key 可操作所有租户，仅限管理员使用。数字员工应使用租户级令牌，绑定单一租户，防止跨租户越权。

### 获取令牌（管理员）

```bash
# 生成（需 admin JWT）
curl -X POST https://3or.cc/api/admin/tenants/{tenant_id}/mcp-token \
  -H 'Authorization: Bearer <admin_jwt>' -H 'Content-Type: application/json'

# 吊销
curl -X DELETE https://3or.cc/api/admin/tenants/{tenant_id}/mcp-token \
  -H 'Authorization: Bearer <admin_jwt>'
```

令牌为 24 字节随机 hex，服务端仅存 SHA-256 摘要。请安全保管，不得暴露给终端用户。

### 使用令牌调用

```bash
curl -X POST https://3or.cc/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'x-tenant-token: <tenant_token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tenant_info","arguments":{}}}'
```

- 令牌调用可省略 tenant_id 参数，服务端自动推导为令牌租户
- 显式传入他人 tenant_id 会被拦截：-32003 Tenant scope mismatch
- 无鉴权请求返回 401；令牌吊销后立即失效

## 可用工具 (19个)

### 文件操作工具 (5个)

#### 1. site_list_files
列出租户网站目录下的文件。
- **输入**: `tenant_id` (number, 必填), `dir` (string, 可选子目录)
- **输出**: 文件列表 (name, path, type, size, mtime)
- **安全**: 只读，目录隔离

#### 2. site_read_file
读取租户网站文件内容。
- **输入**: `tenant_id` (number, 必填), `path` (string, 必填, 相对路径)
- **输出**: 文件内容 (text)
- **安全**: 只读，路径验证

#### 3. site_ai_write_file
AI 安全写入文件（仅限 HTML/CSS/JS，自动安全扫描）。
- **输入**: `tenant_id` (number, 必填), `path` (string, 必填), `content` (string, 必填)
- **安全**: 8层路径验证 + 扩展名白名单 + 内容安全扫描（禁止 PHP/system/eval 等）+ 自动备份 + 审计日志
- **限制**: 仅允许 .html, .css, .js 扩展名

#### 4. site_write_file
写入/修改租户网站文件（管理员权限）。
- **输入**: `tenant_id` (number, 必填), `path` (string, 必填), `content` (string, 必填)
- **安全**: 扩展名白名单 + 路径遍历防护 + 自动备份 + 审计日志

#### 5. site_delete_file
删除租户网站文件（自动备份）。
- **输入**: `tenant_id` (number, 必填), `path` (string, 必填)
- **安全**: 删除前自动备份，路径验证

### 站点统计工具 (1个)

#### 6. site_get_stats
获取租户站点统计信息。
- **输入**: `tenant_id` (number, 必填)
- **输出**: 文件总数、总大小、各类型文件数量

### 文章管理工具 (4个)

#### 7. article_create
创建文章。
- **输入**: `tenant_id` (number, 必填), `title` (string, 必填), `content` (string, 必填), `summary` (string, 可选), `status` (string, 可选: "draft"|"published"), `category_id` (number, 可选)
- **输出**: 文章 ID, slug, status

#### 8. article_list
列出租户的文章列表。
- **输入**: `tenant_id` (number, 必填), `status` (string, 可选过滤), `limit` (number, 可选)
- **输出**: 文章数组 (id, title, slug, status, created_at)

#### 9. article_update
更新文章内容。
- **输入**: `tenant_id` (number, 必填), `article_id` (number, 必填), `title` (string, 可选), `content` (string, 可选), `status` (string, 可选)
- **输出**: 更新结果

#### 10. article_delete
删除文章。
- **输入**: `tenant_id` (number, 必填), `article_id` (number, 必填)
- **输出**: 删除结果

### 栏目管理工具 (2个)

#### 11. category_create
创建栏目。
- **输入**: `tenant_id` (number, 必填), `name` (string, 必填), `slug` (string, 可选), `sort_order` (number, 可选)
- **输出**: 栏目 ID

#### 12. category_list
列出栏目录。
- **输入**: `tenant_id` (number, 必填)
- **输出**: 栏目数组

### 租户信息工具 (1个)

#### 13. tenant_info
获取租户信息和统计。
- **输入**: `tenant_id` (number, 必填)
- **输出**: 租户信息、文章数、文件数、存储使用量

### SEO 工具 (2个)

#### 14. seo_analyze
分析租户网站的 SEO 状态。
- **输入**: `tenant_id` (number, 必填)
- **输出**: SEO 评分 (0-100), 优化建议, 当前配置

#### 15. seo_update
更新 SEO 配置。
- **输入**: `tenant_id` (number, 必填), `site_title` (string, 可选), `site_description` (string, 可选), `site_keywords` (string, 可选), `structured_data` (object, 可选)
- **输出**: 更新结果

### 分析工具 (1个)

#### 16. analytics_get
获取站点访问分析数据。
- **输入**: `tenant_id` (number, 必填), `period` (string, 可选: "7d"|"30d"|"90d")
- **输出**: 访问量统计、每日趋势、热门页面

### AI 工具 (1个)

#### 17. ai_generate_article
AI 生成文章。
- **输入**: `tenant_id` (number, 必填), `topic` (string, 可选), `language` (string, 可选: "zh-CN"|"en"|"ja")
- **输出**: 生成的文章内容 (title, summary, content, seo_info)

### 备份工具 (2个)

#### 18. site_backup_list
列出文件的备份版本列表。
- **输入**: `tenant_id` (number, 必填), `path` (string, 可选)
- **输出**: 备份版本数组 (timestamp, size, filename)

#### 19. site_backup_restore
从备份版本恢复文件。
- **输入**: `tenant_id` (number, 必填), `backup_filename` (string, 必填)
- **安全**: 恢复前自动备份当前版本

## 安全架构

### 目录隔离
每个租户有独立的隔离目录 `/sites/{tenant_id}/`，所有文件操作限制在此目录内。

### 路径验证（8层防护）
1. 参数类型检查
2. 路径清理（去空格、统一斜杠）
3. 禁止模式检查（.., ~, node_modules, .git, .env）
4. 扩展名白名单
5. 扩展名黑名单
6. 隐藏文件禁止编辑
7. 路径前缀验证（防目录穿越）
8. .backups 目录禁止直接编辑

### 扩展名控制
- **白名单**: .html, .css, .js, .json, .png, .jpg, .gif, .svg, .ico, .woff, .woff2, .ttf, .txt, .md, .xml
- **黑名单**: .php, .py, .sh, .exe, .bat, .cmd, .env, .sql, .conf, .pem, .key, .crt

### 备份自动清理
- 每日凌晨3点自动清理30天前备份 (crontab)
- 支持手动触发: GET/POST /api/admin/backups/cleanup

### AI 编辑安全
- 仅允许编辑前端文件 (HTML/CSS/JS)
- 内容安全扫描：禁止 PHP 代码、system()、exec()、eval()、base64_decode() 等
- 所有 AI 操作记录到 site_events 表

### 自动备份
- 每次 write/delete 前自动创建备份
- 保留 30 个版本
- 超过30天自动清理

### 审计日志
- 所有操作记录到 site_audit_logs 表
- 记录：tenant_id, operator_type, operator_id, action, file_path, file_size, backup_path, ip_address

### 资源配额
- 单文件大小限制: 50MB
- 单租户总存储限制: 500MB
- 速率限制: 120 次/分钟/IP

## 使用示例

### AI 数字员工编辑官网首页
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "site_ai_write_file",
    "arguments": {
      "tenant_id": 1,
      "path": "index.html",
      "content": "<!DOCTYPE html>..."
    }
  },
  "id": 1
}
```

### AI 数字员工发布文章
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "article_create",
    "arguments": {
      "tenant_id": 1,
      "title": "企业新闻标题",
      "content": "<p>文章内容...</p>",
      "summary": "文章摘要",
      "status": "published"
    }
  },
  "id": 1
}
```

### AI 数字员工分析 SEO
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "seo_analyze",
    "arguments": {
      "tenant_id": 1
    }
  },
  "id": 1
}
```

## 集成流程

1. 在 Hermes Desktop 中配置 MCP 服务器（品牌增长 -> 官网维护数字员）
2. 在品牌增长设置中填写站点地址 (mcp_base_url) 与租户令牌 (EVACLOUD_WEB_MCP_TENANT_TOKEN)
3. 创建"官网维护数字员"Agent，配置 website_* 动作集（13 个动作）
4. 数字员工通过 MCP 工具管理官网（前端编辑 / 文章发布 / SEO 优化）
5. 所有操作被租户隔离 + 安全扫描 + 审计日志记录

## 维护与监控

- 审计日志: 查看 site_audit_logs 表
- 事件日志: 查看 site_events 表
- 文件备份: 每个文件保留 30 个版本，超30天自动清理
- 系统监控: https://3or.cc/admin-panel/ (管理员登录)
- 备份清理: 每日凌晨3点自动执行，也可手动触发