mcpField
G
glade-mcp

glade-mcp

本地服务
github.com/Glade-tool开发工具2131 周前更新

关于 glade-mcp

glade-mcp 将 AI 客户端连接到 Unity 和 Godot 编辑器,用于游戏开发。它通过自动检测当前编辑器的 MCP 服务,提供引擎专用工具、项目编辑、玩法脚手架和验证工作流。

主要功能

  1. 01连接 Unity 和 Godot 编辑器
  2. 02编辑场景、脚本和资源
  3. 03生成玩法脚手架
  4. 04通过截图和运行时检查验证项目
  5. 05构建和导出项目

适用场景

  1. 01在编辑器中创建玩法系统
  2. 02查找并重命名脚本引用
  3. 03开发时检查运行时行为
  4. 04构建或导出编辑器项目

MCP 相关

MCP 服务会检测正在运行的 Unity 或 Godot 编辑器,并向 MCP 客户端公开相应工具和资源。它通过编辑器桥接在本地端口建立连接。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"glade-tool-glade": {
"command": "uvx",
"args": [
"gladekit-mcp"
]
}
}
}
启动命令uvx gladekit-mcp

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypigladekit-mcp0.7.14

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

GladeKit MCP

将 Cursor、Claude Code、Windsurf、Claude Desktop 和其他 AI 客户端直接连接到 Unity 或 Godot 编辑器。

**Unity(2021.3+):**涵盖 20 个类别的 275 个工具、完整的 Unity 感知型系统提示词、GLADE.md 项目上下文、脚本语义搜索、技能校准、免费的 CC0 资源管线,以及具备 RAG 和跨会话记忆的云端智能层。

**Godot(4.3+):**涵盖 17 个类别的 115 个原生工具,包括场景/节点、脚本、资源、信号、物理和编辑时空间查询、2D(精灵、瓦片地图、视差)、音频、粒子、动画和 AnimationTree、摄像机、导航、UI、光照和 WorldEnvironment、运行时、导出及项目内省。

**两种引擎均支持:**一键生成经过审核的游戏玩法框架(控制器、敌人、战斗、菜单、存档系统)、验证循环(look_at_game_view 截图、运行时事件观察、可玩性探测)、精确脚本编辑并支持真正的 find_references / rename_symbol,以及构建/导出工具,让 Agent 能交付它构建的内容。

MCP 服务会自动检测正在运行的编辑器(Unity 使用 :8765,Godot 使用 :8766),并提供相应的工具集。

GladeKit MCP 演示


快速开始

1. 安装编辑器桥接程序

GladeKit MCP 同时支持 Unity 和 Godot。两个桥接程序都位于此仓库中:unity-bridge/ 是一个 UPM 包;godot-bridge/ 封装了位于 godot-bridge/addons/com.gladekit.mcp-bridge/ 的编辑器插件。请安装适用于你的引擎的版本。

Unity(2021.3+)

在 Unity 中,打开 Window > Package Manager > + > Add package from git URL...

https://github.com/Glade-tool/glade-mcp.git?path=/unity-bridge

Unity 桥接程序会自动在 localhost:8765 上启动。Window > GladeKit MCP 会显示桥接程序/客户端状态,并提供一键 Copy MCP Config 和 Copy Unity AI Gateway Config 按钮。

Godot(4.3+)
  1. 从最新的 Godot 桥接程序发布页下载 com.gladekit.mcp-bridge.zip。(请在 Assets 下下载 zip 文件,而不是“Source code”。)也可以直接从源代码安装:从此仓库复制 godot-bridge/addons/com.gladekit.mcp-bridge/。
  2. 将 com.gladekit.mcp-bridge/ 文件夹移入项目的 addons/ 目录,使最终路径为 <your-godot-project>/addons/com.gladekit.mcp-bridge/plugin.cfg。
  3. 在 Godot 中:Project → Project Settings → Plugins → 启用 GladeKit MCP Bridge。

Godot 桥接程序会自动在 localhost:8766 上启动。你应该会在编辑器的 Output 面板中看到确认信息:

[GladeKit MCP Bridge] listening on ws://127.0.0.1:8766  (v0.7.14, 115 tools registered, thread-polled at 200Hz)

