kaohum/fairygui-mcp

---

概述

MCP for FairyGUI 是一个基于 Model Context Protocol (MCP) 的工具集，让 AI 编程助手（如 Claude Code、Cursor 等）能够直接与 FairyGUI 编辑器交互。

AI 助手可以浏览 UI 资源、打开和预览组件、截图验证、切换控制器状态、发布 UI 包——全程无需手动操作编辑器。

工作原理

┌───────────────┐   MCP (stdio)   ┌─────────────────┐   文件轮询    ┌─────────────────┐
│   AI 助手      │◄──────────────► │  Python MCP 服务 │◄───────────►│  FairyGUI 编辑器 │
│ (Claude Code) │                 │   (fastmcp)     │    JSON     │   (Lua 插件)     │
└───────────────┘                 └─────────────────┘             └─────────────────┘

通信流程：

1. AI 助手调用 MCP 工具 → Python MCP 服务接收请求
2. MCP 服务将 JSON 命令写入 bridge/commands/ 目录
3. FairyGUI 编辑器中的 Lua 插件每 100ms 轮询命令文件
4. 插件在编辑器内执行命令，将结果写入 bridge/results/
5. MCP 服务读取结果，返回给 AI 助手

功能特性

包与资源管理

组件分析

编辑器交互

预览与截图

控制器操作

发布

插件管理

系统要求

• Python 3.10+
• FairyGUI 编辑器（Windows 版本）
• MCP 客户端（Claude Code / Cursor / 其他支持 MCP 的工具）
• Windows 操作系统（窗口截图功能依赖 Win32 API）

快速开始

1. 安装 Python MCP 服务

cd fairyGUI-MCP
pip install -e .

Windows 用户也可以双击 install.bat。

2. 安装 FairyGUI 编辑器插件

将 plugin/MCPBridge/ 目录复制到你的 FairyGUI 项目的 plugins/ 目录下：

your-fairygui-project/
└── plugins/
    └── MCPBridge/          ← 复制整个目录
        ├── package.json
        ├── main.lua
        ├── src/
        │   └── command_handler.lua
        └── bridge/
            ├── commands/
            ├── results/
            └── screenshots/

打开 FairyGUI 编辑器，控制台出现 [MCPBridge] 插件已启动 即表示成功。

3. 配置 MCP 客户端

Claude Code (~/.claude/settings.json 或项目 .mcp.json)：

{
  "mcpServers": {
    "fairygui-tools": {
      "command": "python",
      "args": ["-m", "mcp_fairygui.server"],
      "cwd": "/path/to/fairyGUI-MCP",
      "env": {
        "UI_PROJECT_PATH": "/path/to/your/fairygui-project"
      }
    }
  }
}

Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "fairygui-tools": {
      "command": "python",
      "args": ["-m", "mcp_fairygui.server"],
      "cwd": "/path/to/fairyGUI-MCP",
      "env": {
        "UI_PROJECT_PATH": "/path/to/your/fairygui-project"
      }
    }
  }
}

UI_PROJECT_PATH 是你的 FairyGUI 工程根目录（包含 assets/ 和 package.xml 的目录）。

4. 验证连接

在 AI 助手中调用：

fg_editor_status

应返回：

编辑器: 运行中
通信目录: 正常
插件通信: 正常
已加载 X 个 UI 包

环境变量

项目结构

fairyGUI-MCP/
├── README.md
├── LICENSE
├── pyproject.toml                      # Python 包配置
├── install.bat                         # Windows 安装脚本
├── claude_settings_example.json        # MCP 配置示例
│
├── src/mcp_fairygui/                   # Python MCP 服务
│   ├── server.py                       #   服务入口（路径自动检测）
│   ├── tools/
│   │   ├── package_tools.py            #   包与资源查询
│   │   ├── component_tools.py          #   组件分析（读取/解析/验证）
│   │   ├── editor_tools.py             #   编辑器交互（预览/截图/控制器/发布）
│   │   └── file_tools.py              #   文件管理（移动/删除）
│   ├── parsers/
│   │   ├── xml_parser.py               #   FairyGUI XML 结构化解析器
│   │   └── description_gen.py          #   组件自然语言描述生成器
│   ├── bridge/
│   │   └── command_queue.py            #   命令队列管理器
│   └── utils/
│       └── window_manager.py           #   Windows 窗口管理（激活/截图）
│
└── plugin/MCPBridge/                   # FairyGUI 编辑器插件
    ├── package.json                    #   插件配置
    ├── main.lua                        #   插件入口（定时器轮询 + 日志缓冲）
    ├── src/
    │   └── command_handler.lua         #   命令处理器（编辑器操作实际实现）
    └── bridge/                         #   通信目录
        ├── commands/                   #   MCP → 编辑器
        ├── results/                    #   编辑器 → MCP
        └── screenshots/                #   截图输出

技术细节

通信协议

Lua 插件

• 基于 FairyGUI 插件系统，随编辑器启动自动加载
• 拦截 fprint 全局函数，维护环形日志缓冲区（最多 500 条）
• 持续重置 runInBackground，防止窗口失焦后定时器暂停
• 支持热重载信号文件机制，更新 command_handler.lua 无需重启

Python MCP 服务

• 基于 fastmcp 框架
• 自动检测项目路径（环境变量 → CWD 向上搜索 → 兜底）
• Windows 窗口管理：Win32 API 自动激活编辑器 + PrintWindow 截图

XML 解析

