# FairyGUI MCP 0.8.4-dev.2

**官方编辑器外部试用版，不是稳定版或全功能兼容认证。** 原生模式直接通过工程插件调用官方 FairyGUI 编辑器；无需重构编辑器服务，也无需修改官方程序。

- 新用户先看：[官方编辑器安装与验收](docs/OFFICIAL_EDITOR_TESTING.md)。
- 本次更新范围、已知边界与回退：[0.8.4-dev.2 试用说明](docs/RELEASE_084_DEV2.md)。
- 默认原生模式 **36 个工具**；可选 `source_*` 属于另一个独立后端，不是测试官方包的前置条件。
- 原生插件元数据仍为 `0.6.0`，但本次插件字节已更新；升级时按安装说明备份并替换整个工程插件，不能只比较版本号。

通过工程插件和原版编辑器 API 操作 FairyGUI 的独立 MCP 工具。
基于 [wingcd/fairygui-agent-bridge](https://github.com/wingcd/fairygui-agent-bridge)
的 MIT 源码改造；保留原许可，见 [UPSTREAM.md](UPSTREAM.md)。

**这不是 FairyGUI 编辑器源码，也不包含编辑器程序、SDK、用户工程、反编译产物或访问令牌。**
无需修改编辑器二进制。原版 GUI 进程需要运行；不是 headless 编辑器。

## 架构与范围

```text
MCP client → Node stdio server → authenticated 127.0.0.1 HTTP
                                      ↓
                              project-local JS plugin
                                      ↓
                              original editor API

Optional source_* tools → explicitly configured external Python backend
```

- 本版本默认 **36 个工具**：读取工程/组件、创建组件、插入/删除对象、改属性、保存、发布、日志、启动等。
- 配置独立重建后端后增加 4 个 `source_*` 工具，共 **40 个**；通用模式的声音上传、模式查询、浏览器预览各显式增加 1 个工具，再显式开启回执维护增加 2 个工具，全部开启共 **45 个**。重建编辑器/HTTP 服务不在本仓库中；可选的 HTTP 适配器随 source_backend/ 分发，不是原生模式的运行依赖。
- 原生编辑和离线重建是两套执行层，工具说明中明确区分。
- 已在 **Windows / FairyGUI Editor 6.1.4、6.0.5** 验证部分原生功能；逐项范围见 docs/NEXT.md，不是全部 API 的兼容性保证。
- `refresh` 已验证外部资源导入；导入异步完成，应轮询读取。`screenshot` 已验证原生 UI 内容截图与独立 PNG 文件检查。
- 发布验证检查原生成功状态、对应包文件的新近时间、FGUI 文件头、包 ID、大小和 SHA256。
  **不声称已解码所有字段、渲染一致或与 GUI 发布逐字节相等。**
  当前验证器支持常见 `<发布包名>.bytes` / `<发布包名>_fui.bytes` / `<发布包名>.fui`；自定义发布命名和格式需增加适配。

## 安装

依赖：Node.js 22+、Python 3.11+、已安装的 FairyGUI 编辑器。原生模式及通用 HTTP 适配器使用标准库；可选浏览器预览还需明确配置已安装的 Playwright 与浏览器，默认不安装、不下载。

先使用工程副本试运行。将仓库、工程和私有运行目录分别放置，例如：

```text
D:/FGUI-work/fairygui-mcp/   # 本仓库
D:/FGUI-work/project/       # 你自己的工程，含一个 .fairy
D:/FGUI-work/runtime/       # 私有 config.json、进程状态和日志
```

PowerShell 示例（替换为自己的绝对路径）：

```powershell
git clone https://github.com/BlacksoilShi/fairygui-mcp.git D:/FGUI-work/fairygui-mcp
python D:/FGUI-work/fairygui-mcp/setup.py `
  --project D:/FGUI-work/project `
  --editor D:/Apps/FairyGUI-Editor/FairyGUI-Editor.exe `
  --runtime D:/FGUI-work/runtime --port 17931
```

setup 生成随机令牌，不输出令牌、不覆盖已有配置、不修改工程。
默认发布目录和截图目录是工程的同级目录；端口支持 1024–65535。

在任意支持 stdio 的 MCP 客户端中添加：

```json
{
  "mcpServers": {
    "fgui": {
      "command": "node",
      "args": [
        "D:/FGUI-work/fairygui-mcp/server.mjs",
        "--config", "D:/FGUI-work/runtime/config.json"
      ]
    }
  }
}
```

配置中的 `python` 默认使用执行 setup 的解释器绝对路径。客户端找不到 Node 时，`command` 也使用绝对路径。
原生工具调用超时建议至少 **150 秒**；原生发布最多 120 秒，另留产物核验时间。通用后端设为最大 HTTP 超时时，客户端应至少留 **260 秒**；详见后端协议。

### 第一次使用

1. 调用 `editor_start`：安装工程插件并启动编辑器，或连接已经匹配的运行实例。
2. `ping` → `project_info` → `list_packages` → `read_component`。
3. 使用已确认的对象/资源名进行修改，再 `save_all` / `publish`。

已有插件文件与当前版本不一致时会报 `PLUGIN_CONFLICT`，不会静默覆盖。
先关闭对应编辑器、备份该工程的 `plugins/fgui-agent-bridge-custom`，再明确更新插件。
外部已经打开相同工程但未加载插件时，应先关闭它再启动，避免同工程多实例写入。
`editor_start` 不扫描或关闭无关进程，也不会自动重试失败的启动。

## 可选的独立重建后端

在私有配置中增加两个绝对路径：

```json
{
  "sourceHelper": "D:/your-rebuild/helper.py",
  "sourceConfig": "D:/your-rebuild/config.json"
}
```

这是配置片段，不是完整配置。两个字段同时配置才启用四个 `source_*` 工具。
后端应使用同一个配置的 Python 解释器，接受 `helper.py COMMAND JSON_ARGS`，
从 `FGUI_MCP_CONFIG` 读取配置，stdout 仅返回 `{"ok":true,"result":...}` 或错误 JSON。
当前兼容适配约定为固定 `Gesture/Main`，属性对象 `n0/n1`，同次调用内 undo/redo；
并非任意工程通用重建器。调用该后端就是执行本地 Python 代码，仅配置可信文件。


### 通用重建后端（显式选择）
上面的配置保留旧版固定 Gesture/Main 适配。需要任意工程/组件选择时，在同一私有配置中另加
`"sourceProtocol": "fgui-rebuild-http/1"`。此时四个固定工具被四个通用工具替换，
不是叠加：`source_capabilities`、`source_state`、`source_command`、
`source_receipt_read`，基础模式仍为 40 个工具。编辑器 HTTP 服务需单独安装并已启动；本仓库同时分发可选的 HTTP 适配器。

再显式设置 `"sourceUploads": true` 且后端配置导入根目录，才增加
`source_sound_upload`（共 41 个）。上传不是原版编辑器导入，也不是音频解码验证。
大结果通过有界快照或持久回执分页，调用方需按实际 nextOffset 拼接并核对 SHA256。
迁移预览的短期 planToken 可通过 MCP 传回；它不是身份认证令牌，过期或历史回执不续期。

配置、尺寸限制、去重/未知结果语义见 [通用后端协议](docs/SOURCE_BACKEND.md)、
[上传约定](docs/SOUND_UPLOAD.md) 与 [迁移租约](docs/MIGRATION_PLAN_LEASES.md)。
原生 session/revision 与独立后端 session/revision 分开，交叉使用无效。

## 原生发布与中断恢复
`publish` 支持 configured/all/selected/trunk 模式。selected 要求非空 branch；all/trunk 不接受 branch。
configured 仅在当前配置采用单分支处理时接受 branch，全分支配置会明确报错而非忽略参数。
只处理当前配置工程；source_* 与原生发布是两套执行层。详见 [发布范围](docs/RELEASE_060.md)。

仅在明确处理此前中断的原生发布时调用 `editor_start({"recoverPublish":true})`。
普通启动行为不变。外部 Windows helper 核验旧进程身份并签发短期证明，原生插件完成
设置落盘回读和匹配记录清理后才报告恢复。存活/身份不明、磁盘冲突或清理失败仍保持阻塞。
不要手工删租约或按锁文件年龄猜测进程已退出。见 [恢复协议](docs/PUBLISH_OWNER_PROOF.md)。

## 测试

```powershell
cd D:/FGUI-work/fairygui-mcp
npm test
python tests/test_helper.py
python tests/test_publish_owner.py
python tests/test_recovery_helper.py
```

测试创建本地临时文件与 loopback mock 服务，不启动原版编辑器、不需要 GitHub 凭据。
Windows CI 执行相同测试。插件主文件由十个源码片段拼接生成：

```powershell
npm run build:plugin
```

`scripts/build-plugin.mjs --check` 检查生成文件是否与源码一致。
测试层次与发布范围见 [docs/REVIEW.md](docs/REVIEW.md)。

## 使用边界

- 一个 server 对应一个显式配置的工程；多个工程使用不同端口和配置。
- loopback、Bearer、Host/Origin 检查、session/request ID 和截止时间。
- 输入在换行前即有 64 KiB 内存上限；HTTP 响应、编辑队列和并发请求同样有界。
- 尚未调度的请求可取消；已经发送给编辑器的操作可能已产生作用，超时/断连不等于撤销。
- 原生写操作不自动重试；原生去重在内存中，不是持久事务。通用后端另有持久回执与未知结果规则。
- 不暴露任意执行脚本、任意 HTTP 目标或全局工程自动发现。
- 私有配置中含令牌；工程插件内也有相应配置。工程对外发布时同样需要排除它。
- 路径约束不是同用户恶意代码的系统沙箱，也不消除文件系统竞态。
- 原生运行可产生 FairyGUI 自身的用户配置/缓存；本仓库不是操作系统级隔离器。

## 回退

停用客户端 MCP 条目即停止新请求，不会自动关闭编辑器。
代码更新使用 Git 提交管理，回退到已验证提交后重新加载客户端。
更新插件前保存备份；退出对应编辑器后恢复旧插件，再启动。
原版编辑器二进制不在本仓库中，也不由本工具修补。

## 完整离线测试

运行 `npm test`，一次执行原生传输、Python helper、诊断、模式、预览、适配器及安装校验。Python 不在 PATH 时设置 `FGUI_TEST_PYTHON` 为绝对路径。测试不启动编辑器，不要求 Playwright；真实编辑器及浏览器全链路属于独立集成验收。

可选后端配置和升级/回退见 [可选后端安装](docs/OPTIONAL_BACKEND_SETUP.md)。本包不包含重构编辑器源码、SDK 或任何用户工程。

## 通用 source 输入契约

[静态输入契约](docs/contract.schema.json)覆盖全部9个通用 source 工具；实际可用项仍以显式配置及当前 `tools/list` 为准。`npm test` 会运行真实 stdio 目录一致性、配置组合及非法输入不派发检查，默认只检查，不改写文档。结构模式不替代运行时文本限制或后端语义验证，详见[契约范围与维护](docs/SOURCE_CONTRACT.md)。


## Explicit interrupted-receipt preservation

See [interrupted receipt maintenance](source_backend/INTERRUPTED_MAINTENANCE.md).
It is opt-in, digest-pinned, preserves unknown identities, and never replays a source write.