fgui-agent-bridge
Use it as an MCP/CLI bridge to a running FairyGUI Editor to inspect, modify, verify, and publish .fairy projects.
Connect/select a project, check heartbeat/ping, list packages/resources, open documents, and inspect active document/tree/text style/history.
Create components, buttons, and MovieClips; import images, fonts, and sounds; manage/remove MovieClips.
Insert/remove/select objects; edit supported properties, text styles, List/Group layouts, relations, gearDisplay, and controllers.
Read/create/update/remove Transitions and keyframe items; preview Transition/MovieClip animation.
Replace object resources; verify document state; undo/redo; save/discard documents; save all.
Read publish settings and publish active, specified, or all packages.
Requires a running FairyGUI Editor with an open project; supported scope covers native FairyGUI UI/transitions, not Spine, DragonBones, Loader3D, or SWF.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fgui-agent-bridge Create a new component called MainMenu in package UI and open it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FairyGUI Agent Bridge
通过 MCP 或 CLI,让 AI 编程助手读取和编辑正在运行的 FairyGUI 工程。
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 --frozen2. 安装工程插件
运行目录选择器,选择包含 .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 packagesstatus 读取已有心跳;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 \
--applySkill 是可选的;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-settingsinsert-loader 和 insert-list 创建当前文档根组件下的对象;默认不保存。Loader 接受空 URL 或工程内图片/MovieClip,List 条目引用组件。完整参数见 uv run fgui-agent insert-loader --help 和 uv run fgui-agent insert-list --help。
更多工具、资源管理、动效和发布用法见 使用参考。
保存与验证
文档编辑通常默认不保存。支持验证的写操作通过以下选项控制行为:
选项 | 行为 |
| 保存整个当前文档,包括已有的未保存修改 |
| 回读编辑器状态;保存后进一步比对磁盘 XML |
| 保存后关闭重开文档并再次比对,需要同时启用保存和验证 |
响应的 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 配置。
常见问题
问题 | 排查方式 |
| 确认 Editor 已打开目标工程、插件已加载;查看工程内 |
版本不匹配 | 更新 Bridge 并重新同步插件,然后重新打开工程 |
MCP 中没有工具 | 检查两个绝对路径、 |
导入找不到文件 | 使用本地绝对路径,并确认文件存在 |
写入超时后不确定是否执行 | 先查状态和当前文档,确认结果后再决定是否重试,避免重复创建 |
图集分析返回 | 图集约束不足,需在编辑器中确认或补全配置 |
提交 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、版本和文档,并用隔离工程验证写操作。
plugin/main.ts:Editor 插件源码;编译生成的
main.js随仓库提交。src/fairygui_agent:Python MCP 与 CLI。
tests:离线回归及 Editor 验收报告。
scripts/sync_to_project.py:插件和可选 Skill 的同步入口。
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/、本地环境、缓存或个人配置。
许可证
Available Tools
76 toolsfgui_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
Scored across 76 tools
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.
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.
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.
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
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
AlicenseNot gradedqualityAmaintenanceThis 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.304MIT- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityCmaintenanceAn 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.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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