kaohum/fairygui-mcp

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

41 stars 8 forks 质量 76 趋势 16MIT

Repository Install

FairyGUI 编辑器自动化的 MCP 工具集——让 AI 助手操作 FairyGUI

概览

MCP for FairyGUI 是一个基于 Model Context Protocol （MCP）的工具集，让 AI 编程助手（如 Claude Code、Cursor 等）能够直接与 FairyGUI 编辑器交互。 AI 助手可以浏览 UI 资源、打开和预览组件、截图验证、切换控制器状态、发布 UI 包——全程无需手动操作编辑器。 1. AI 助手调用 MCP 工具 → Python MCP 服务接收请求 2.MCP 服务将 JSON 命令写入 bridge/commands/ 目录 3.FairyGUI 中的 Lua 插件每 100ms 轮询命令文件 4.插件在编辑器内执行命令，将结果写入 bridge/results/ 5.MCP 服务读取结果，返回给 AI 助手 - 3.10+ - （Windows 版本） - MCP 客户端（Claude Code / Cursor / 其他支持 MCP 的工具）- Windows 操作系统（窗口截图功能依赖 Win32 API）将 plugin/MCPBridge/ 目录复制到你的 FairyGUI 项目的 plugins/ 目录下：打开 FairyGUI 编辑器，控制台出现 [MCPBridge] 插件已启动即表示成功。（~/.claude/settings.json 或项目 .mcp.json）： UI_PROJECT_PATH 是你的 FairyGUI 工程根目录（包含 assets/ 和 package.xml 的目录）。

概述（AI 翻译）

让 AI 助手直接操作 FairyGUI 编辑器，实现 UI 开发自动化

英文 |中文

概述

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

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

工作原理

通信流程：

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

功能特性

包与资源管理

工具	说明
`fg_list_packages`	列出项目中所有 UI 包（包名、ID、资源数）
`fg_get_package_info`	获取包详情（组件/图片/字体/文件夹列表）
`fg_list_resources`	按类型过滤列出包内资源
`fg_search_component`	跨包模糊搜索组件
`fg_move_resource`	移动或重命名包内资源
`fg_delete_resource`	删除资源（自动扫描引用，支持强制删除）

组件分析

工具	说明
`fg_read_component`	读取组件原始 XML 内容
`fg_parse_component`	解析 XML 为结构化自然语言描述（含控制器、Gear、Relation、动画）
`fg_validate_component`	验证组件规范（XML 格式、属性完整性、命名规范、ID 唯一性）

编辑器交互

工具	说明
`fg_editor_status`	检查编辑器和插件连接状态
`fg_editor_activate`	激活编辑器窗口到前台
`fg_editor_reload`	刷新项目或指定包的资源
`fg_editor_open_component`	在编辑器中打开组件进行编辑

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

概述

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 插件)     │
└───────────────┘                 └─────────────────┘             └─────────────────┘

通信流程：

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

功能特性

包与资源管理

工具	说明
`fg_list_packages`	列出项目中所有 UI 包（包名、ID、资源数）
`fg_get_package_info`	获取包详情（组件/图片/字体/文件夹列表）
`fg_list_resources`	按类型过滤列出包内资源
`fg_search_component`	跨包模糊搜索组件
`fg_move_resource`	移动或重命名包内资源
`fg_delete_resource`	删除资源（自动扫描引用，支持强制删除）

组件分析

工具	说明
`fg_read_component`	读取组件原始 XML 内容
`fg_parse_component`	解析 XML 为结构化自然语言描述（含控制器、Gear、Relation、动画）
`fg_validate_component`	验证组件规范（XML 格式、属性完整性、命名规范、ID 唯一性）

编辑器交互

工具	说明
`fg_editor_status`	检查编辑器和插件连接状态
`fg_editor_activate`	激活编辑器窗口到前台
`fg_editor_reload`	刷新项目或指定包的资源
`fg_editor_open_component`	在编辑器中打开组件进行编辑
`fg_editor_save`	保存当前打开的组件
`fg_editor_close`	关闭当前组件
`fg_editor_get_selection`	获取编辑器中当前选中的元素

预览与截图

工具	说明
`fg_editor_preview`	在预览窗口中显示组件
`fg_editor_start_test`	启动 F5 预览测试（支持指定设备分辨率，如 iPhone X、iPad Pro）
`fg_editor_stop_test`	停止 F5 预览
`fg_editor_capture_preview`	截取预览运行中的截图（支持切换设备分辨率）
`fg_editor_screenshot`	截取编辑器全屏或组件画布截图

控制器操作

工具	说明
`fg_editor_list_controllers`	列出当前组件的所有控制器（含页面名称和当前选中页）
`fg_editor_switch_controller`	切换控制器页面（按索引或名称）

发布

工具	说明
`fg_editor_publish_package`	发布指定 UI 包
`fg_editor_publish_all`	发布所有 UI 包

插件管理

工具	说明
`fg_editor_reload_plugin`	热重载命令处理器（无需重启插件）
`fg_editor_reload_all_plugins`	重载所有 FairyGUI 插件

系统要求

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。

在 GitHub 查看完整 README

安装

This server does not publish a one-line install command.

Open the repository installation guide 新手？先看 mcpskill.org 教程 →

配置

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