Beckett - MCP for Godot

Beckett — Godot 的 MCP

别再等待 Godot。

Beckett 是一个零旁路进程模型上下文协议（MCP）服务，作为 GDScript EditorPlugin 直接嵌入 Godot 4 编辑器。AI Agent（Claude 等）通过 HTTP 驱动编辑器——无需 Node/Python 桥接程序，无需第二个进程，也无需云端服务。

本仓库提供免费的 MIT 许可 Lite 版：完整的 检查 → 编写 → 运行 → 查看 开发循环（56 个工具），支持 GDScript 和 C#。现在，免费版中的 AI 也能观看正在运行的游戏：截取游戏画面、读取实时远程场景树和节点状态、轮询性能监视器，以及跟踪游戏日志。付费的 Full 版让 AI 成为游戏测试者（它可以驱动输入、点击 2D/3D 和 UI，并验证结果），此外还提供测试运行器、动画工具、scatter_nodes、后台导出、项目级分析和 46 个知识包。参见Full 版新增功能。

Lite：AI 能看见你的游戏。Full：AI 能对游戏进行测试。

演示

为什么

现有的 Godot MCP 服务要么通过命令行调用外部程序（无法运行游戏、截图或检查运行时状态），要么运行一个将请求转发给精简版编辑器内插件的 Node/Python 旁路进程。而本项目让插件本身成为 MCP 服务，并通过 ClassDB 提供适用于任意类的反射泛型工具，而不是为每个领域手工编写数百个包装器（这是一种反模式：LLM 使用超过约 40 个工具后，表现会下降）。

亮点

• 零辅助进程 — TCPServer HTTP/JSON-RPC 服务在编辑器主线程上轮询。无需编组，除插件外无需安装任何额外组件。
• AI 可以看到你的游戏（免费） — 对运行中的游戏进行 screenshot，读取实时远程场景树（get_remote_tree / find_nodes / wait_for_node），读取实时节点状态（runtime_get_property / monitor_properties），轮询 get_performance_monitors，并通过 game_logs 查看日志及堆栈跟踪。免费版可以观察和诊断运行中的游戏；Full 则通过驱动输入并验证结果，完成整个闭环。
• GDScript 和 C#，一个插件，零辅助进程 — C#/.NET 开发循环也免费：build_csharp 会运行 dotnet build 编译检查，并返回结构化的 file:line:col 和 CS 代码诊断（编辑器打开时也安全，无需安装 C# 项目本来就不需要的 .NET SDK 以外的依赖）；write_script 支持 .cs，反射也会像 GDScript 的 class_name 一样呈现你的 C# [GlobalClass] 类型。
• 反射优先 + 发现功能 — find_classes / describe_class / find_methods 让整个引擎接口都可供搜索；接着通过 describe_object / set_property / call_method 操作任意 Node / Resource / Object。无需编写特定领域代码，即可处理 TileMap、GPUParticles、AnimationTree、NavMesh、着色器等。
• 带写入前验证的 GDScript 开发循环 — write_script / script_patch 会先解析代码，并拒绝写入无法编译的代码（解决 AI 使用 Godot 时最常见的问题：编造 GDScript）。Godot 相较于 UE 的优势：重新加载无需编译。
• 可撤销的创作操作 — 所有场景/节点变更都通过 EditorUndoRedoManager 执行（原子操作且可撤销）；batch_execute 会在失败时回滚整个批次。
• 一步安装 — 启用插件后会自动启动服务并写入 .mcp.json，因此 claude/Cursor 无需手动编辑即可连接（无需安装 Node.js——竞品连试用都需要它）。
• 安全性：仅限 localhost，并严格检查 Host 和 Origin（防止 DNS 重绑定）；新项目使用独立令牌；文件读取限制在项目目录内；并设有只读、允许列表和破坏性操作确认限制；自动启动可选择关闭（beckett/autostart=false）。SECURITY.md 说明了哪些内容受到保护、哪些不受保护，以及如何报告问题。
• 运行 → 查看循环 — play_scene → wait_until → logs_read → screenshot / get_remote_tree → 修复：启动游戏、查看其输出和错误，再检查运行画面和实时场景树以进行诊断。（Full 可自主完成闭环：AI 驱动游戏并验证结果。）此外还支持 MCP Resources + Prompts。
• 停靠面板 — 显示状态，提供一键启动/停止、复制客户端配置，以及 AI 努力度滑块（Lite 中为 1–4；L4 = 查看），用于限制公布的工具数量：只需要一部分工具时，可减少模型上下文开销。实时生效，无需重新连接 — 服务会通过其 SSE 流推送 notifications/tools/list_changed，支持列表变更通知的客户端（Claude Code、Cursor 等）会立即重新获取列表。
• 失焦时也能保持响应 — MCP 流量活跃期间，服务会限制编辑器的低处理器休眠，因此即使焦点在终端而非编辑器上（常见的 Agent 使用方式），调用仍能快速响应。
• 符合当前 MCP 规范 — 支持协议版本协商；每个工具都带有工具注解（readOnlyHint/destructiveHint/openWorldHint），并在文本结果之外提供 structuredContent（2025-06-18）。审计环形缓冲区（audit://recent）会记录最近 200 次工具调用，让 AI 的所有操作一目了然。