桥接程序会将每个会话的身份验证令牌写入 ~/.gladekit/godot-bridge-8766.token;MCP 服务会自动读取该令牌,因此网页无法通过本地套接字驱动你的编辑器。

**支持:**Godot 4.3+ GDScript 项目、Forward+ 和 Compatibility 渲染器、2D 和 3D。**暂不支持:**Godot Mono / C# 项目。桥接程序仅用于编辑器,不会在导出的游戏中运行。

引擎自动检测:MCP 服务会在启动时探测两个端口,并提供相应的工具集。需要同时运行两个编辑器?设置 GLADEKIT_MCP_FORCE_ENGINE=unity 或 =godot,即可指定引擎。

2. 连接 AI 客户端

安装 uv(一次性操作):

  • Mac/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后将 MCP 配置添加到 AI 客户端。客户端会自动启动 MCP 服务,无需手动启动服务。

Claude Code

选项 A:一行命令(推荐)

  • Mac/Linux: claude mcp add --transport stdio gladekit-mcp --scope user -- uvx gladekit-mcp
  • Windows: claude mcp add --transport stdio gladekit-mcp --scope user -- cmd /c uvx gladekit-mcp

选项 B:手动配置

如果你克隆了此仓库,.mcp.json 会自动连接。否则,请将以下内容添加到 Claude Code MCP 设置中:

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
Cursor

Cursor Settings > MCP > Add new MCP server:

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(Mac)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
Cline (VS Code extension)

打开 Cline 的 MCP 设置文件(首次使用 MCP 时自动创建):

  • Mac: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

添加:

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
Windsurf

