Skip to main content
Glama
fgui-agent-bridge

fgui-agent-bridge

by Wilson520403

FairyGUI Agent Bridge

通过 MCP 或 CLI,让 AI 编程助手读取和编辑正在运行的 FairyGUI 工程。

CI License: MIT

Bridge 提供组件创建、界面布局、资源管理、动效编辑和发布工具。支持 MCP stdio 的客户端可以调用这些工具;无需 AI 客户端时,也可以直接使用命令行。

当前版本:0.8.26 · 76 个 MCP 工具 · 主要验证环境:FairyGUI Editor 6.1.4 / macOS

快速开始 · 使用示例 · 工具与行为参考 · 兼容性 · 参与开发

可以用它做什么

工作

支持的操作

搭建界面

创建组件、按钮、文本、List 和 Loader;插入资源实例;分组、复制和调整层级

调整布局

修改位置、尺寸、文字样式、List/Group 布局、Relation、Controller 和 gearDisplay

维护列表

读取已有 List 的默认组件与条目,整批更新文案、图标及顺序,新增、删除或清空条目

管理资源

导入图片、字体、声音;缩放大图;改名、移动、复制或删除包内资源

处理引用

查询引用与依赖、替换对象资源或全工程引用、查找未使用及重复资源

制作动效

创建和修改 Transition、编辑关键帧、生成 MovieClip、控制动画预览

验证与发布

保存后读取 XML、关闭重开验证;分析图集约束,发布活动包、指定包或全部包

例如,你可以让 Agent「先读取当前组件,在右上角添加一个图片 Loader,再用已有按钮组件创建三项菜单」。Agent 通过工具执行编辑,你可以在 FairyGUI Editor 中检查结果。

Related MCP server: Cocos Creator MCP Server

快速开始

环境要求

  • Python 3.10+ 和 uv。

  • 已安装 FairyGUI Editor,并有可打开的 .fairy 工程。

  • 使用 MCP 时,客户端需要支持 stdio,并能访问这台电脑上的 Bridge 和 FairyGUI 工程目录。

本仓库包含 Python MCP/CLI 服务和 Editor 插件。插件安装在每个 FairyGUI 工程中,Python 服务从本仓库运行。

让 AI 帮你安装

将以下提示词交给能够执行本地终端命令的编程助手:

请安装 FairyGUI Agent Bridge,并验证连接。
源仓库:https://github.com/Wilson520403/fgui-agent-bridge.git

先检查 Python、uv 和 FairyGUI Editor。克隆仓库并运行 uv sync --frozen,
再用 scripts/sync_to_project.py 将插件安装到目标 FairyGUI 工程。
目标工程:从当前工作区查找 .fairy 文件;存在多个或找不到时,请让我选择。
若客户端支持 MCP,请配置本仓库提供的 fgui-agent-mcp stdio 服务。
可选 Skill 安装到当前代码仓库的 .agents/skills/ 下。
完成后依次验证 status、ping、project、packages,报告实际连接结果。

手动安装

1. 下载并安装依赖

git clone https://github.com/Wilson520403/fgui-agent-bridge.git
cd fgui-agent-bridge
uv sync --frozen

2. 安装工程插件

运行目录选择器,选择包含 .fairy 文件的工程目录:

uv run python scripts/sync_to_project.py --choose-project --apply

也可以指定路径,适合脚本或没有图形界面的终端:

uv run python scripts/sync_to_project.py \
  --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT \
  --apply

插件安装到目标工程的 plugins/agent-bridge/。重新打开 FairyGUI 工程以加载插件,并将工程内生成的 .agent/ 加入该工程的 .gitignore。

同步脚本默认只预览变更,传 --apply 才写入。它不会删除目标目录里的其他文件。

3. 验证连接

保持 FairyGUI Editor 运行并打开目标工程。在 Bridge 仓库目录执行以下命令,将路径替换为你的工程路径:

uv run fgui-agent --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT status
uv run fgui-agent --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT ping
uv run fgui-agent --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT project
uv run fgui-agent --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT packages

status 读取已有心跳;ping 等待编辑器实际响应。检查版本是否匹配,并确认返回的工程路径和包列表符合预期。

4. 连接 MCP 客户端(可选)

在客户端中添加一个 stdio MCP 服务。下面是常见的 JSON 配置格式,具体配置位置由客户端决定;可复制 .mcp.example.json,将两个绝对路径替换为本机路径:

{
  "mcpServers": {
    "fgui": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/ABSOLUTE/PATH/TO/fgui-agent-bridge",
        "fgui-agent-mcp"
      ],
      "env": {
        "FGUI_PROJECT_PATH": "/ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT"
      }
    }
  }
}

第一个路径是 Bridge 仓库,第二个是 FairyGUI 工程。如果 GUI 客户端找不到 uv,请把 command 改为 uv 可执行文件的绝对路径。重新加载 MCP 服务后,先调用 fgui_status 和 fgui_ping 验证连接。

可选:安装 Agent Skill

fgui-agent-bridge Skill 提供组件分层与复用规范、操作流程、属性约定和验证边界。拼界面时先检查已有组件,同样式元素共用源组件,通过实例或数据表达差异。对于支持仓库 Skill 的 Agent,可将它同步到业务代码仓库:

uv run python scripts/sync_to_project.py \
  --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT \
  --skill-root /ABSOLUTE/PATH/TO/YOUR-CODE-REPOSITORY \
  --apply

Skill 是可选的;MCP 和 CLI 都可以独立使用。

使用示例

在 MCP 客户端中,可以直接描述任务:

