内容
# CC5 MCP 服务器
[](LICENSE)
[](https://github.com/modelcontextprotocol/sdk)
一个 MCP（模型上下文协议）服务器，允许像 Claude 这样的 LLM 通过自然语言控制 **Reallusion Character Creator 5**。调整面部特征，应用身体预设，捕获视口截图，加载资产，导出 FBX 文件 - 所有这些都可以通过对话式命令。
## 架构
```
┌─────────────┐ stdio ┌──────────────────┐ HTTP :5101 ┌──────────────────┐ RLPy ┌─────┐
│ LLM 客户端 │ ◄────────────► │ MCP 服务器 │ ◄──────────────► │ CC5 插件 │ ◄──────────► │ CC5 │
│ (Claude) │ │ (Node.js / TS) │ │ (Python / Qt) │ │ │
└─────────────┘ └──────────────────┘ └──────────────────┘ └─────┘
```
MCP 服务器通过 **stdio** 传输与 Claude 通信，并通过 **HTTP** 将命令转发到在 CC5 中运行的 Python 插件。插件通过 QTimer 驱动的命令队列在主线程上执行所有 RLPy API 调用，确保线程安全。
## 功能
### MCP 工具（44）
MCP 服务器提供 44 种工具，涵盖 14 个模块，用于控制 CC5：
#### 场景和头像管理
| 工具 | 描述 |
|------|-------------|
| `check_cc5_connection` | 验证 CC5 是否正在运行且桥接插件是否激活 |
| `list_avatars` | 列出当前场景中的所有头像 |
| `list_scene_objects` | 列出所有场景对象（头像、道具、灯光、相机） |
| `get_avatar_info` | 获取头像详细信息，包括所有非零形态值 |
| `create_avatar` | 在场景中创建一个新的 CC3+ 基础头像 |
| `describe_character` | 当前角色外观的自然语言描述 |
#### 形态控制
| 工具 | 描述 |
|------|-------------|
| `search_morphs` | 按关键字搜索形态目录 |
| `adjust_morph` | 调整单个形态滑块（-1.0 至 1.0） |
| `adjust_multiple_morphs` | 批量调整多个形态滑块 |
| `get_morph_value` | 查询形态滑块的当前值 |
| `reset_morphs` | 将所有形态重置为零 |
| `apply_body_preset` | 应用身体类型预设（运动员、肌肉发达、苗条、沉重、平均） |
#### 内容和资产
| 工具 | 描述 |
|------|-------------|
| `list_clothes` | 列出当前头像的服装 |
| `list_hair` | 列出当前头像的头发 |
| `list_accessories` | 列出当前头像的配饰 |
| `remove_scene_item` | 按名称删除服装、头发或配饰 |
| `browse_content` | 浏览 CC5 内容文件夹（服装、鞋子等） |
| `load_asset` | 加载 CC5 资产文件（.iAvatar、.ccm、.iClothes 等） |
| `export_fbx` | 将当前头像导出为 FBX 文件。镜像 CC5 “导出 FBX”对话框：`target_tool` 预设，`export_motion`（“网格和运动”），`sub_d_level`（HD 细分），`embed_textures`，`fps`，`motion_range`，`convert_image_format`，`texture_size`。裸文件名导出到 `D:\CC5Export`（通过 `CC5_EXPORT_DIR` 覆盖）。 |
| `create_actor_mixer` | 从打开的头像生成 ActorMIXER PRO 混音器资产（.ccMixerPreset）。`confirm_create` 门控试运行（false，CANCELs）与实际创建（true）。需要 ActorMIXER PRO 插件。 |
#### 材料和颜色
| 工具 | 描述 |
|------|-------------|
| `get_material_info` | 获取网格和材料名称 |
| `get_diffuse_color` | 获取材料的漫反射颜色 |
| `set_diffuse_color` | 设置漫反射颜色（RGB，0.0-1.0） |
| `set_eye_color` | 设置眼睛颜色（便捷快捷方式） |
| `set_hair_color` | 设置头发颜色（便捷快捷方式） |
| `set_lip_color` | 设置嘴唇颜色（便捷快捷方式） |
#### 可见性和显示
| 工具 | 描述 |
|------|-------------|
| `set_item_visible` | 显示或隐藏场景项目 |
#### 相机和灯光
| 工具 | 描述 |
|------|-------------|
| `get_camera_info` | 获取相机位置和焦距 |
| `set_camera_focal_length` | 设置相机焦距 |
| `get_lights` | 列出场景中的所有灯光 |
| `set_light_color` | 设置灯光颜色（RGB） |
#### 表达和动画
| 工具 | 描述 |
|------|-------------|
| `get_expression_info` | 获取可用的表达组和滑块 |
#### 渲染和导出
| 工具 | 描述 |
|------|-------------|
| `capture_viewport` | 捕获 CC5 3D 视口截图 |
| `set_subdivision_level` | 设置 HD 细分级别（0 = 基础，1 = 中等，2 = HD） |
#### 编辑和历史
| 工具 | 描述 |
|------|-------------|
| `undo` | 撤销上一个操作 |
| `redo` | 重做已撤销的操作 |
#### 高级功能
| 工具 | 描述 |
|------|-------------|
| `execute_python` | 在 CC5 中执行 Python 代码（仅开发模式） |
| `execute_rlpy` | 直接执行 RLPy API 调用（仅开发模式） |
| `metahuman_export` | 导出到 MetaHuman（当可用时） |
### MCP 资源
| 资源 URI | 描述 |
|-------------|-------------|
| `cc5://morphs/catalog` | 所有形态滑块的完整目录，按类别分组 |
| `cc5://avatar/current` | 当前头像状态，包含所有活动形态值 |
## 先决条件
- **Node.js** 18+ 和 npm
- **Reallusion Character Creator 5** （CC5）
- **Windows** （CC5 仅支持 Windows）
## 快速入门
### 1. 构建 MCP 服务器
```bash
git clone <repo-url> cc5-mcp-server
cd cc5-mcp-server
npm install
npm run build
```
### 2. 安装 CC5 插件
在 **管理员 PowerShell** 中运行：
```powershell
powershell -ExecutionPolicy Bypass -File install-plugin.ps1
```
这会从 CC5 的 OpenPlugin 目录创建到 `cc5-plugin/` 文件夹的符号链接。
### 3. 配置 Claude 代码
在 `~/.claude.json` 中添加 `mcpServers`：
```json
{
"cc5": {
"command": "node",
"args": ["<path-to-project>/build/index.js"],
"env": {
"CC5_BRIDGE_URL": "http://127.0.0.1:5101"
}
}
}
```
将 `<path-to-project>` 替换为存储库的绝对路径。
### 4. 启动桥接
**选项 A：自动（推荐）** - 启动 CC5。插件会自动从 `OpenPlugin/CC5_MCP_Bridge/` 加载。必要时在插件管理器中启用它。
**选项 B：手动** - 在 CC5 中，转到脚本 > 加载 Python 并选择 `start_bridge.py`。
### 5. 验证连接
询问 Claude：*“检查 CC5 是否连接”* - 它将调用 `check_cc5_connection` 并报告状态。
## 使用示例
### 创建和定制角色
> “创建一个新头像并使他们具有运动型，鼻子略大”
Claude 将调用：
1. `create_avatar` - 添加一个基础头像
2. `apply_body_preset`，预设为 “athletic”
3. `adjust_morph`，`morph_id` 为 “Nose_Size”，值为 0.6
### 描述和调整
> “我的角色是什么样子？让下巴更宽。”
Claude 将调用：
1. `describe_character` - 读取当前形态状态
2. `adjust_morph`，`morph_id` 为 “Jaw_Width”，值为 0.7
### 批量修改
> “给角色一个更圆的脸和更柔软的特征”
Claude 将调用 `adjust_multiple_morphs`，并传递一个包含多个形态调整的数组，用于脸颊、下巴、 chin 等。
### 为游戏引擎导出
> “将此角色导出为 FBX 到我的项目文件夹”
Claude 将调用 `export_fbx`，并指定输出路径。
该工具复制了 CC5 的“导出 FBX（InstaLOD）”对话框。推荐的 Unreal（UE5 Skeleton）调用是：
```jsonc
{
"output_path": "character.fbx", // 裸文件名 -> D:\CC5Export\character.fbx
"target_tool": "UE5", // 目标工具预设：Unreal（UE5 Skeleton）
"export_motion": true, // FBX 选项：网格和运动
"sub_d_level": 0, // HD 角色细分级别：SubD 0
"embed_textures": true, // 纹理设置：嵌入纹理 = 开启
"fps": 30 // 包含运动：帧率 = 30（当前动画 = 所有）
}
```
传递裸文件名（无目录组件）默认导出到 `D:\CC5Export` - 通过 `CC5_EXPORT_DIR` 环境变量覆盖目录。使用绝对路径时原样使用。省略 `motion_range` 保留对话框默认的“所有”。
## 配置
| 环境变量 | 默认值 | 描述 |
|---------------------|---------|-------------|
| `CC5_BRIDGE_URL` | `http://127.0.0.1:5101` | CC5 桥接 HTTP 服务器的完整 URL |
| `CC5_BRIDGE_PORT` | `5101` | 桥接服务器的端口（在 `cc5-plugin/main.py` 中设置） |
| `CC5_DEV_MODE` | `1` | 启用热重载（`/reload` 端点）和开发界面（0 = 生产，1 = 开发） |
| `CC5_ALLOW_EXEC` | *(未设置)* | 启用 `/exec/python` 和 `/exec/rlpy` 端点（仅在设置时激活，无论 DEV_MODE 如何） |
| `CC5_RELOAD_SECRET` | *(空)* | `/reload` 端点的身份验证令牌。如果设置，请求必须包含 `X-Reload-Token` 头部 |
| `CC5_REQUEST_TIMEOUT_MS` | `30000` | MCP 服务器端的 HTTP 请求超时（毫秒） |
| `CC5_ROOT` | `C:\Program Files\Reallusion\Character Creator 5` | CC5 安装路径（用于默认头像加载） |
| `CC5_EXPORT_DIR` | `D:\CC5Export` | 当给定裸文件名（无目录）时，`export_fbx` 的默认输出文件夹。由桥接插件读取。 |
## 开发
### 构建
```bash
npm run build # 编译 TypeScript
npm run dev # 监视模式（更改时重新编译）
```
### 测试
```bash
npm test # 运行测试
npm run test:watch # 监视模式
npm run test:coverage # 包含覆盖率报告
```
### 热重载 Python 插件
桥接支持热重载 `cc5_api.py` 而无需重启 CC5：
```bash
# 无身份验证
curl http://127.0.0.1:5101/reload
# 带身份验证（当 CC5_RELOAD_SECRET 设置时）
curl -H "X-Reload-Token: <secret>" http://127.0.0.1:5101/reload
```
重载后，服务器的分派表会自动使用更新的功能修补。
### 项目结构
```
cc5-mcp-server/
├── src/ # MCP 服务器（TypeScript）
│ ├── index.ts # 入口点
│ ├── cc5-bridge.ts # CC5 桥接的 HTTP 客户端
│ ├── types.ts # 类型定义
│ ├── util.ts # 共享实用程序（bridgeCall 包装器）
│ ├── tools/ # MCP 工具定义（14 个文件，共 44 个工具）
│ │ ├── morph.ts # 形态搜索、调整、重置（5 个工具）
│ │ ├── scene.ts # 场景/头像管理（6 个工具）
│ │ ├── asset.ts # 资产加载 / FBX 导出（2 个工具）
│ │ ├── character.ts # 身体预设、角色描述（2 个工具）
│ │ ├── content.ts # 服装、头发、配饰、浏览（5 个工具）
│ │ ├── color.ts # 眼睛、头发、嘴唇颜色设置（3 个工具）
│ │ ├── material.ts # 材料信息、漫反射颜色（7 个工具）
│ │ ├── camera.ts # 相机焦距控制（2 个工具）
│ │ ├── light.ts # 灯光颜色和信息（4 个工具）
│ │ ├── visibility.ts # 显示/隐藏物品（2 个工具）
│ │ ├── edit.ts # 撤销/重做（2 个工具）
│ │ ├── expression.ts # 表达信息（1 个工具）
│ │ ├── scripting.ts # Python/RLPy 执行（1 个工具）
│ │ └── metahuman.ts # MetaHuman 导出（2 个工具）
│ └── resources/
│ └── morphs.ts # 形态目录和头像状态资源
├── cc5-plugin/ # CC5 Python 插件
│ ├── main.py # 插件入口（initialize_plugin / uninitialize_plugin）
│ ├── server.py # HTTP 桥接服务器（http.server）
│ ├── cc5_api.py # RLPy API 包装器
│ └── config.json # 插件配置
├── start_bridge.py # 手动桥接启动脚本
├── install-plugin.ps1 # 插件安装程序（需要管理员）
└── claude-mcp-config.json # Claude Code MCP 配置片段
```
## API 参考
### GET 端点
| 端点 | 描述 | 响应 |
|----------|-------------|----------|
| `GET /health` | 健康检查 | `{"result": {"status": "ok", "service": "cc5-mcp-bridge", "version": "..."}}` |
| `GET /api` | API 发现（所有端点和必需参数） | `{"result": {"service": "...", "endpoints": {...}}}` |
| `GET /reload` | 热重载 cc5_api 模块 | `{"result": {"success": true}}` |
| `GET /avatars` | 列出所有场景头像 | `{"result": [{"name": "...", "id": "...", "type": "..."}]}` |
| `GET /avatar/info` | 当前头像详细信息 + 活动形态 | `{"result": {"name": "...", "active_morphs": {...}}}` |
| `GET /morphs/catalog` | 完整的形态目录，按类别分组 | `{"result": {"Category": [{"id": "...", "display_name": "..."}]}}` |
### POST 端点
| 端点 | 参数 | 描述 |
|----------|-----------|-------------|
| `POST /morph/get` | `morph_id` | 获取当前形态值 |
| `POST /morph/set` | `morph_id`, `value` | 设置形态滑块（-1.0 至 1.0） |
| `POST /morphs/set` | `morphs`（`{id, value}` 数组） | 同时设置多个形态（每个 -1.0 至 1.0） |
| `POST /avatar/create` | *(无)* | 创建默认 CC3+ 头像 |
| `POST /asset/load` | `file_path` | 加载 CC5 资产文件 |
| `POST /export/fbx` | `output_path`, `options`（可选） | 导出头像为 FBX |
| `POST /viewport/capture` | `output_path`（可选） | 捕获视口截图 |
| `POST /subdivision` | `level`（0-2） | 设置 HD 细分级别 |
所有响应都遵循信封格式：成功时为 `{"result": ...}`，失败时为 `{"error": "..."}`。
## 安全
- **仅限 localhost** - 桥接服务器仅绑定到 `127.0.0.1`。MCP 服务器验证 `CC5_BRIDGE_URL` 指向 localhost 之前连接。
- **路径验证** - TypeScript MCP 服务器和 Python 插件都验证文件路径以防止路径遍历（..）攻击。只有加载资产和导出时才接受允许的文件扩展名。
- **重载身份验证** - `/reload` 端点支持通过 `CC5_RELOAD_SECRET` 环境变量和 `X-Reload-Token` 头部进行令牌身份验证。
- **请求大小限制** - 桥接强制执行 1 MB 的最大请求体大小。
- **线程安全** - 所有 RLPy API 调用都通过命令队列序列化，并在 CC5 的主线程上执行，使用 QTimer。
## 许可证
MIT