在 Windsurf 中,打开 Windsurf Settings → MCP Servers → Open MCP Registry,然后点击设置(齿轮)图标,打开 mcp_config.json。添加以下代码片段(或直接编辑 ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
Unity AI Gateway (native in-editor)

Unity 内置的 AI Assistant 可通过 MCP 连接 GladeKit。这样,你就能直接在 Unity Editor 中使用 GladeKit 的 275 个工具,无需外部 AI 客户端。

要求: Unity 6000.3+,并安装 AI Gateway 包([email protected])

  1. 在 Unity 中,前往 Edit > Project Settings > AI > MCP Servers
  2. 点击 Open Config File 并粘贴以下内容(或使用 Window > GladeKit MCP > Copy Unity AI Gateway Config):
{
  "enabled": true,
  "path": "",
  "mcpServers": {
    "gladekit-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}
  1. 在 Path Configuration 下,将终端中的 PATH 粘贴到 User Path,以便 Unity 找到 uvx。获取 PATH 的方法:
    • Mac/Linux: echo $PATH
    • Windows: echo %PATH%
  2. 点击 Refresh Config File and Reload Servers
  3. 确认 Servers 部分中的服务显示为 StartedSuccessfully

提示: 如果找不到 uvx,请将其所在目录添加到配置中的 path 字段(例如,Mac 上的 "/opt/homebrew/bin" 或 Windows 上的 "C:\\Users\\<you>\\.local\\bin")。或者,使用 pip install gladekit-mcp,并设置 "command": "python" 和 "args": ["-m", "gladekit_mcp"]。

故障排除: 如果服务显示为 FailedToStart,请点击 Inspect 查看错误详情。最常见的原因是 PATH 不正确——Unity 的 PATH 与终端中的 PATH 不同。请参阅下文的故障排除部分。

付费套餐(GLADEKIT_API_KEY): 若要在任何客户端上启用 RAG 知识库和跨会话记忆,请将密钥添加到配置的 env 字段。请参阅下文的云端智能。

VS Code (GitHub Copilot)

将以下内容添加到工作区中的 .vscode/mcp.json:

{
  "servers": {
    "gladekit-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gladekit-mcp"]
    }
  }
}

为什么选择 GladeKit?

特性GladeKit MCPunity-mcp (CoplayDev)godot-mcp (Coding-Solo)
引擎Unity 和 Godot,由单个服务自动检测UnityGodot
工具275 个 Unity 工具 + 115 个 Godot 工具,粒度细致48 个整合工具(action 枚举)14 个
编辑器连接实时编辑器会话(HTTP :8765 / WebSocket :8766)实时编辑器会话每次调用都会启动 godot --headless,并在磁盘上编辑 .tscn
游戏玩法脚手架生成器一次调用即可生成经过验证的模板——控制器、敌人、投射物、生命值 + HUD、游戏管理器、菜单、移动平台、存档系统无无
验证循环look_at_game_view 截图、运行时事件流、可玩性探测、修复后再验证门控、compile_scripts截图、读取控制台、测试运行器run_project + 原始 stdout
脚本编辑大纲 / 局部读取、锚点编辑、真正的 find_references / rename_symbol(词法扫描器)锚点 / 正则表达式编辑、Roslyn 验证无脚本工具
构建 / 导出支持两种引擎(build_player、export_project)Unity无(仅 MeshLibrary)
资源免费的 CC0 流程,带许可证审计AI 生成(自带 Tripo / Meshy / fal 密钥)无
项目上下文GLADE.md + 实时提示词(渲染管线、输入系统、技能水平)静态指令无
脚本搜索通过 OpenAI embeddings 进行语义搜索(自备密钥)正则表达式 find_in_file无
记忆会话内(remember_for_session)+ 跨会话(云端)无无
安全性编辑操作支持撤销、修改前备份、覆盖保护、按会话进行令牌身份验证、只读模式SHA 保护的脚本编辑无
测试269 个 pytest + 覆盖 37 个用例的评测(针对 3 个 MCP SDK 版本)、schema↔bridge 一致性保护、Unity NUnit + Godot GUT 测试套件Unity CI 矩阵 + NL 套件无
许可证MITMITMIT
已于 2026-08-29 对照 unity-mcp v10.1.2 和 godot-mcp 0.1.1 的源码进行验证。godot-mcp 是星标数最多的 Godot 服务;最接近的活跃编辑器内替代方案 godot-ai(46 个工具)支持截图和批量执行,但不支持脚手架生成、重构、资源管线、导出或记忆功能。

所有核心功能均免费且可在本地运行。云端智能层为可选功能,需要 GLADEKIT_API_KEY。


功能

275 个 Unity 工具 + 115 个 Godot 工具

Unity(20 个类别): 场景 • GameObjects • 脚本 • 预制体 • 材质 • 光照 • VFX 和音频 • 动画 • IK • 物理(3D 和 2D) • Tilemaps • 摄像机 • UI • 输入系统 • 地形和 NavMesh • 性能分析器 • 游戏玩法脚手架生成器 • 运行时和诊断 • 构建 • 资源管线

全部 275 个工具均可调度。Claude Code 默认会看到约 90 个精选核心工具(Claude Code 的实际工具数量上限为 128 个;Unity AI Gateway 受云端令牌预算限制)。使用 get_relevant_tools 可发现用于专业工作的扩展工具(混合树、NavMesh、IK、Cinemachine 等)。

5 个元工具: get_relevant_tools(基于任务的工具发现 + RAG 上下文)、remember_for_session(存储事实)、recall_session_memories(检索事实)、batch_execute(多步工具调度)、search_project_scripts(语义代码搜索,仅限 Unity)。前四个工具适用于两种引擎。

9 个 MCP 资源(Unity): 桥接健康状态、项目上下文、项目信息、场景层级、项目脚本、当前选择、GLADE.md、会话记忆和批处理规范遥测数据。

Godot(17 个类别): 全部 115 个工具均直接开放(无需核心工具筛选),另有四个引擎无关的元工具。只读工具带有 MCP readOnlyHint 注解,客户端可据此自动批准。

一次调用即可生成游戏玩法脚手架

经过验证、可自动连接的模板,会原样写入可靠脚本并围绕脚本组装场景,同时保留从头编写脚本时容易遗漏的游戏手感细节(土狼时间、跳跃缓冲、可变跳跃高度、对角线归一化)。再次运行时会复用已有内容,而不会重复创建。

  • 玩家: create_third_person_controller(3D,两种引擎均支持)、create_platformer_controller / create_top_down_controller(Unity)、create_2d_controller(Godot)。
  • 战斗: create_projectile、create_health、create_health_bar、create_enemy(Unity)/ create_enemy_2d + create_enemy_3d(Godot)、create_hit_vfx。
  • 游戏循环: create_game_manager(分数、生命、胜利/失败)、create_collectible、create_hazard、create_level_system、create_loot_drop、create_save_system。
  • 流程与手感: create_main_menu、create_pause_menu、create_scene_transition、create_moving_platform、create_screen_shake、create_juice、create_particles_2d / _3d、create_sound_effects。

批量布局工具(set_transform_batch、set_node_transform_batch、arrange_nodes、snap_to_ground)可通过一次调用放置数十个对象,无需逐个往返调用。

验证构建成果 - **查看画面:** `look_at_game_view` 会返回渲染视图的截图,帮助模型发现仅靠检查无法察觉的隐藏、缺失或位置错误的对象。 - **观察运行:** `start_runtime_observation` / `get_runtime_events` 会从运行会话中持续传输带游标和指纹的错误信息流;原始日志可使用 `get_unity_console_logs` / `get_godot_console_logs` 获取。 - **进行游戏测试:** `start_playability_probe`(Unity)和 `run_gameplay_probe`(Godot)会通过输入控制玩家并报告 PASS/FAIL;Godot 的 `run_project` 提供 `verify` 模式,可运行、捕获并报告结果。 - **编译并交付:** `compile_scripts`(Unity);`build_player` + `get_build_status`(Unity),以及 `create_export_preset` + `export_project`(Godot,包括 Web)。 - **诊断卡顿(Godot):** 编辑器主线程看门狗会将“超时”转化为“编辑器已卡死 12 秒——请关闭模态对话框”,并提供 `possible_solutions`。
精准脚本编辑

get_script_content 支持大文件的轮廓模式(结构概览)和按行范围读取;modify_script 可应用基于锚点的编辑。find_references 和 rename_symbol 使用词法扫描器(支持 C# 和 GDScript),只匹配完整标识符,因此重命名前就能看到实际影响范围。除非用户明确要求,否则 create_script / modify_script 不会覆盖现有项目脚本。

GLADE.md

在 Unity 项目根目录中创建 GLADE.md 文件。MCP 服务会读取该文件,并将其注入每个请求中。它可作为永久上下文层,始终提供游戏的设计意图、约定和限制。

# My Game

Genre: 3D platformer
Player: CharacterController, double jump enabled
Art style: pixel art, 16x16 sprites
Naming: PascalCase for scripts, snake_case for folders
脚本语义搜索

在 MCP 配置的 env 字段中设置 OPENAI_API_KEY,服务便会根据语义相似度为项目脚本排序。询问“敌人是如何生成的?”,即可找到相关脚本,即使脚本名不是 EnemySpawner。

所需内容均随软件包提供,无需安装标志或额外组件。可在 platform.openai.com/api-keys 获取密钥(按量付费,每次搜索只需几分钱,使用 text-embedding-3-small)。

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

没有密钥时,search_project_scripts 仍会返回脚本,只是不进行排序。密钥只会发送到 OpenAI 的嵌入端点。

技能水平校准

服务会跟踪你消息中的词汇,并判断你是 Unity 初学者还是专家。初学者会收到通俗易懂的解释和鼓励性的措辞;专家则会收到简洁、专业的回复。校准结果会保存到项目中的 .gladekit/skill_level.json。

资源流程(免费 CC0 导入)

提供三个工具,可在两种引擎中直接通过 AI 客户端查找并导入免费且可商用的资源。所有资源均为 CC0(公有领域,无需署名)。v1 随附 Kenney.nl 资源包(每周更新目录);其他提供方(Freesound、Quaternius、AI 生成)已列入路线图。

工具用途
find_asset按描述、资源类型、风格和许可证搜索并排序候选资源。只读,不会将操作分派给编辑器。
import_asset下载、解压、放置到 Assets/(或 res://)下,为资源类型配置导入设置,并写入包含许可证元数据的 .gladekit-asset.json 旁车文件。需要明确提供 licenseAcknowledged: true。
list_imported_assets遍历项目中的旁车文件并显示许可证审计信息(许可证数量、需要署名的数量)。适合在商业发行前使用。

示例工作流(Cursor、Claude Code、Windsurf 使用相同的模式):

你: 我正在制作一款 2D 平台游戏原型,需要临时使用角色和图块美术资源。帮我找一些免费的。

AI 调用 find_asset:

{
  "description": "platformer character and tiles",
  "asset_type": "sprite_2d",
  "max_results": 5
}

结果(已截断):

{
  "success": true,
  "candidates": [
    {
      "id": "kenney/platformer-pack-redux",
      "name": "Platformer Pack Redux",
      "description": "360+ side-scrolling platformer sprites: characters, enemies, tiles, items, hazards.",
      "license": "CC0-1.0",
      "license_summary": "Public domain. No attribution required for any use, including commercial.",
      "official_page": "https://kenney.nl/assets/platformer-pack-redux",
      "approx_assets": 360,
      "score": 0.92
    },
    { "id": "kenney/pixel-platformer", "score": 0.71, ... },
    { "id": "kenney/tiny-town", "score": 0.45, ... }
  ],
  "count": 3
}

你: 就选 Platformer Pack Redux 吧。把它导入到 Assets/Sprites/Platformer/。我接受 CC0 许可证。

AI 调用 import_asset:

{
  "candidateId": "kenney/platformer-pack-redux",
  "assetType": "sprite_2d",
  "licenseAcknowledged": true,
  "targetPath": "Assets/Sprites/Platformer/"
}

MCP 服务在本地解析下载 URL(目录随服务一同打包,无需依赖云端),并将其传递给 Unity 桥接程序。桥接程序会下载、解压、为每个精灵配置 TextureImporter(Texture Type = Sprite、Filter Mode = Point、Uncompressed),然后写入许可证旁车文件。结果:

{
  "success": true,
  "message": "Imported 360 file(s) from kenney/platformer-pack-redux to Assets/Sprites/Platformer/",
  "downloadedBytes": 1842340,
  "importedFileCount": 360,
  "configuredImportSettings": 354,
  "license": "CC0-1.0",
  "sidecarPath": "Assets/Sprites/Platformer/.gladekit-asset.json"
}

精灵会显示在 Unity Project 窗口中,可以直接拖入场景。

你: 发布之前,审计一下我导入的资源。有没有需要署名的?

AI 调用 list_imported_assets:

{
  "success": true,
  "count": 1,
  "licenseCounts": { "CC0-1.0": 1 },
  "attributionRequiredCount": 0,
  "entries": [
    {
      "candidate_id": "kenney/platformer-pack-redux",
      "license": "CC0-1.0",
      "asset_type": "sprite_2d",
      "imported_at": "2026-05-10T09:37:42Z",
      "target_path": "Assets/Sprites/Platformer/",
      "imported_file_count": 360,
      "sidecar_path": "Assets/Sprites/Platformer/.gladekit-asset.json"
    }
  ]
}

CC0 无需署名;审计报告中没有需要署名的项目。如果之后导入了 CC-BY 资源,它会显示在这里,提醒你注明出处。

安全性与许可证规范:

  • 大模型看不到下载 URL。URL 解析在云端/MCP 端进行;如果解析后的字段缺失或由大模型注入,桥接工具会拒绝操作。
  • 每次调用 import_asset 都必须提供 licenseAcknowledged: true。没有该参数,桥接程序会拒绝操作。未经用户明确确认,不要设置该参数。
  • 下载前,桥接程序会根据每个提供方的允许列表,验证 _resolvedUrl 的主机名(AssetPipelineGuard.IsResolvedUrlHostAllowed)。即使客户端绕过云端和 MCP 的预处理环节,也无法偷偷传入任意下载 URL;未知主机名会被默认拒绝。仅支持 HTTPS。
  • 每个导入的资源包都会获得一个 .gladekit-asset.json 旁车文件,其中记录候选资源 ID、提供方、许可证、署名字符串、源 URL 和时间戳。list_imported_assets 会读取这些文件以生成审计报告。
  • 桥接端通过 AssetPipelineGuard 控制资源管线工具。配置错误的客户端无法绕过此限制。

禁用管线(适用于工作室或精选资源工作流):

在 MCP 服务的环境中设置 GLADEKIT_MCP_DISABLE_ASSET_PIPELINE=1,即可完全停用这三个工具。它们不会出现在工具列表中,分派请求时也会返回明确的错误。对于已有受管资源工作流的项目(例如由 Perforce 跟踪的资源库、内部资源存储库),不适合使用 AI 驱动的外部下载;建议此类项目采用此设置。

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"],
      "env": { "GLADEKIT_MCP_DISABLE_ASSET_PIPELINE": "1" }
    }
  }
}