使用蓝湖 mcp 读取 http:xxxx, 根据概念图完成界面的的拼装,注意组件识别与子组件之间的分层管理
根据PSD完成界面的的拼装,注意组件识别与子组件之间的分层管理
根据某文件夹里的效果图完成界面的的拼装,注意组件识别与子组件之间的分层管理

以下 CLI 示例在 Bridge 仓库目录执行。将工程路径和 ui:// URL 替换为实际值;资源 URL 可通过 items 包名 查询。创建对象前,先在 Editor 中打开目标组件。

# 创建图片 Loader,并验证保存与关闭重开后的结果
uv run fgui-agent --project /PATH/TO/PROJECT insert-loader \
  --name cover --url ui://PACKAGE_ID_IMAGE_ID \
  --x 40 --y 40 --width 180 --height 90 \
  --fill scale --align center --v-align middle \
  --save --external-reload

# 用已有组件作为 List 条目模板
uv run fgui-agent --project /PATH/TO/PROJECT insert-list \
  --name menu --x 40 --y 160 --width 240 --height 300 \
  --default-item ui://PACKAGE_ID_BUTTON_ID \
  --layout single_column --line-gap 12 \
  --items '[{"title":"开始"},{"title":"设置"},{"title":"退出"}]' \
  --save --external-reload

# 读取并整批更新已有 List 的条目
uv run fgui-agent --project /PATH/TO/PROJECT get-list-items --name menu
uv run fgui-agent --project /PATH/TO/PROJECT set-list-items --name menu \
  '[{"title":"设置"},{"title":"开始"}]' --save --external-reload

# 读取对象树和发布设置
uv run fgui-agent --project /PATH/TO/PROJECT tree
uv run fgui-agent --project /PATH/TO/PROJECT publish-settings

insert-loader 和 insert-list 创建当前文档根组件下的对象;默认不保存。Loader 接受空 URL 或工程内图片/MovieClip,List 条目引用组件。完整参数见 uv run fgui-agent insert-loader --help 和 uv run fgui-agent insert-list --help。

更多工具、资源管理、动效和发布用法见 使用参考。

保存与验证

文档编辑通常默认不保存。支持验证的写操作通过以下选项控制行为:

选项

行为

save=true / --save

保存整个当前文档,包括已有的未保存修改

verify=true(默认)

回读编辑器状态;保存后进一步比对磁盘 XML

external_reload=true / --external-reload

保存后关闭重开文档并再次比对,需要同时启用保存和验证

响应的 strength 表示实际验证范围:none 未证明持久化、disk 已比对磁盘、reload 已完成重载比对。不同工具的重载方式和验证字段有差异,详见 验证说明。

属性与部分动效修改支持 Agent 撤销;List/Loader 等结构创建及 List 条目整批更新不进入 Agent 撤销栈,未保存时可用 discard 放弃当前文档全部未保存修改。资源导入、包资源管理、分支等操作可能立即写盘,具体行为见各工具说明。

工作原理

graph LR
    Client["MCP 客户端 / CLI"] --> Bridge["Python Bridge"]
    Bridge -->|本地 JSON 队列| Plugin["FairyGUI 工程插件"]
    Plugin -->|Editor API| Editor["FairyGUI Editor"]

请求和响应通过工程内的 .agent/ 目录交换。编辑器插件调用原生 API,Bridge 按请求 ID 等待实际结果。运行时队列和日志无需提交到 Git。

更新

uv run python scripts/sync_to_project.py \
  --pull --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT --apply

如需同时更新 Skill,追加 --skill-root /PATH/TO/YOUR-CODE-REPOSITORY。更新插件后重新打开工程;Bridge 仓库位置和启动命令未变时,可继续使用原 MCP 配置。

常见问题

问题

排查方式

ping 超时

确认 Editor 已打开目标工程、插件已加载;查看工程内 .agent/bridge.log

版本不匹配

更新 Bridge 并重新同步插件,然后重新打开工程

MCP 中没有工具

检查两个绝对路径、uv 是否可启动,以及客户端是否重新加载服务

导入找不到文件

使用本地绝对路径,并确认文件存在

写入超时后不确定是否执行

先查状态和当前文档,确认结果后再决定是否重试,避免重复创建

图集分析返回 unknown

图集约束不足,需在编辑器中确认或补全配置

提交 Issue 时,请附上 Bridge 版本、Editor 版本、操作系统、复现步骤和相关错误;分享日志前请移除私人路径或其他敏感内容。

兼容性与范围

  • 主要开发和实测环境为 FairyGUI Editor 6.1.4 / macOS。Windows 和其他 Editor 版本尚未完整实测,欢迎反馈兼容问题。

  • 工具操作需要 Editor 运行并打开工程,不提供无界面的 FairyGUI 编辑服务。

  • 动效覆盖原生 Transition / MovieClip;Spine、DragonBones、Loader3D 和 SWF 不在支持范围。

  • 分组、复制、层级调整目前限于根组件下未锁定、未分组普通对象;完整组复制和组成员编辑尚未支持。

  • Editor 保存验证与 Unity 运行效果是两项独立检查;本仓库的编辑器验收报告不代表 Unity 或发布产物已验收。

  • Lanhu manifest 自动映射、Unity 自动联调和视觉差分仍在规划中。

参与开发

欢迎通过 Issues 报告问题或提交 Pull Request。新增接口请同步插件、MCP、CLI、版本和文档,并用隔离工程验证写操作。

uv sync --frozen
uv run python -m compileall -q src scripts
npx -y -p typescript@5.4.5 tsc -p plugin/tsconfig.json --pretty false
uv run python -m unittest discover -s tests -v
git diff --check

