FairyGUI Agent Bridge MCP
An MCP server and CLI with 76 tools let an agent edit an open FairyGUI Editor project: components, assets, animation, publishing
- 79 ★ on the repository
- Last commit
Broad access
Why this level
- The tools write and delete components, assets and packages in your FairyGUI project and publish the result
- The editor plugin accepts agent commands and changes project files on disk
Install
- Works in
Manual install
git clone https://github.com/Wilson520403/fgui-agent-bridge.gitThen uv sync --frozen and uv run python scripts/sync_to_project.py --choose-project --apply.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The tools write and delete components, assets and packages in your FairyGUI project and publish the result
- The editor plugin accepts agent commands and changes project files on disk
This is third-party code. Review the repository files before installing.
What it does
FairyGUI Agent Bridge connects an AI assistant to a running FairyGUI Editor. A Python service over MCP and CLI passes commands to an editor plugin installed in the project, and the agent creates components, lays out the interface, manages assets, edits animation and publishes packages. There are 76 tools in total, version 0.8.26. The agent creates buttons, texts, lists and loaders, inserts asset instances, changes position and text style, relations and controllers, updates list items in batches, imports images, fonts and sounds, finds unused and duplicate assets, replaces references across the project, edits Transitions and keyframes and builds MovieClips. The result is verified by reading XML after saving and by reopening. An optional skill on layering and component reuse ships with it.
Who it is for. Game UI developers on FairyGUI who build screens from mockups and want to hand routine work to an agent.
Good fit when
- A screen must be built from a concept image, PSD or mockup and the agent must find components and layers
- A list has dozens of items and texts, icons and order change in one pass
- You need to find unused and duplicate assets and replace references across the project
- You need to build transitions and keyframes or create a MovieClip
- Before handoff you want to publish the active package, a chosen one or all of them
Not a fit when
- You have no running FairyGUI Editor: the tools work only with an open project
- You work on Windows or another editor version: main verification was on 6.1.4 and macOS
- You need Spine, DragonBones, Loader3D or SWF: they are unsupported
- You need whole-group copying or group member editing: not available yet
Example request
Read the current component, add an image Loader in the top right corner and build a three item menu from the existing button componentMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
FGUI_PROJECT_PATHrequired- Absolute path to the FairyGUI project open in the editor
Limitations
It needs Python 3.10 or newer, `uv`, an installed FairyGUI Editor and a project with a `.fairy` file. The plugin is installed into each project by the `sync_to_project.py` script with `--apply`, without which the script only previews changes, and then the project must be reopened. Main verification ran on FairyGUI Editor 6.1.4 and macOS, and Windows and other versions are not fully tested. Grouping, copying and layer changes are limited to ordinary unlocked objects under the root component. An editor save check does not confirm behavior in Unity. Lanhu mockup mapping and visual diff are still planned.
How to disable. Delete the `plugins/agent-bridge/` folder from the FairyGUI project and remove the `fgui` entry from the MCP settings. The Bridge repository can be deleted as an ordinary folder.
FAQ
How do I install FairyGUI Agent Bridge?
Run `git clone https://github.com/Wilson520403/fgui-agent-bridge.git` and `uv sync --frozen`, then `uv run python scripts/sync_to_project.py --choose-project --apply` and reopen the FairyGUI project.
How do I connect an MCP client?
Add a stdio server `fgui` with the command `uv run --project <Bridge path> fgui-agent-mcp` and the `FGUI_PROJECT_PATH` variable. After reload call `fgui_status` and `fgui_ping`.
Can I do without MCP?
Yes, there is a CLI: `uv run fgui-agent --project <path> ping` along with `status`, `project` and `packages`. MCP and CLI work independently and the skill is optional.
How is `status` different from `ping`?
`status` reads the heartbeat already written by the editor and `ping` waits until the editor actually answers.
What does the skill do?
It sets rules for layering and reuse: check existing components first, build identical elements from a shared source component and express differences through instances or data.
Discussion
No questions or reviews yet.
Related
MCP serversA Cocos Creator 2.4.x plugin with a local server so an agent edits scenes, prefabs and assets and builds the project over MCP
A Cocos Creator extension with a built-in MCP server: the agent builds UI, edits scenes and takes editor screenshots
A plugin with skills for building TypeScript MCP servers and MCP apps: the agent scaffolds, edits, debugs and verifies them
A Unity plugin with an MCP server, skills and CLI: the agent drives scenes, assets, scripts and tests in the Unity Editor
A Godot addon and MCP server: the agent sees the scene tree, errors and screenshots of the running game and validates changes in the editor
An MCP server and plugin for Godot 4.4+: the agent edits scenes and scripts in the editor, runs the game and reads errors
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| FairyGUI Agent Bridge (this card) | no | not required | 79 | |
| Cocos Creator MCP Server | no | not required | 1,486 | an MCP plugin for Cocos Creator; here a bridge to the FairyGUI editor with 76 tools and a CLI |
| AnkleBreaker Unity MCP Plugin | no | not required | 257 | drives the Unity editor; here work with FairyGUI interface projects |
README in short
The README lists capabilities by work group, gives a quick start with an agent prompt and manual installation, shows the MCP JSON config and example requests. It also covers compatibility, what is unsupported and the development flow.
README badge
Original SKILL.md
--- name: fgui-agent-bridge description: 当通过 MCP、CLI 或源码使用和维护独立 FGUI Agent Bridge 仓库时使用；包括连接 FairyGUI Editor、选择工程、拼装界面时的组件分层与复用、读取/修改组件文档、保存/撤销、发布资源，以及新增或变更 Bridge Action、MCP 工具、CLI 参数、协议、安全边界、同步脚本和文档。 --- # FGUI Agent Bridge ## 目标与真源 本 Skill 面向独立 `fgui-agent-bridge` 仓库。该仓库是 Bridge、MCP、CLI 和 Skill 的唯一开发真源，业务工程中的插件与 Skill 仅是同步快照。 - FairyGUI 插件源码：`plugin/main.ts` - FairyGUI 运行文件：`plugin/main.js`；修改源码后必须重新编译并一起提交 - 插件包与最小宿主类型：`plugin/package.json`、`plugin/types/` - Python/MCP/CLI 真源：`src/fairygui_agent/` - 版本必须同步：`plugin/package.json`、`pyproject.toml`、`src/fairygui_agent/__init__.py`、`plugin/main.ts`、`plugin/main.js` - 工程文档真源：`README.md` - 当前能力参考：[references/current-capabilities.md](references/current-capabilities.md) - 业务工程同步入口：`scripts/sync_to_project.py` 若实现、README 和 Skill 不一致，先以代码和实际桥接响应核对，再在同一个改动中修正 README 与 Skill；不要凭旧摘要猜测 Action 或参数。 ## 何时使用 - 使用 `fgui_*` MCP 工具或 `fgui-agent` CLI 操作 FairyGUI 组件。 - 拼装界面、拆分子组件、选择公共组件或处理同样式的重复元素。 - 查看包、资源、活动文档、对象树、对象 ID/路径、属性或撤销状态。 - 修改组件属性、插入/删除已有 `ui://` 资源、替换 Image/Loader 资源引用、读取或修改文本样式、验证文档结构与持久化、保存、放弃、撤销或重做。 - 发布当前包、指定包或全部包，或检查发布设置。 - 检查 Bridge/插件版本一致性，或从源仓库拉取最新代码并同步到目标工程。 - 修改插件、MCP、CLI、版本、协议、白名单、队列语义、同步脚本或 README。 ## 使用工作流 ### 0. 检查更新与同步（按需） - 当用户要求“检查更新”、“拉取最新 Bridge 版本”，或 `fgui_status` 返回 `versionMatch: false` / 协议不兼容提示时： 1. 运行 `uv run python scripts/sync_to_project.py --pull --project PATH --skill-root PATH --apply`（或 `uv run fgui-agent update --pull --apply`）； 2. 若插件更新，提醒用户在 FairyGUI Editor 中重新打开工程生效。 ### 1. 连接与定位 1. 使用 `fgui_status` 查看当前会话是否已选择工程、编辑器是否在线、插件版本是否匹配以及心跳年龄；它不会唤醒编辑器。 2. 工程未选择时调用 `fgui_use_project`，参数可为 `.fairy` 文件、FairyGUI 工程目录或包含 `FairyGUI/FairyGUI.fairy` 的仓库目录。 3. 需要唤醒或验证编辑器时调用 `fgui_ping`。不要把“请求已写入队列”当作 FairyGUI 已完成。