Unity 桥接程序通过 EditorPrefs(GladeAI.AssetPipelineEnabled,默认值为 true)实施相同的限制。可通过 POST http://localhost:8765/api/settings { "assetPipelineEnabled": false } 切换此设置。

安全与防护
  • **可撤销:**搭建脚手架和批量编辑会登记到编辑器的撤销栈(Unity),或在修改前于 .gladekit-backups/ 中创建备份,并支持通过节点撤销(Godot)。create_script / modify_script 未显式指定标志时,会拒绝覆盖项目中的实际脚本。
  • **仅限回环地址:**两个桥接服务都绑定到 127.0.0.1。Godot 桥接服务要求每个请求都携带会话专用令牌(~/.gladekit/godot-bridge-<port>.token),但 health 除外,以防止跨站 WebSocket 偷偷发起驱动请求。Unity 桥接服务会对文件端点实施本地主机访问控制和路径遍历防护。
  • **运行模式安全:**编辑器运行时,编辑工具会拒绝执行;只读工具在两种模式下都可运行。
  • 只读会话:GLADEKIT_GODOT_READ_ONLY=1(或在项目设置中设置 gladekit/read_only_mode)会让 Godot 桥接服务拒绝所有会修改内容的工具,适用于审计、审查和演示。
云端智能