离线测试覆盖协议和模拟宿主行为,真实 Editor 验收需要另行运行。请勿提交 .agent/、本地环境、缓存或个人配置。

许可证

MIT

Available Tools

76 tools
fgui_add_keyframesA

在 Transition 时间轴上创建关键帧;一次调用可由 fgui_undo/redo 原子回退。

每项需要 targetId(空表示根组件)、type 与 frame;value 省略时由编辑器采样对象当前状态。 label 可写说明文字。同一轨道同一帧已存在会整体拒绝,不会留下半写入。 save=True 保存后默认比对磁盘 XML 中该 Transition 的条目数;external_reload=True(需 save=True)关闭重开再比对。

Inputs: name (required), keyframes (required), save, verify, +1 more. Returns: object

fgui_add_transition_itemB

向 Transition 添加一个类型化关键帧轨道项。

save=True 保存后默认比对磁盘 XML 中该 Transition 的条目数;external_reload=True(需 save=True)关闭重开再比对,响应 strength 为 reload / disk / none。

Inputs: item (required), name (required), save, verify, +1 more. Returns: object

fgui_adjust_depthA

将一个根组件下未锁定、未分组对象移到绝对层级 index(0.8.24+)。

index 从 0 开始,0 是最底层;不能越界或落入分组块。 返回完整前后顺序,不进 Agent 撤销栈;save 保存整个当前文档。 external_reload 需 save=True,关闭重开验证持久化顺序。

Inputs: index (required), save, verify, object_id, +3 more. Returns: object

fgui_analyze_atlas_fitA

按图集打包器的真实约束(PackSettings / 全局 AtlasSetting)判断每张图能否入图集。

只读,不改任何资源。返回每张图的 fit(fits / exceeds / unknown)、卡住它的约束 (maxWidth / maxHeight / squareSide)以及与旧的大图硬编码规则的差异统计 (disagreements)——发布时仍按旧规则标记 folderAtlas=alone,本工具只暴露差异, 供决定是否切换。

Inputs: package_name. Returns: object

fgui_clear_atlas_markersA

清除磁盘 package.xml 中错误的 atlas="alone" 标记(只处理按真实约束装得下的图片)。

默认只预览,execute=True 才写;可用 item_ids / item_names 限定目标。 这是带外修改:绕过编辑器对象模型,不可撤销、不进 Agent 撤销栈。执行前会保存 当前包并备份 package.xml,写后回读磁盘并 Dispose + 重开包。包内有未保存文档时 直接拒绝;有已保存的打开文档时,需要显式 close_open_documents=True 才会关闭它们。

只清除错误标记,不写任意图集归属;装不下或无法判定的 alone 标记会保留并在 held 里说明原因。

Inputs: package_name (required), execute, item_ids, item_names, +1 more. Returns: object

fgui_create_branchA

创建分支并为每个包建立分支根;走工程原生 API,立即落盘且不可撤销。

switch_to=True 创建后切换活跃分支;有未保存文档时需同时 save_open_documents=True。

Inputs: name (required), verify, switch_to, save_open_documents. Returns: object

fgui_create_buttonB

创建标准 FairyGUI Button 组件;状态图顺序为 up/down/over/selectedOver/disabled/selectedDisabled。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目;组件类资源不支持 external_reload,strength 上限为 disk。

Inputs: button_name (required), package_name (required), mode, save, +15 more. Returns: object

fgui_create_componentB

在指定包中新建组件文档;默认打开但不保存,重名时默认拒绝。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目;组件类资源没有可靠的 asset 重载手段,external_reload 不可用,strength 上限为 disk。

Inputs: package_name (required), component_name (required), save, width, +9 more. Returns: object

fgui_create_groupA

将至少两个根组件下未锁定、未分组对象组成组(0.8.24+)。

targets 每项仅含 id/name/path 一个定位键。原生操作把成员移到显示列表末尾。 返回成员归属和前后顺序;不进 Agent 撤销栈。save 保存整个当前文档; external_reload 需 save=True,关闭重开验证顺序、名称和成员归属。

Inputs: targets (required), name, save, verify, +1 more. Returns: object

fgui_create_movieclipB

用有序绝对图片路径创建或替换 MovieClip;图片序列由 FairyGUI 原生动画资源处理。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目和资源文件;external_reload=True(需 save=True)卸载并重新加载 asset 再比对,响应 strength 为 reload / disk / none。

Inputs: frame_paths (required), package_name (required), movieclip_name (required), fps, +12 more. Returns: object

fgui_delete_package_itemA

删除包资源(组件/图片/字体/声音/MovieClip/目录);不可逆操作,必须显式 force=True。

编辑器原生 DeleteItem 不会拦引用:被引用的资源照样删,引用方会留下悬空 src。 默认检测到引用就拒绝并列出引用位置;确认要删就传 allow_dangling_references=True,响应会回报哪些引用会变悬空。 目标组件的文档正开着时默认拒绝;传 close_open_documents=True 让本工具关闭它(未保存改动一律拒绝)。 删除会连带删掉磁盘文件,不进 Agent 撤销栈。

Inputs: url, save, force, verify, +5 more. Returns: object

fgui_discard_documentA

放弃当前文档全部未保存修改并重新加载磁盘版本。

Inputs: no named parameters. Returns: object

fgui_duplicate_objectA

原生复制一个根组件下未锁定、未分组的普通对象(0.8.24+)。