• 完整 FairyGUI 组件 Schema（控制器、显示列表、Gear、Relation、Transition、扩展属性）
• 结构化 dataclass 模型（Component、Controller、DisplayElement 等）
• 自然语言描述生成器，将组件结构转化为 AI 友好的文档

使用示例

AI 辅助 UI 开发

用户：帮我查看 Common 包里有哪些按钮组件

AI 调用: fg_list_resources("Common", "component")
AI 调用: fg_search_component("Button")
→ 列出所有匹配组件，包含 ID、路径、导出状态

自动化 UI 验证

AI 调用: fg_editor_open_component("Build", "BuildLevelUp")
AI 调用: fg_editor_list_controllers()
→ 获取所有控制器和页面

AI 调用: fg_editor_switch_controller("state", page_index=0)
AI 调用: fg_editor_screenshot(target="preview")
→ 截图验证正常状态

AI 调用: fg_editor_switch_controller("state", page_index=1)
AI 调用: fg_editor_screenshot(target="preview")
→ 截图验证 MAX 状态

组件分析与校验

AI 调用: fg_parse_component("Common", "ButtonItem")
→ 生成结构化描述：尺寸、控制器、元素列表、Gear/Relation 配置、动画定义

AI 调用: fg_validate_component("Common", "ButtonItem")
→ 验证：XML 格式、属性完整性、命名规范、ID 唯一性

批量发布

AI 调用: fg_editor_publish_all()
→ 发布所有 UI 包到 Unity 项目

依赖

Python（必填）

Python（可选，Windows 截图功能）

安装可选依赖：pip install -e ".[windows]"

常见问题

Q：显示"插件通信: 超时"

确保 MCPBridge 插件已加载。检查 FairyGUI 编辑器控制台是否有 [MCPBridge] 插件已启动。如果插件未加载，检查 plugins/MCPBridge/ 目录是否正确放置。

Q：截图功能不可用

编辑器全屏截图需要 pywin32 和 Pillow：pip install pywin32 Pillow。组件画布截图由 Lua 插件通过 GetScreenShot API 实现，不需要额外依赖。

Q：F5 预览模式下命令超时

F5 模式会将 runInBackground 设为 false。插件会持续重置此标志，但如果编辑器被其他全屏窗口遮挡，仍可能超时。确保编辑器在前台可见。

Q：支持 macOS/Linux 吗？

MCP 服务本身跨平台。Lua 插件运行在 FairyGUI 编辑器内（Unity），与操作系统无关。但窗口管理和全屏截图功能依赖 Windows API（pywin32），其他平台需要自行实现对应功能。欢迎贡献！

贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

致谢

• FairyGUI - 优秀的 Unity UI 解决方案
• fastmcp - Python MCP 框架
• Model Context Protocol - AI 工具通信协议

许可证

MIT License

---

Overview

MCP for FairyGUI is a Model Context Protocol (MCP) toolset that enables AI coding assistants (Claude Code, Cursor, etc.) to interact directly with the FairyGUI editor — browse UI resources, open and preview components, capture screenshots, switch controller states, and publish packages, all without manual editor operations.

How It Works

┌───────────────┐   MCP (stdio)   ┌─────────────────┐   File Polling  ┌─────────────────┐
│  AI Client    │◄──────────────► │  Python MCP Srv │◄──────────────► │  FairyGUI Editor│
│ (Claude Code) │                 │   (fastmcp)     │     JSON        │   (Lua Plugin)  │
└───────────────┘                 └─────────────────┘                 └─────────────────┘

1. AI assistant calls an MCP tool → Python MCP server receives the request
2. MCP server writes a JSON command to bridge/commands/
3. Lua plugin inside FairyGUI editor polls for commands every 100ms
4. Plugin executes the command in editor context, writes result to bridge/results/
5. MCP server reads the result and returns it to the AI assistant

Features

• Package & Resource Management — List, search, move, and delete UI resources
• Component Analysis — Read, parse, and validate component XML
• Editor Interaction — Open, save, close components; get selection
• Preview & Screenshots — Preview with device support; capture editor or canvas screenshots
• Controller Operations — List and switch controller pages
• Publishing — Publish individual or all packages
• Plugin Management — Hot-reload command handler; reload all plugins

System Requirements

• Python 3.10+
• FairyGUI Editor (Windows)
• MCP client (Claude Code / Cursor / any MCP-compatible tool)
• Windows OS (window screenshot features require Win32 API)

Quick Start

1. Install Python MCP Server

cd fairyGUI-MCP
pip install -e .

2. Install FairyGUI Editor Plugin

Copy plugin/MCPBridge/ into your FairyGUI project’s plugins/ directory:

your-fairygui-project/
└── plugins/
    └── MCPBridge/
        ├── package.json
        ├── main.lua
        ├── src/
        └── bridge/

Open FairyGUI editor and look for [MCPBridge] Plugin started in the console.

3. Configure MCP Client

{
  "mcpServers": {
    "fairygui-tools": {
      "command": "python",
      "args": ["-m", "mcp_fairygui.server"],
      "cwd": "/path/to/fairyGUI-MCP",
      "env": {
        "UI_PROJECT_PATH": "/path/to/your/fairygui-project"
      }
    }
  }
}

4. Verify

Call fg_editor_status — you should see “Editor: Running, Plugin communication: OK”.

Available Tools (22)

Contributing

1. Fork this repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push the branch: git push origin feature/amazing-feature
5. Submit a Pull Request

License

MIT License