内容
# mc-iclone8-mcp
[Français](README.fr.md)
通过官方Python API控制iClone 8的本地MCP服务器。
iClone插件提供一个小型的启动/停止窗口。MCP端点是本地的，默认为`http://127.0.0.1:8766/mcp`。所有iClone命令在运行前都会发送回iClone的主线程。
## 要求
- Windows上的iClone 8。
- 支持Streamable HTTP MCP的客户端，例如Codex。
## 安装iClone插件
1. 将此存储库文件夹复制到：
```text
<iClone 8>\Bin64\OpenPlugin\mc-iclone8-mcp
```
2. 启动iClone 8并加载插件。
3. 打开 **插件 → mc-iclone8-mcp → 打开MCP服务器**。
4. 选择 **启动**。状态必须显示`http://127.0.0.1:8766/mcp`。
服务器故意绑定到`127.0.0.1`：它旨在为运行iClone的计算机使用，而不是用于网络连接。
## 作为Codex MCP服务器安装
保持iClone打开并启动服务器。首先运行：
```powershell
codex mcp add mc-iclone8-mcp --url http://127.0.0.1:8766/mcp
```
添加后重启Codex（或启动新任务）。通过以下命令确认配置：
```powershell
codex mcp list
```
或者，将以下内容添加到`%USERPROFILE%\.codex\config.toml`（或项目的`.codex\config.toml`）：
```toml
[mcp_servers.mc-iclone8-mcp]
url = "http://127.0.0.1:8766/mcp"
startup_timeout_sec = 15
tool_timeout_sec = 60
```
一个相同的可复制示例可在[`examples/codex-config.toml`](examples/codex-config.toml)中找到。
## 可用功能
服务器公开MCP工具以：
- 检查、选择、转换、显示和删除场景对象；
- 创建官方iClone图元、导入资产和保存项目；
- 控制时间线、相机和灯光；
- 检查和更改材质、颜色、纹理映射、不透明度、光泽度和自发光；
- 检查头像组件、皮肤骨骼、动画剪辑、循环次数和变形；
- 加载或预加载动作，应用Substance Painter纹理文件夹，导出单个对象为FBX；
- 检查当前渲染大小，并在明确确认后启动渲染；
- 检查iClone mocap状态和原生TCP/UDP可用性，无需打开外部连接。
插件针对iClone 8。它故意避免使用iClone 7专有API，包括iClone 8中删除的运动骨骼API。
## 代理示例指令
给代理一个明确的目标、对象名称和数值。代理可以先检查场景，然后调用相应的MCP工具。
| 类别 | 示例指令 |
| --- | --- |
| 场景 | “列出场景中的道具，然后选择`MCP8_Live_Test_Box`。” |
| 创建 | “在X=0，Y=0，Z=20处创建一个名为`Logo_Block`的红色方块，并在其下方添加一个地板。” |
| 变换 | “将`Logo_Block`移动到帧120的X=200处，并将其缩放至150%。” |
| 材质 | “列出`Logo_Block`上的材质，然后将材质0设置为皇家蓝色并隐藏其漫反射纹理。” |
| 纹理映射 | “将`C:\\Assets\\logo_basecolor.png`应用于`Logo_Block`上材质0的漫反射纹理。” |
| 材质动画 | “在帧300，将`Logo_Block`材质0的不透明度设置为0.25，自发光设置为0.8。” |
| 时间线 | “将播放头设置为帧0，播放帧0到300，然后停止。” |
| 相机 | “读取活动相机的焦距并将其设置为50毫米。” |
| 动画 | “使用帧0、150、300、450和600的变换键在`Center_Cube`周围动画化`Orbit_Sphere`。” |
| 头像 | “列出头像`Character1`的皮肤骨骼和动画剪辑。” |
| 头像播放 | “检查`Character1`的功能，然后将剪辑0设置为以1.2倍速度循环三次。” |
| 变形 | “列出`Character1`上的变形，然后将指定的面部变形设置为权重0.5在当前帧。” |
| 导入/导出 | “导入此`.iProp`文件，保存项目，然后将选定的对象导出为FBX。” |
| 渲染 | “读取渲染尺寸。只有我确认后，使用项目的当前iClone设置渲染视频。” |
| Mocap | “检查iClone mocap是否正在运行；不要更改或连接任何设备。” |
对于相机跟踪镜头，请使用真实的场景相机而不是iClone预览相机：“创建或激活`Camera1`，然后在与主题一致的偏移量下，在相同的帧上键控其变换。”
## 开发
```powershell
python -m compileall -q .
python -m unittest discover -s tests -v
```
主要技术参考是官方的[iClone 8 Python API文档](https://wiki.reallusion.com/IC8_Python_API)。