保留序列化属性、资源引用、Relation/Gear/扩展覆盖,生成新 ID,追加到末尾。 dx/dy 是相对源坐标偏移,默认原位;几何向零截断并返回 rounded。 不支持组或组成员,不进 Agent 撤销栈。save 保存整个当前文档; external_reload 需 save=True,并验证副本序列化内容和显示列表。

Inputs: dx, dy, name, save, +5 more. Returns: object

fgui_duplicate_package_itemA

复制包资源;副本是新 id 的新资源,磁盘文件一并复制,原资源不受影响。

new_name 省略时用 "<原名>_copy"。conflict_policy 取 error(同名即拒绝)或 auto_rename(自动加后缀)。

Inputs: url, save, verify, new_name, +4 more. Returns: object

fgui_duplicate_transitionA

复制一个 Transition(含全部关键帧);可由 fgui_undo 回退。

6.1.4 的 DuplicateTransition 运行时不接受新名称参数,Bridge 会复制后再经文档模型改名; structureNormalized=true 表示副本结构经编辑器归一化,与源不完全一致。省略 new_name 时沿用编辑器自动命名。 save=True 保存后默认比对磁盘 XML 中副本的 节点;external_reload=True(需 save=True)关闭重开再比对。

Inputs: name (required), save, verify, new_name, +1 more. Returns: object

fgui_find_duplicateA

找出文件内容完全相同的资源,按 MD5 分组(只读,0.8.19+)。

适合清理重复导入的图片、字体和音效;组件 XML 也参与比较。每组返回文件大小、 条目和可回收字节数,按浪费体积从大到小排序。同名不同内容不算重复。

packages / types / include_branches 同 fgui_find_unused;max_groups 和 max_items_per_group 分别限制组数与组内明细条数,计数字段不受截断影响。

Inputs: types, packages, max_groups, include_branches, +1 more. Returns: object

fgui_find_unusedA

找出工程内没有任何引用位置的资源(只读,0.8.19+)。

返回每个未引用资源的包、路径、URL、文件大小,图片还附带尺寸。判断口径是 「当前工程内零引用」:导出资源可能被运行时按 URL 使用,默认仍会列出并标记 exported,删改前请确认;skip_exported=True 可排除它们。

packages 传包名或包 ID,省略时扫描全工程;types 可按 image / font / sound / movieclip / component 过滤;max_items 限制返回明细条数,unusedCount 仍是真实总数。

Inputs: types, packages, max_items, skip_exported, +1 more. Returns: object

fgui_get_active_documentA

读取当前活动文档、修改状态和选择数量。

Inputs: no named parameters. Returns: object

fgui_get_historyB

读取 Agent 属性事务栈和 FairyGUI 原生撤销状态。

Inputs: no named parameters. Returns: object

fgui_get_list_itemsB

只读当前根组件下的 List 条目(0.8.26+),按原顺序返回完整数组。

items 的空 url 表示继承 defaultItem,effectiveUrls 返回实际组件 URL。 items 可直接用于 set_list_items;unsupportedItemData 非空时整批更新会拒绝。

Inputs: object_id, object_name, object_path. Returns: object

fgui_get_movieclipC

读取 MovieClip 的帧、FPS、Swing 和 RepeatDelay 设置。

Inputs: url, item_name, item_path, package_name. Returns: object

fgui_get_projectC

读取当前 FairyGUI 工程信息。

Inputs: no named parameters. Returns: object

fgui_get_publish_settingsA

读取工程发布目录、格式、图集、代码生成和包级覆盖设置。发布前应先调用。

Inputs: package_name. Returns: object

fgui_get_text_styleC

读取 TextField/RichText 的统一文本样式。

Inputs: object_id, object_name, object_path. Returns: object

fgui_get_transitionA

按名称读取当前组件的一个 Transition。

Inputs: name (required). Returns: object

fgui_get_treeA

读取当前组件对象树;修改前应先取得稳定的对象 ID 或路径。

branch 指定时要求当前文档属于该分支;只读读取不要求该分支处于活跃状态。

Inputs: branch, max_depth. Returns: object

fgui_import_fontB

从绝对本地路径导入字体;这是磁盘写入操作,支持拒绝、自动改名或替换同名字体。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目和资源文件;external_reload=True(需 save=True)卸载并重新加载 asset 再比对,响应 strength 为 reload / disk / none。

Inputs: source_path (required), package_name (required), save, branch, +8 more. Returns: object

fgui_import_imageB

从绝对本地路径导入图片;这是磁盘写入操作,支持拒绝、自动改名或替换同名图片。

max_size 是长边上限(像素,1~32768):源图长边超过它就先等比缩放再入库,响应里的 scaled 回报缩放前后尺寸与缩放比,atlasPrecheck 给出按真实图集约束的前置判定(fit 为 fits/exceeds/unknown,unknown 不等于放行)。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目和资源文件;external_reload=True(需 save=True)卸载并重新加载 asset 再比对,响应 strength 为 reload / disk / none。

Inputs: source_path (required), package_name (required), save, branch, +9 more. Returns: object

fgui_import_soundA

从绝对本地路径导入声音资源;支持替换同名声音,属于磁盘写入。

save=True 保存包与工程后默认比对 package.xml(分支写入比对 package_branch.xml)条目和资源文件;external_reload=True(需 save=True)卸载并重新加载 asset 再比对,响应 strength 为 reload / disk / none。

Inputs: source_path (required), package_name (required), save, branch, +8 more. Returns: object

fgui_insert_listA

在当前文档根组件下创建 List,支持布局、默认条目组件和初始条目(0.8.25+)。