在 MCP 配置的 env 字段中设置 GLADEKIT_API_KEY,即可启用云端功能:

  • RAG 知识库 - get_relevant_tools 会查询经过整理且适配引擎的知识库(API 修正、错误模式),并将结果与工具推荐一同注入。Godot 会话会检索 Godot 文档,而非 Unity 内容。
  • 跨会话持久记忆 - 使用 remember_for_session 存储的事实会跨会话保留,并重新注入系统提示词。
  • 约定提取 - 从积累的记忆中提炼编码模式(命名、架构、偏好),并在后续会话中提供。

所有云端功能都能优雅降级:如果缺少密钥或无法连接云端,一切仍可正常运行。

{
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"],
      "env": { "GLADEKIT_API_KEY": "your-api-key" }
    }
  }
}
传输方式(stdio + streamable HTTP)

GladeKit MCP 支持两种传输方式。stdio 是默认方式,适用于所有 MCP 客户端——以上所有配置都使用 stdio。服务端同时支持 MCP SDK 1.x 和 2.x(mcp[cli]>=1.10,<3),并在最低版本、最新的 1.x 和最新的 2.x 上进行测试。

Streamable HTTP 适用于偏好基于 URL 配置的客户端(Claude Desktop URL 模式、自定义客户端)。手动启动服务端,然后将客户端指向该 URL:

# Defaults: host=127.0.0.1, port=8767, path=/mcp
gladekit-mcp --transport http

# Custom host/port/path
gladekit-mcp --transport http --host 127.0.0.1 --port 9000 --path /mcp

端点:

  • POST/GET/DELETE http://127.0.0.1:8767/mcp - MCP streamable-HTTP 端点
  • GET http://127.0.0.1:8767/health - 存活检查

安全默认设置:

  • 仅绑定到回环地址(127.0.0.1)。使用 --host 0.0.0.0 可开放到局域网,但需主动选择。
  • 回环地址绑定时会启用 DNS 重绑定防护:Host 标头不是 127.0.0.1:<port> 或 localhost:<port> 的请求会被拒绝,并返回 421 Misdirected Request。
  • 非回环地址绑定时会禁用重绑定防护(网络安全由你负责),并在启动时打印警告。

客户端配置示例:

{
  "mcpServers": {
    "gladekit-mcp": {
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}
环境变量

MCP 服务(在客户端配置的 env 字段中设置):

VariableRequiredDescription
UNITY_BRIDGE_URLNoUnity 桥接 URL(默认值:http://localhost:8765)
GODOT_BRIDGE_URLNoGodot 桥接 URL(默认值:ws://localhost:8766/)
GLADEKIT_MCP_FORCE_ENGINENounity 或 godot——当两个编辑器都打开时,跳过自动检测
OPENAI_API_KEYNo启用基于嵌入的脚本语义搜索(获取一个)
GLADEKIT_API_KEYNo启用 RAG 知识库、跨会话记忆和约定提取
GLADEKIT_MCP_DISABLE_ASSET_PIPELINENo设置为 1 可屏蔽 find_asset / import_asset / list_imported_assets(精选资源工作流)
GLADEKIT_MCP_SUPPRESS_BRIDGE_WARNINGNo设置为 1 可关闭 Unity 或 Godot 桥接版本低于推荐版本时的 stderr 警告

Godot 桥接(启动 Godot 之前在 shell 中设置):

VariableDescription
GLADEKIT_GODOT_BRIDGE_PORT监听端口(默认值为 8766)
GLADEKIT_GODOT_READ_ONLY设置为 1,拒绝此编辑器会话的所有修改类工具
GLADEKIT_GODOT_NO_AUTH设置为 1,禁用每会话令牌身份验证(适用于较旧的客户端;选择启用)
故障排除

Unity 桥接无法连接

  • 打开 Unity 并等待其完成资源导入——桥接会自动启动
  • 在 Unity 中检查 Window > GladeKit MCP——Bridge 和 AI Client 指示器会显示连接状态;Restart 会重新绑定服务,Diagnostics 面板会显示近期桥接故障
  • 确认没有其他程序占用端口 8765:lsof -i :8765(Mac/Linux)或 netstat -ano | findstr 8765(Windows)

Godot 桥接无法连接

  • 确认插件已启用,且 Output 面板显示 listening on ws://127.0.0.1:8766;绑定失败时会打印 GLADEKIT_GODOT_BRIDGE_PORT 覆盖设置说明
  • 工具错误中出现 authentication failed:MCP 服务无法读取 ~/.gladekit/godot-bridge-8766.token。重启 Godot(它会重新写入令牌),或者对于较旧的客户端,在启动 Godot 前设置 GLADEKIT_GODOT_NO_AUTH=1
  • 对话框打开时工具调用超时:编辑器的主线程被阻塞。关闭对话框;错误信息会指出卡顿时长

AI 客户端找不到 uvx

  • 安装 uv:curl -LsSf https://astral.sh/uv/install.sh | sh(Mac/Linux)或 pip install uv
  • 或者使用 pip install gladekit-mcp,并将配置命令从 "uvx" 改为 "python",参数设为 ["-m", "gladekit_mcp"]

Claude Code 中未显示工具

  • Claude Code 实际上最多支持约 128 个工具。GladeKit 默认显示约 90 个精选核心工具——这是有意为之。全部 275 个工具都可调用:使用 get_relevant_tools 按任务描述查找扩展工具。

未加载 GLADE.md

  • 文件名必须准确为 GLADE.md(Mac/Linux 上区分大小写),并放置在 Unity 项目根目录下(与 Assets/、Packages/、ProjectSettings/ 同级)

Stderr 警告:Unity bridge X.Y.Z is older than recommended

  • Unity 会缓存 UPM Git 包,且不会重新获取,因此 ?path=unity-bridge 安装版本会随着时间推移逐渐落后于 main。通过 Unity → Window > Package Manager > GladeKit MCP Bridge > Update 更新,或将清单条目固定到特定标签,以便明确控制后续更新:

    "com.gladekit.mcp-bridge": "https://github.com/Glade-tool/glade-mcp.git?path=unity-bridge#v0.7.23"
    
  • 同一条警告也会作为一次性前缀出现在下一条工具响应中,方便你在聊天中看到。若要同时关闭这两处提示:在 MCP 客户端配置的 env 中添加 "GLADEKIT_MCP_SUPPRESS_BRIDGE_WARNING": "1"。对于 Godot,请用最新版本的 zip 替换 addon 文件夹。

Unity AI Gateway - 服务显示 FailedToStart

  • 在 Servers 部分点击 Inspect 查看错误消息
  • 最常见的原因:Unity 找不到 uvx。在 Path Configuration 下,将终端中的完整 PATH 粘贴到 User Path,然后点击 Refresh Config File and Reload Servers
  • 在 Windows 上:在 Command Prompt 中运行 echo %PATH%。在 Mac/Linux 上:运行 echo $PATH
  • 另一种方法:使用 pip install gladekit-mcp,并将命令设为 "python",参数设为 ["-m", "gladekit_mcp"],这样就无需依赖 uvx 的 PATH
  • 先在 Unity 外验证:在终端中运行 uvx gladekit-mcp(你应该能在 stderr 中看到 gladekit-mcp v... 横幅)
架构
[AI Client: Cursor / Claude Code / Windsurf / Claude Desktop / Unity AI Gateway]
         |
         | stdio or HTTP MCP protocol
         v
[gladekit_mcp Python process]
    bridge.py -> probes :8765 (Unity, HTTP) and :8766 (Godot, WebSocket), picks the engine
    prompts.py -> system prompt (auto-reads render pipeline, input system, GLADE.md)
    tools/ -> 275 Unity tool schemas + dispatch      schemas/godot/ -> 115 Godot tool schemas
    asset_pipeline/ -> bundled CC0 catalog + URL resolution
    cloud.py -> optional GLADEKIT_API_KEY -> api.gladekit.com
         |                                  |
         | HTTP localhost:8765              | WebSocket localhost:8766 (+ session token)
         v                                  v
[Unity Bridge -- C# Editor extension]     [Godot Bridge -- GDScript EditorPlugin]
    unity-bridge/ (UPM package)              godot-bridge/addons/com.gladekit.mcp-bridge/
    UnityBridgeServer.cs -> HttpListener     ws_server.gd -> TCPServer + WebSocketPeer
    275 ITool implementations                115 tool implementations (main-thread dispatch)
    UnityContextGatherer, PlayModeObserver,  context_gatherer, play_session_manager,
    BackupManager, BuildManager              backup_manager, export_manager, bridge_auth
参与贡献

每个桥接程序都是其工具的事实来源;Python 服务会镜像其架构。每当 mcp-server/、unity-bridge/ 或 godot-bridge/ 有变更时,CI 都会运行(包括 ruff、pytest,以及针对三个 MCP SDK 版本的评估测试框架);如果某个参数只存在于一侧,架构↔桥接程序字段一致性测试就会失败。添加一个工具需要进行三处更改。

Unity

  1. C# 实现(unity-bridge/Editor/Tools/Implementations/<Category>/MyTool.cs):
public class MyTool : ITool
{
    public string Name => "my_tool";
    public string Execute(Dictionary<string, object> args)
    {
        // ... Unity Editor API calls ...
        return ToolUtils.CreateSuccessResponse("Done", extras);
    }
}
  1. C# 注册(unity-bridge/Editor/Tools/Registrars/<Category>Tools.cs):添加 Register(new MyTool());。注册是显式的——未注册的工具可以正常编译,但在分发时会返回 "Tool was blocked from executing or null."。

  2. Python 架构(mcp-server/src/gladekit_mcp/tools/<category>.py):按照现有格式(OpenAI 函数调用架构)在该类别的工具列表中添加一项。

Godot

  1. GDScript 实现(godot-bridge/addons/com.gladekit.mcp-bridge/tools/implementations/<category>/my_tool.gd),继承 i_tool.gd;在 _init() 中设置 tool_name 和 requires_edit_mode,并返回 ToolUtils.success(...) / ToolUtils.error(...)。

  2. 注册:在 godot-bridge/addons/com.gladekit.mcp-bridge/bridge/tool_registry.gd 中注册(register_tool(MyTool.new()))。

  3. Python 架构(mcp-server/src/gladekit_mcp/schemas/godot/<category>.py)。

有关传输协议和 GUT 测试设置,请参阅 godot-bridge/README.md;有关发布历史,请参阅 mcp-server/CHANGELOG.md。


许可证: MIT,详见 LICENSE。

GladeKit 桌面应用 是一款独立的商业产品,在此 MCP 服务基础上增加了流式传输、遗漏恢复和记忆界面。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。