工具（56）· 资源（6）· 提示词（6）

工具更少，是刻意为之——这是我们的护城河，而非限制。 大多数 Godot MCP 都会为每项任务手写一个工具（create_sprite、add_collision、make_timer……），结果是数百个工具仍然遗漏类，还会塞满模型的上下文（有可量化的证据表明，大模型在工具数量超过约 40 个后性能会下降）。Beckett 的工具采用反射泛型设计：describe_class / set_property / call_method 可通过 ClassDB 驱动 Godot 的任意 1000 多个类——TileMap、GPUParticles、AnimationTree、着色器、你自己的 class_name 或 C# [GlobalClass]——无需编写针对特定领域的代码。**别数工具数量，要看覆盖范围：**更小、更精炼的工具集能够触及整个引擎，胜过一百个覆盖面狭窄的封装工具。

免费的 Lite 版本提供完整的检查 → 编写 → 运行 → 查看循环，支持 GDScript 和 C#：

• 反射 / 发现： get_godot_version、find_classes、describe_class、find_methods、describe_object、set_property、call_method、get_scene_tree
• 场景编写（可撤销）： create_node、delete_node、rename_node、reparent_node、duplicate_node、move_node、instance_scene、save_scene、open_scene
• GDScript 开发循环： validate_script、write_script、script_patch、read_script、attach_script
• C#/.NET 开发循环： build_csharp（通过 dotnet build 执行编译检查，返回结构化的 file:line:col + CS 代码诊断；编辑器打开时也能安全运行，无需新增依赖；write_script 支持 .cs，且 C# [GlobalClass] 类型会显示在反射结果中）
• 信号： connect_signal、disconnect_signal、list_signals
• 资源资产： create_resource、set_resource
• 文件 / 项目： read_file、write_file、list_dir、search_files、rescan_filesystem、get_project_setting、set_project_setting
• 运行循环： play_scene、stop_scene、get_play_state、wait_until、logs_read
• 运行时观察（AI 能看到你的游戏）： screenshot、ui_snapshot（一次调用即可将每个可见 Control 作为结构化状态返回）、get_remote_tree、find_nodes、wait_for_node、runtime_get_property、monitor_properties、get_performance_monitors、game_logs
• 渲染诊断： render_probe（以数据形式说明 3D 节点为何显示或未显示在屏幕上：可见性链、视锥体、剔除遮罩、材质剔除模式、三角形绕序）和 set_debug_draw（切换运行中游戏的调试绘制模式，然后通过 screenshot 查看一个渲染阶段）
• 项目 / 编写辅助工具： get_project_statistics、apply_template、batch_execute、doctor（一次调用即可自我诊断：版本、工作量上限、服务与身份验证状态、客户端配置，以及各层级的工具列表会占用多少上下文）、help（按需获取任意工具的完整参数目录）
• MCP 资源： scene://tree、scene://selection、project://settings、assets://list、log://output、audit://recent
• MCP 提示词： inspect_node、audit_scene、setup_2d_player、fix_script_errors、build_test_fix、make_game

Full 版新增内容

Full 版在相同的核心功能上增加了高级层，让 AI 成为试玩测试者：它能看到屏幕、按下按钮并验证结果。总计 92 个工具、46 个技能包：

• AI 操控游戏： simulate_input、2D + 3D UI 点击（click_button_by_text / click_control / click_node3d / click_world）、scroll / drag、get_control_rect / find_ui_elements、实时 runtime_call / runtime_set_property，以及 record_input / replay_input。
• AI 验证结果： assert_node_state、assert_screen_text、assert_scene、compare_screenshots，以及编辑器内的测试运行器（test_run）。
• 创作并发布： animation_manage（关键帧 / 轨道 / 预设）、scatter_nodes（Scene-Paint 批量放置）、后台 export_project + job_status、项目级分析（find_unused_resources、detect_circular_dependencies），以及 Godot Asset Store / Library 浏览器安装工具（asset_lib_search / asset_lib_info / asset_lib_install）。
• 46 个技能知识包（list_skills / load_skill）：gdscript、粒子、动画、UI、物理、多人游戏、移动端等，因此反思功能可以覆盖各个领域，无需为每个领域单独提供工具。

Lite 附带游戏端运行时（addons/beckett/runtime/mcp_runtime.gd，MIT 源码），供 Full 的操控工具使用；该运行时能够理解操控命令。Lite 的工具不会发送这些命令，且 Lite 的桥接层会拒绝这些命令，因此 Lite 可以看到正在运行的游戏，但无法操控它。这是产品功能边界，并非沙箱；详情请参阅 SECURITY.md。