default_item 与条目 url 必须引用组件;每项省略 url 时使用 default_item。 items 最多 1000 项,可写 url/title/icon/name/selectedTitle/selectedIcon,图标须引用图片。 x/y/width/height 向零截断,尺寸须大于 0;间距须为整数。 支持保存、XML 条目回读与关闭重开验证。不进 Agent 撤销栈,未保存可 discard。 save 保存整个文档;external_reload 要求 save=true 且 verify=true。

Inputs: x, y, name, save, +14 more. Returns: object

fgui_insert_loaderA

在当前文档根组件下创建 Loader(0.8.25+)。

url 可空,或引用工程内图片/MovieClip;不接受外部 URL。 固定 autoSize=false,x/y/width/height 向零截断并回报 rounded。 默认不保存;不进 Agent 撤销栈,未保存可 discard。save 保存整个文档。 external_reload 要求 save=true 且 verify=true。

Inputs: x, y, url, fill, +9 more. Returns: object

fgui_insert_objectA

插入已有 ui:// 资源;结构操作不能由 Agent 属性事务栈撤销。

save=True 保存后默认比对磁盘 XML;external_reload=True 会在保存后关闭并重新打开文档再比对,需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: url (required), x, y, name, +4 more. Returns: object

fgui_insert_textA

在当前文档根组件下创建文本对象(0.8.20+);结构操作不能由 Agent 属性事务栈撤销。

文本是 FGUI 的裸节点、不是包资源,所以只能用 insert_text 造,不能用 insert_object。 style 支持:font / fontSize / color / align / vAlign / autoSize / letterSpacing / lineGap / width / height / bold / italic / underline / strokeSize / strokeColor / shadowX / shadowY / shadowColor。 其中 width/height 会自动把 autoSize 切成 none(否则编辑器在保存时按文字自然尺寸重算,写进去的尺寸会被改写)。 投影偏移(shadowX/shadowY)会自动打开投影开关:偏移不伴随开关时编辑器不会落盘。

save=True 保存后默认比对磁盘 XML;external_reload=True 会在保存后关闭并重新打开文档再比对,需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: x, y, name, save, +4 more. Returns: object

fgui_list_branchesA

列出工程分支及活跃分支;可附带每个包的分支根与资源。

refresh=True 先从磁盘重扫。分支资源目录为 assets_/,活跃分支不会让编辑器自动改道保存。

Inputs: refresh, include_items, include_packages. Returns: object

fgui_list_controllersB

列出当前文档根组件的全部 Controller(0.8.8+)。

Inputs: no named parameters. Returns: object

fgui_list_itemsA

列出指定包中的资源,可按 FairyGUI 资源类型过滤。

省略 branch 时跟随当前活跃分支,branch="" 表示主干。返回的分支视角中, 分支资源覆盖同名主干资源;只读操作可以读取非活跃分支,不需要先切换。

Inputs: package_name (required), branch, item_type. Returns: result

fgui_list_packagesA

列出当前 FairyGUI 工程中的全部包。

Inputs: no named parameters. Returns: result

fgui_list_transitionsA

读取当前组件的全部 Transition 及类型化关键帧。

Inputs: no named parameters. Returns: result

fgui_move_package_itemA

把包资源移动到包内另一个目录;磁盘文件同步移动,不可撤销。

folder_path 是包内目录(如 "/ui/")。编辑器原生 MoveItem 要求目标目录已存在, 否则会抛原生异常;本工具默认按 create_folders=True 先建目录再移动,并在响应里回报是否新建了目录。 移动不会更新引用方文档的 fileName 属性(id 不变,运行时按 id 解析不受影响),响应里的 staleFileNameSlots 会列出这些位置。

Inputs: folder_path (required), url, save, verify, +5 more. Returns: object

fgui_open_documentA

按包名和资源名打开 FairyGUI 组件文档。

省略 branch 时跟随当前活跃分支,branch="" 表示主干。只读打开不要求该分支处于活跃状态, 但后续写该文档前仍需切换。

Inputs: item_name (required), package_name (required), branch. Returns: object

fgui_pingA

唤醒 FairyGUI Editor 并验证桥接协议、版本和能力。

Inputs: no named parameters. Returns: object

fgui_preview_animationA

在 Editor 中播放、暂停、停止、跳帧或查询预览状态;预览不会保存到 FairyGUI 资源。

Inputs: kind (required), operation (required), name, delay, +8 more. Returns: object

fgui_publishA

按工程发布设置导出 FairyGUI 包。默认发布当前文档所属包并先保存;可选择指定包或全部包。

Inputs: scope, branch, package_names, timeout_seconds, +2 more. Returns: object

fgui_query_dependenciesA

查询目标资源依赖了哪些资源(只读,0.8.10+)。

走编辑器原生 DependencyQuery。seek_level 取 selection / samePackageButNotExported / samePackage(默认)/ all,决定依赖搜索范围;响应会回报实际生效的 seekLevel。

只读:不会保存、不会标记文档修改。max_items、skip_package_open 同 fgui_query_references。

Inputs: resource_url (required), max_items, seek_level, skip_package_open. Returns: object

fgui_query_referencesA

查询全工程里哪些位置引用了目标资源(只读,0.8.10+)。

走编辑器原生 DependencyQuery,返回的每条引用精确到「哪个包的哪个资源的哪个属性槽」: packageId / itemId / propKey / arrayIndex / valueType。改资源引用前先跑它,能直接回答 「换掉这张图会影响哪些节点」,也可作为 replace_object_resource 的影响面预览。

只读:不会保存、不会标记文档修改。max_items 限制返回条数(默认 200,上限 2000), 截断时 truncated=true 且 totalCount 仍为真实总数,不会静默丢弃。 skip_package_open=True 跳过「预先打开未打开的包」,更快但可能少算未打开包里的引用; 默认会先打开,代价记录在响应的 packages 字段里。

Inputs: resource_url (required), max_items, skip_package_open. Returns: object

fgui_redoA

优先重做 Agent 属性事务;事务栈为空时回退到 FairyGUI 原生重做。

Inputs: no named parameters. Returns: object

fgui_remove_movieclipB

删除 MovieClip 包资源;这是不可逆资源操作,必须显式 force=True。

save=True 保存包与工程后默认比对 package.xml 确认条目已移除;删除没有诚实的重载基元,external_reload 不可用,strength 上限为 disk。

Inputs: url, save, force, verify, +3 more. Returns: object

fgui_remove_objectA

删除非根对象;需要可靠回退时使用 fgui_discard_document。

删除按「缺失性验证」处理:save=True 保存后确认磁盘 XML 不再包含该节点;external_reload=True 关闭重开后确认目标仍不存在,需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: save, verify, object_id, object_name, +2 more. Returns: object

fgui_remove_transitionA

删除当前组件中的一个 Transition;可由 fgui_undo 恢复。

save=True 保存后默认确认磁盘 XML 不再包含该 Transition;external_reload=True(需 save=True)关闭重开后确认仍不存在,响应 strength 为 reload / disk / none。

Inputs: name (required), save, verify, external_reload. Returns: object

fgui_remove_transition_itemA

删除 Transition 指定索引的关键帧项;可用 fgui_undo 恢复。

save=True 保存后默认比对磁盘 XML 中该 Transition 的条目数;external_reload=True(需 save=True)关闭重开再比对,响应 strength 为 reload / disk / none。

Inputs: name (required), item_index (required), save, verify, +1 more. Returns: object

fgui_rename_package_itemA

重命名包资源;磁盘文件同步改名,不可撤销。

new_name 不带扩展名(编辑器按资源类型补)。同名资源会被拒绝。 改名不会更新引用方文档的 fileName 属性(id 不变,运行时按 id 解析不受影响), 响应里的 staleFileNameSlots 会列出这些位置,需要时让那些文档经编辑器重新保存一次即可补齐。

Inputs: new_name (required), url, save, verify, +4 more. Returns: object

fgui_replace_object_resourceA

通过 Editor API 替换 Image/Loader 图片引用或组件实例的源组件(0.8.21+);保存后默认比对磁盘 XML。Button 状态暂不支持。

组件实例换源组件走编辑器原生命令 Document.ReplaceSelection:id/name/xy/relation/显式 size 全部保留, 没有显式 size 时尺寸跟随新源组件(FGUI 语义,preserve_size 对组件实例不适用)。 expected_type 省略时按目标对象推导(image/loader→image,组件实例→component),显式传入则作为断言。

external_reload=True 会在保存后关闭并重新打开文档再比对,是唯一能证明「重新载入时值不丢」的验证;需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: resource_url (required), save, state, verify, +5 more. Returns: object

fgui_replace_referencesA

把全工程对某个资源的所有引用替换成另一个资源(0.8.11+)。

先预览、再执行,这是硬要求而不是建议:编辑器原生 ReplaceReferences 直接改包 XML, 立即落盘、不进 Agent 撤销栈、没有 save 兜底,也没有 external_reload 可做—— 响应里 undoable=false 就是这个意思。默认 execute=false 只出预览, 确认 totalCount 与 references 明细后再显式传 execute=True。

与 fgui_replace_object_resource 分工:那个改「某一个对象的某一个属性槽」, 走文档模型、可撤销、有 save/verify/external_reload 梯子;这个改「全工程引用图」, 走原生批处理、不可撤销。两者不要互相替代。

执行后按引用图回读验证(源资源残留引用必须为 0),verification.scope 会标明 "reference-graph"——这是引用图口径,不宣称属性级一致:原生批量替换不会同步 image 元素的 fileName,落盘后该属性短暂滞后,warnings 字段会显式报出槽位数量, 这些节点下次经编辑器保存时自动补齐。

max_items、skip_package_open 同 fgui_query_references。

Inputs: resource_url (required), new_resource_url (required), execute, max_items, +1 more. Returns: object

fgui_save_allA

显式保存所有 FairyGUI 文档、已打开包和工程,并清空 Agent 属性事务栈。

Inputs: no named parameters. Returns: object

fgui_save_documentA

显式保存当前 FairyGUI 文档,并清空 Agent 属性事务栈。

Inputs: no named parameters. Returns: object

fgui_select_objectB

通过对象 ID、对象树路径或唯一名称选择一个对象。

Inputs: object_id, object_name, object_path. Returns: object

fgui_set_controllerA

创建、修改或删除当前组件的 Controller(0.8.8+)。

create=True 创建不存在的控制器;remove=True 删除;pages 整体替换页面集 (会重新分配页面 id,gearDisplay 中的页面引用需重新核对);add_pages 追加; selected_index/selected_page 设置选中页。

external_reload=True 需 save=True,关闭重开文档后重新比对;strength 标明验证强度。

Inputs: name (required), save, pages, create, +9 more. Returns: object

fgui_set_gear_displayA

设置对象的 gearDisplay 联动(0.8.8+):指定控制器与可见页面。

controller=None 或空字符串清除联动;pages 为页面 id 或名称列表(也接受 "0,1" 逗号串), 省略 pages 保持现有页面不变。