Full 为一次性购买（$15），终身更新：https://beckettlabs.itch.io/beckett-godot-mcp

对比

Beckett 是业界少数几款嵌入式（无需旁挂服务）服务之一，而且其免费版就包含查看正在运行的游戏的功能，Native 也是如此。其他产品也各有优势（原始工具数量、知名度、覆盖面），下面是客观对比。（竞品数据来自其自行公布的数字；它们提供的手写领域专用工具更多，这是不同的设计选择，并不严格等同于“能力更强”：见 原因。）

	Beckett Lite（免费，MIT）	Beckett Full（$15）	CLI 外部调用（例如 Coding-Solo，免费）	旁挂服务（godot-mcp-pro，$15，Node 18+）	Native（免费，嵌入式，仅支持 4.6+）
无需旁挂服务（无需 Node/Python）	✅	✅	❌（Node CLI 外部调用）	❌（Node 18+ + TS 服务）	✅（嵌入式）
AI 能看到正在运行的游戏（屏幕截图、实时场景树、实时状态）	✅ 免费	✅	⚠️ 仅 CLI 调试输出	✅（付费）	✅（免费）
AI 能操控并断言（试玩测试：输入、点击、断言）	❌	✅	❌	✅（输入录制 / 重放）	⚠️ 部分支持
写入前验证（拒绝无法编译的 GDScript）	✅	✅	❌	❌	❌
C# + GDScript	✅	✅	❌（GDScript）	❌（GDScript）	❌（GDScript）
Godot 4.2+	✅	✅	因产品而异	因产品而异	❌（仅支持 4.6+）
工具数量	56	92	~12	~163	154

无意贬低其他产品：Coding-Solo 是知名度最高的产品（约 4,000★），godot-mcp-pro 提供最全面的精选工具集（约 163 个），并支持输入录制 / 重放；Native 则免费提供 154 个嵌入式工具。Beckett 的选择是采用规模较小的通用反思接口，覆盖整个引擎，提供写入前验证、支持两种语言、兼容 4.2+，并且免费版就能让 AI 看到你的游戏*。*

使用

1. 从编辑器安装。 在 Godot 中，打开 Asset Store 标签页（4.7 之前为 AssetLib），搜索 "Beckett"，然后安装（Asset Store 列表，Asset Library #5296）。或者手动将 addons/beckett/ 复制到项目中。
2. 在 Project → Project Settings → Plugins 中启用 Beckett（适用于 Godot 4.2+，推荐 4.4+；已在 4.4.1 上通过 CI 验证，并在 Windows、macOS 和 Linux 上通过 4.6.3 和 4.7.2 验证）。启用后会自动启动服务并写入 .mcp.json。（退出选项：beckett/autostart=false、beckett/auto_write_client_config=false。其他选项：BECKETT_PORT 默认值为 8770、BECKETT_TOKEN、BECKETT_READONLY=1、BECKETT_ALLOWLIST、BECKETT_CONFIRM_DESTRUCTIVE=1。面板中有 Start/Stop 按钮。）
3. 连接客户端。对于 Claude Code，只需在项目中运行 claude；自动写入的 .mcp.json 会完成连接配置（/mcp → beckett）。对于 Cursor/其他客户端，请连接到 http://127.0.0.1:8770/mcp（Streamable HTTP），或按下面板中的 Connect Detected Clients 按钮。请参阅 INSTALL.md。

状态

这是免费、采用 MIT 许可证的 Lite 版本，包含 检查 → 编写 → 运行 → 查看 核心功能：反射/发现、用于 GDScript 和 C# 的场景与脚本编写（含 build_csharp 编译检查）、信号、资源创建/分配、文件和项目设置、运行 → 等待 → logs_read 开发循环，以及让 AI 看到运行中游戏的运行时观察工具（screenshot、get_remote_tree、实时节点状态、性能监视器、game_logs），还有 Resources + Prompts + dock panel。**56 个工具。**已在 Godot 4.4.1、4.6.2 和 4.7 上进行实时构建和验证（无头编辑器 + 真实 HTTP MCP 客户端），并在每次推送时通过 Windows、Linux 和 macOS 上的 CI 测试。

Full 版本增加了由 Agent 驱动的游戏测试层（AI 操控输入、点击 2D/3D 和 UI，并断言测试结果）：测试运行器（test_run）、动画工具（animation_manage）、scatter_nodes、后台导出任务、全项目分析，以及 46 个内置技能包。它可以对运行中的游戏进行游戏测试。

许可证

Lite 版本 — MIT（本仓库）。免费开源：可使用、分叉并发布。请参阅 LICENSE。

Full 版本（Agent 驱动的游戏测试层、后台导出任务和技能包）是单独的商业产品——一次性购买，终身更新。

---

Beckett 是第三方工具，与 Godot Foundation 无关联，也未获其认可。“Godot”是 Godot Foundation 的商标。