external_reload=True 需 save=True,关闭重开文档后重新比对;strength 标明验证强度。

Inputs: controller (required), save, pages, verify, +4 more. Returns: object

fgui_set_group_layoutA

修改 Group 对象的布局属性(0.8.8+)。fields 支持:

advanced、layout(horizontal/vertical 或 hz/vt)、lineGap、columnGap、 excludeInvisibles、mainGridMinSize、mainGridIndex、autoSizeDisabled、collapsed。 layout/lineGap/columnGap/excludeInvisibles 仅对 advanced=true 的高级组有效。

external_reload=True 需 save=True,关闭重开文档后重新比对;strength 标明验证强度。

Inputs: fields (required), save, verify, object_id, +3 more. Returns: object

fgui_set_instance_overrideA

写组件实例的扩展级 override(同一个组件、不同实例不同文案/样式)。

只支持扩展级覆盖,这是编辑器与 FGUI 运行时共同支持的那一层: 源组件是 Button 扩展时可写 title(text 是别名)、icon、selectedTitle、selectedIcon、 titleColor(#RRGGBB 六位,alpha 会被编辑器丢掉)、titleFontSize;Label 扩展可写 title、icon、titleColor、titleFontSize。落盘形态是实例节点里的扩展子节点 <component ...><Button title="..."/></component>,运行时按同一组字段消费。

边界(真机 6.1.4 实测):编辑器不支持逐子对象覆盖——改实例内部子对象只改到内存, 磁盘不落盘;这类需求请改用 insert_text 直接建对象,或把样式固化成组件类型。 源组件没有扩展时也会被拒绝。

external_reload=True 会在保存后关闭并重新打开文档再比对,是唯一能证明「重新载入时值不丢」 的验证;需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: properties (required), save, verify, object_id, +3 more. Returns: object

fgui_set_keyframeA

修改一个已有关键帧;可用 item_index,或 target_id + track_type + frame 定位。

按 target_id/type/frame 还能定位 get_transition 隐藏的 Tween 合成端点(此时 itemIndex=null、syntheticEndpoint=true)。changes 支持 frame / label / tween / ease / repeat / yoyo / value / endValue。tween=true 只能用于已处于 Tween 关系中的关键帧 (Tween 起点,或插入已有 Tween 后形成的端点);普通关键帧之间建立 Tween 请用 fgui_upsert_transition。endValue 写入 Tween 端点;tween=false 不能同时给 endValue。 save=True 保存后默认比对磁盘 XML;external_reload=True(需 save=True)关闭重开再比对。

Inputs: name (required), changes (required), save, frame, +5 more. Returns: object

fgui_set_list_itemsA

整批替换已有 List 的条目(0.8.26+);数组顺序即条目顺序,[] 清空。

最多 1000 项,支持 url/title/icon/name/selectedTitle/selectedIcon;省略的字段清空。 省略 default_item 保留默认组件,空串清除它。条目的空/省略 url 继承最终默认组件。 先校验全部输入;限当前根组件下未锁定的 List,须退出时间轴与组内编辑。 不进 Agent 撤销栈;默认不保存,未保存可 discard,save 保存整个文档。 原生应用失败尝试恢复原条目并回报 rolledBack;保存/验证失败不自动回滚。 external_reload 要求 save=True 且 verify=True。

Inputs: items (required), save, verify, object_id, +4 more. Returns: object

fgui_set_list_layoutA

修改 List 对象的布局与滚动属性(0.8.8+)。fields 支持:

layout(single_column/single_row/flow_horizontal/flow_vertical/pagination)、 selectionMode(none/single/multiple/multiple_singleclick)、lineGap、columnGap、 defaultItem(ui:// 组件资源)、autoItemSize、align/vAlign(含 none)、 selectionController(控制器名)、foldInvisibleItems、clearOnPublish、 scrollItemToViewOnClick、overflow(visible/hidden/scroll)、margin("l,t,r,b")。

external_reload=True 需 save=True,关闭重开文档后重新比对;strength 标明验证强度。

Inputs: fields (required), save, verify, object_id, +3 more. Returns: object

fgui_set_propertyB

修改白名单属性;该操作进入 Agent 属性 undo/redo 事务栈。

save=True 保存后默认比对磁盘 XML;external_reload=True 会在保存后关闭并重新打开文档再比对,需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: value (required), property_name (required), save, verify, +4 more. Returns: object

fgui_set_publish_settingsA

按包写入发布与图集设置:输出路径、代码生成、图集约束(PackSettings)与排除列表。

走对象模型(包级设置没有 DocElement 入口),响应里 writePath 会显式声明 object-model:它不进组件文档的撤销栈,也不走组件的持久化验证梯子。

只写你确实要改的字段——未提供的字段保持编辑器当前值,不会被重置。 atlasList 是全量替换语义:传进来的数组就是落盘的最终列表,不做增量合并; 省略该字段则完全不碰图集设置。packSettings 里未提供的键取编辑器新建对象的默认值。

external_reload 是保存后关闭重开包的回读,属于同进程重开,不等于跨重启持久化。

Inputs: settings (required), package_name (required), save, verify, +1 more. Returns: object

fgui_set_relationB

整体替换对象的 Relation 绑定(0.8.8+)。relations 每项为:

{"target": {"id"/"path"/"name"} 或 null(null/缺省 = 父组件), "sidePair": "left-left,right-right" 或 "pairs": [{"source": "right", "target": "right", "percent": false}]}

sidePair 方向名:left/center/right/leftext/rightext/width(水平), top/middle/bottom/topext/bottomext/height(垂直);percent 追加 % 后缀。

external_reload=True 需 save=True,关闭重开文档后重新比对;strength 标明验证强度。

Inputs: relations (required), save, verify, object_id, +3 more. Returns: object

fgui_set_text_styleB

设置 TextField/RichText 的统一文本样式。

external_reload=True 会在保存后关闭并重新打开文档再比对,是唯一能证明「重新载入时值不丢」的验证;需要 save=True。响应中的 strength 字段标明验证强度:reload / disk / none。

Inputs: style (required), save, verify, object_id, +3 more. Returns: object

fgui_statusA

读取本地 FairyGUI 工程选择和桥接心跳,不主动唤醒编辑器。

Inputs: no named parameters. Returns: object

fgui_switch_branchA

切换活跃分支;name 传空字符串切回主干。

只改变编辑器分支上下文。真机 6.1.4 上文档保存与资源创建不会自动改道,Bridge 的写操作按 branch 参数或活跃分支显式寻址。

Inputs: name (required), save_open_documents. Returns: object

fgui_undoA

优先撤销 Agent 属性事务;事务栈为空时回退到 FairyGUI 原生撤销。

Inputs: no named parameters. Returns: object

fgui_update_movieclipB

更新已有 MovieClip;传入 frame_paths 时使用新的有序图片序列替换动画帧。

save=True 保存包与工程后默认比对 package.xml 条目和资源文件;external_reload=True(需 save=True)卸载并重新加载 asset 再比对,响应 strength 为 reload / disk / none。

Inputs: fps, url, save, speed, +11 more. Returns: object

fgui_update_transition_itemB

替换 Transition 指定索引的关键帧项;可用 fgui_undo/redo 回退。

save=True 保存后默认比对磁盘 XML 中该 Transition 的条目数;external_reload=True(需 save=True)关闭重开再比对,响应 strength 为 reload / disk / none。

Inputs: item (required), name (required), item_index (required), save, +2 more. Returns: object

fgui_upsert_transitionA

声明式创建或完整替换一个 Transition;一次调用可由 fgui_undo/redo 原子回退。

save=True 保存后默认比对磁盘 XML 中的 节点;external_reload=True(需 save=True)关闭并重新打开文档再比对,响应 strength 为 reload / disk / none。

Inputs: transition (required), save, verify, external_reload. Returns: object

fgui_use_projectA

为当前 MCP 会话选择 .fairy 文件、FairyGUI 工程目录或仓库目录。

Inputs: project_path (required). Returns: object

fgui_verify_documentA

只读验证 target 的 expected 属性;默认比对磁盘 XML,不保存。无 expected 时仅返回快照。

expected 为纯属性对象时比对单个 target(必须提供 object_id/object_path/object_name)。expected 含 children 时执行对象树比对,可省略 target(默认根组件):每个节点用 id/name/type 断言或定位,children 为子节点 spec 数组;childrenMode 默认 "exact"(按位置全等,数量必须一致),"subset" 表示每个 spec 按 id/name/index 定位一个子节点、允许多余节点。

external_reload=True 会关闭并重新打开当前文档再比对——这是只读操作仍能达到的最强持久化证明。本命令不会保存,因此文档存在未保存改动时会拒绝执行。

Inputs: expected, read_xml, max_depth, object_id, +3 more. Returns: object

fgui_verify_transitionA

只读校验当前组件的 Transition:目标对象、关键帧值、嵌套引用与 XY 位置范围。

不修改文档、不保存。省略 name 时校验全部 Transition。summary.valid 只统计 error; position_outside_canvas 是 warning——滑入/滑出动画的越界坐标本身是合法的。

Inputs: name, check_bounds. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 76 tools

    Disambiguation3/5

    The tool set has clear domain groupings, but several near-neighbor tools create real misselection risk: insert_object vs insert_text/insert_loader/insert_list, add_keyframes vs add_transition_item vs set_keyframe vs update_transition_item, and delete_package_item vs remove_object vs remove_transition vs remove_movieclip. The descriptions often explain the boundaries, but an agent must read carefully to avoid choosing the wrong operation.

    Naming Consistency5/5

    Every tool uses the fgui_ prefix and snake_case, with predictable verb_noun forms such as fgui_create_component, fgui_get_tree, fgui_set_property, and fgui_verify_document. The few diagnostic names like fgui_ping and fgui_status are minor exceptions within an otherwise highly consistent convention.

    Tool Count1/5

    With 76 tools, the surface is far beyond the typical 3-15 range and is heavily fragmented into specialized variants for resources, transitions, verification, branches, and object creation. Even for a feature-rich FairyGUI editor bridge, this volume creates excessive selection and maintenance overhead for an agent.

    Completeness4/5

    The surface is very broad: project selection, branches, packages/items, documents, object trees, properties, transitions, movie clips, lists/groups, publishing, references, and verification are all represented. There are some notable gaps, such as package-level create/delete and branch deletion, but most core workflows have coverage.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      This MCP server integrates AI assistants with Unity Editor, allowing them to create scenes, generate scripts, simulate input, and automate workflows using 91 built-in tools.
      304
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for Cocos Creator 3.8+ that enables AI assistants to interact with the editor via 50+ tools for scene, node, component, prefab, asset, and project management.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that translates human GUI actions into machine-executable commands, enabling AI agents to control real software applications like Zoom, Excel, and WeChat via natural language or API calls.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables AI agents to control and interact with Godot 4 editor, allowing scene manipulation, file editing, and project inspection through natural language.
      MIT