内容
# Godot 代理循环
**构建它。玩它。证明它。**
适用于 Godot 4 的 MCP 自动化循环。
[](https://www.npmjs.com/package/@beremaran/godot-agent-loop)
[](https://github.com/beremaran/godot-agent-loop/actions/workflows/godot-integration.yml)
<!-- generated-coverage-badge:start -->
[](docs/coverage/coverage-report.md)
<!-- generated-coverage-badge:end -->
[](https://modelcontextprotocol.io/introduction)
[](https://godotengine.org)
[](LICENSE)
其他集成提供给代理工具。Godot 代理循环为它们提供了一个经过测试的反馈循环，用于编写、运行、观察、测试和独立验证 Godot 游戏：
```text
作者 → 验证 → 运行 → 观察 → 测试 → 验证 → 完善
```
[](assets/demo/godot-agent-loop-launch.mp4)
<img src="assets/demo/launch-playing.png" alt="代理构建的游戏正在播放" width="32%"> <img src="assets/demo/launch-win.png" alt="胜利屏幕" width="32%"> <img src="assets/demo/launch-lose.png" alt="失败屏幕" width="32%">
[观看 65 秒演示](assets/demo/godot-agent-loop-launch.mp4) ·
[阅读确切的运行证据](docs/launch/launch-evidence.md) ·
[检查生成的项目](examples/launch-demo)
## 快速入门
```bash
claude mcp add godot-agent-loop -- npx -y @beremaran/godot-agent-loop
```
然后将代理指向项目目录—or 空目录—and 描述可玩的结果。默认的 `core` 界面保留在生成的[工具表面预算](docs/coverage/tool-surface.json)内。使用只读的 `godot_catalog` 查找和检查隐藏功能，然后使用 `godot_call` 执行它。运行时注入是暂时的；观察到的项目可以使用可选的持久编辑器插件。
使用 Cline、Cursor 或其他 MCP 客户端？请参阅[配置](#configuration)。
## 声明前
- 每个当前工具和公共操作都跟踪到源代码派生的[覆盖率报告](docs/coverage/coverage-report.md)中的测试解析；其计数和表面大小是生成的，而不是复制到文档中。
- 完整的串行真实 Godot 矩阵在 CI 中强制执行。
- 冷启动代理构建并独立验证了一个可玩的胜/负游戏，耗时不到 7 分钟，使用 103 次 MCP 调用和没有内置工具；请参阅[启动证据](docs/launch/launch-evidence.md)和[确定性验收记录](docs/golden-agent-acceptance.md)。
- 特权反射、代码执行和网络组默认被拒绝，编辑器提供一个人类 **暂停代理** 控制。
支持故意有界：Godot 4.7 既是兼容性底线，也是主要目标。编辑器附件在 Linux CI 和头部 macOS 4.7.1 验收运行中得到验证；Windows 保留文档化的可移植验收路径，但不声明编辑器 UI 声明。完整的调试器自动化、本地扩展构建和无边界引擎控制不被声明。详细信息请参阅[验证的支持边界](#verified-support-boundary)。
## 亮点
- **有或无编辑器的作者** — 安全地附加到正常打开的项目以进行不可撤销的场景/资源事务，或保留分离和 CI 编写，并具有明确的同步元数据。
- **运行和观察** — 启动游戏，捕获日志和错误，增量截图，并使用基线、掩码和保留差异运行视觉回归比较。
- **像玩家一样测试** — 鼠标、键盘、按键保持、拖动、滚动、触摸和游戏手柄输入针对正在运行的游戏。
- **独立验证** — 无头 GDScript 验证 (`validate_script`、`validate_scripts`)，原生/GUT/GdUnit4 测试运行器 (`run_project_tests`)，有界运行时证据 (`verify_project`)，导出检查 (`verify_export_readiness`) 和静态完整性分析 (`analyze_project_integrity`)。
- **进入运行时** — 检查和操作任何节点、信号、动画、物理身体或 UI 控制，通过 100 多个运行时工具；`game_eval` 使用 `await` 支持执行 GDScript（特权，，需选择加入）。
- **驱动编辑器** — `editor_session ensure` 发现匹配的项目，编辑器路由工具和 `editor_transaction` 通过 `EditorUndoRedoManager` 应用可逆编辑，而代理活动停靠器重放有界相关跟踪，具有人类 **暂停代理** 锁定。
- **.NET / C# 支持** — 为 C# 项目构建脚手架，匹配到已安装的 Godot 的 `Godot.NET.Sdk`，生成惯用脚本，并通过 `verify_dotnet_project` 恢复/构建/运行。
- **设计有界** — 确定的分页和大响应大小上限，结构化相关诊断和最小特权安全默认值。
## 工具目录
完整的库存—运行时交互、场景编写、项目管理、验证、2D/3D 渲染、音频、UI、联网等—位于[docs/tools.md](docs/tools.md)。每个工具的验证状态和测试参考都位于生成的[覆盖率报告](docs/coverage/coverage-report.md)中。
## 需求
- [Godot 引擎](https://godotengine.org/download) 4.7 或更高版本
- （可选）[.NET SDK](https://dotnet.microsoft.com/download) 8.0+ 和 Godot .NET（C#）构建，仅当使用 `create_project` 的 `dotnet: true` 标志或 `create_csharp_script` 时需要
- [Node.js](https://nodejs.org/) >= 22.0.0（活动 LTS）
- 支持 MCP 的 AI 助手（Claude Code、Cline、Cursor 等）
### Godot 兼容性政策
开发针对最新的稳定 Godot 版本。Godot 4.7 是当前的兼容性底线和主要目标，CI 涵盖该确切版本。底线可能会在阻碍有用功能或产生有意义的维护成本时提高。在这种情况下，最后的兼容版本仍然可用，并且只有在用户需求证明维护它时，才会创建旧版本维护分支。该分支将仅接收关键修复而不是新功能。
### 验证的支持边界
| 区域 | 状态 | 证据或限制 |
| --- | --- | --- |
| Linux headed（桌面或 Xvfb），Godot 4.7 | 在 CI 中验证 | 在 Xvfb 下的完整 MCP E2E，直接运行时，子进程操作和严格的脚本解析 |
| GDScript 项目和运行游戏工作流 | 为广告工具验证 | 请参阅生成的[覆盖率报告](docs/coverage/coverage-report.md) |
| 特权运行时命令 | 仅需选择加入 | 默认禁用；用于受信任的本地主机开发 |
| Godot .NET/C# | 脚手架、编译和编辑器加载验证 | Godot .NET 4.7 和 .NET SDK 8 |
| Linux 导出 | 发布/调试模板导出和烟雾运行验证 | Godot 4.7 安装的模板；其他目标未声明 |
| 渲染和截图 | 需要头部渲染上下文 | Linux 软件渲染上的兼容性和 Forward+；无显示的会话快速失败，并具有桌面/Xvfb 补救 |
| Windows | 可移植验收验证 | Godot 4.7 进程、Unicode 路径、运行时输入、窗口查询和拆除工作流；编辑器 UI、渲染和导出未声明 |
| macOS | 可移植验收和附加编辑器工作流验证 | Godot 4.7.1 头部重放打开 Godot，通常重新连接 MCP，作者和同步而无需焦点切换/手动重新加载，练习不可撤销的交易，并清理发现记录；请参阅[交互验收记录](docs/coverage/interactive-golden-agent-run.json) |
| 编辑器状态和撤销/重做桥 | 在 Linux CI 和头部 macOS 4.7.1 上验证 | 协议 2 使用私有项目发现、`EditorInterface` 和 `EditorUndoRedoManager`；Windows 编辑器 UI 仍在声明边界之外 |
| 完整的调试器控制 | 未声明 | 断点、堆栈检查和帧本地评估仍在支持边界之外 |
| 分析器、泄漏、资产、本地化和可访问性审计 | 在 MCP E2E 中验证 | `game_performance` 和 `analyze_project_integrity` 返回有界的实时/静态证据；原生扩展构建仍不受支持 |
| GDExtension 构建 | 未声明 | `analyze_project_integrity` 检查声明和库而不调用任意原生工具链 |
## 配置
[快速入门](#quickstart) `npx` 命令是大多数设置所需的一切。下面的部分涵盖其他客户端和源代码 checkout。
### 交互式编辑器设置
对于用户监视的项目，请复制 [`addons/godot_agent_loop`](addons/godot_agent_loop) 到项目中的相同路径，启用 **Godot 代理循环** 在 **项目 > 项目设置 > 插件** 下，然后重启 Godot 一次。此后，Godot 可以正常打开；`editor_session` 在不启动重复的情况下发现匹配的项目。
该插件发布了一个私有、未跟踪的记录在 `.godot/godot_agent_loop/editor-session.json`，每个编辑器启动时都有一个新的令牌和临时环回端口。该令牌从未返回或记录。多个编辑器通过规范的项目路径路由。要卸载，请禁用插件，关闭 Godot，删除 `addons/godot_agent_loop`，并可选地删除一个陈旧的 `.godot/godot_agent_loop` 目录。MCP 清理仅删除其自己的未修改的瞬时桥，而不触及这个持久的插件。
已经启动的编辑器如果没有启用兼容的插件，则无法安全地接收新的 `EditorPlugin`。一次安装/启用并重启。有关状态、协议迁移、无冲突恢复和回退语义，请参阅[交互架构](docs/architecture/editor-interaction.md)。
### 可移植代理包
存储库提供了一个中立的包，启动匹配的 npm MCP 服务器，并为 Claude Code、Codex、OpenCode 和 Pi 提供相同的构建、调试、验证和发货技能。对于 Claude Code：
```text
/plugin marketplace add beremaran/godot-agent-loop
/plugin install godot-agent-loop@godot-agent-loop
```
对于本地 checkout，请使用 `claude --plugin-dir ./agent-plugin`。请参阅[可移植代理包指南](docs/agent-plugin.md)，了解验证的 Claude Code、Codex、OpenCode 和 Pi 安装路径。
### MCP 客户端配置
<details>
<summary>Claude Code（手动设置）</summary>
将以下内容添加到您的 Claude Code MCP 设置中：
```json
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@beremaran/godot-agent-loop"],
"env": {
"GODOT_PATH": "/path/to/godot",
"GODOT_MCP_AUTHORING_MODE": "headless",
"DEBUG": "true"
}
}
}
}
```
</details>
<details>
<summary>Cline（VS Code）</summary>
将以下内容添加到您的 Cline MCP 设置（`cline_mcp_settings.json`）：
```json
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@beremaran/godot-agent-loop"],
"disabled": false
}
}
}
```
</details>
<details>
<summary>Cursor</summary>
在您的项目中创建 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@beremaran/godot-agent-loop"]
}
}
}
```
</details>
对于源代码 checkout，请使用 `node` 作为可执行文件，并将构建的服务器路径作为单独的参数传递：
```json
{
"command": "node",
"args": ["/absolute/path/to/godot-agent-loop/build/index.js"]
}
```
### 从源代码安装
```bash
git clone https://github.com/beremaran/godot-agent-loop.git
cd godot-agent-loop
npm install
npm run build
```
## 运行时工具设置
通过 `run_project` 启动游戏时不需要设置：服务器通过生成一个 `override.cfg`（Godot 在启动时将其合并到 `project.godot` 上）并将运行时脚本复制到项目中，然后在 `stop_project`、游戏退出或服务器关闭时删除它们。`project.godot` 永远不会被修改。如果早期服务器崩溃或被杀死而没有清理，下一个服务器检测并删除残留的文件；您自己管理的安装（在 `project.godot` 中声明）永远不会被触及。
要运行交互服务器而无需 `run_project`，请复制 `build/scripts/mcp_interaction_server.gd` 到您的项目，并将其注册为 autoload：
1. 将 `build/scripts/mcp_interaction_server.gd` 复制到您的项目的脚本文件夹
2. 在 Godot 中：**项目 > 项目设置 > 自动加载**
3. 添加脚本，名称为 `McpInteractionServer`
服务器监听 `127.0.0.1:9090`。每个 MCP 服务器启动都会生成一个加密的运行时密钥，它只传递给 Godot 子进程，并在能力协商期间进行身份验证，然后再接受任何运行时命令。手动管理的运行时应设置相同的 `GODOT_MCP_RUNTIME_SECRET` 值；如果省略，则保留旧的不安全行为，仅适用于受信任的机器。
执行任意 GDScript、调用任意节点属性或方法、变异脚本、调用多人游戏对等体或建立 HTTP/WebSocket 连接的命令默认情况下仍然禁用。仅当使用 `GODOT_MCP_PRIVILEGED_GROUPS` 授予所需的组时才授予：`reflection` 启用任意属性/方法访问，`code-execution` 启用评估/脚本控制，而 `network` 启用 RPC、HTTP 和 WebSocket。旧的 `GODOT_MCP_ALLOW_PRIVILEGED_COMMANDS=true` 授予所有三个组。请仅在受信任的本地主机开发工作流中使用它们。身份验证失败/成功发出一个包含事件名称、运行时组件、数字会话 ID 和时间戳的结构化审计事件。
## 环境变量
| 变量 | 描述 |
| ---------- | ------------- |
| `GODOT_PATH` | Godot 可执行文件的路径（覆盖自动检测） |
| `DEBUG` | 设置为 `"true"` 以进行详细的服务器端日志记录。这也以 `--debug-godot` 运行无头操作脚本，这会记录诊断信息并在项目中写入一个临时写访问探测文件（再次删除）。参数值按类型和大小汇总在日志中，从不打印。 |
| `GODOT_MCP_ALLOWED_DIRS` | 可选。限制 `run_project` 到这些根目录下的项目（`;`、`，` 或 `:` 分隔）。当未设置时，允许任何项目路径。 |
| `GODOT_MCP_AUTHORING_MODE` | 可选，默认为 `persistent`。`persistent` 重用头部 Godot 进程，避免每个场景或资源调用的启动成本。`headless` 不打开辅助窗口，而是通过其声明的单次 `--headless` 子进程回退运行。这不会更改头部 `run_project` 路径。 |
| `GODOT_MCP_RUNTIME_SECRET` | 可选的显式共享运行时密钥。如果省略，MCP 服务器会生成一个新鲜的 256 位值，并仅将其传递到 Godot 进程。它被设置为相同的手动设置值，仅当连接到单独启动的运行时。 |
| `GODOT_MCP_EDITOR_START_PAUSED` | 可选，默认为 `false`。启动编辑器插件的协作锁以人类编辑模式，因此在 **Resume Agent** 被按下之前拒绝变异的 MCP 工具。 |
| `GODOT_MCP_TOOL_SURFACE` | 可选，默认为 `core`。`compact` 是 `core` 的兼容别名；`full` 广告完整的静态目录。未知值被拒绝。使用 `godot_catalog` 加 `godot_call` 来查找隐藏的工具；组合的 `godot_tools` 别名在 1.x 发布线中已弃用。 |
| `GODOT_MCP_LEGACY_JSON_TEXT` | 可选，默认为 `true`。设置为 `false` 以使客户端读取 MCP `structuredContent` 以省略额外的兼容性 JSON 文本块并减少重复输出。捆绑适配器将其设置为 `false`。 |
| `GODOT_MCP_PRIVILEGED_GROUPS` | 可选的逗号分隔的最小特权授予：`reflection`、`code-execution` 和/或 `network`。默认情况下，所有这些都被拒绝。 |
### 结构化运行时证据
在 `DEBUG=true` 时，MCP 服务器将 JSON 请求生命周期事件输出到 stderr。Godot 运行时输出匹配的事件到其捕获的 stdout。两者都使用内部的 `mcp_<number>` 相关 ID 和受控事件字段；参数、响应值、密钥、源、URL和引擎错误永远不会被复制到日志中。稳定的JSON-RPC错误代码仍然是可用的机器可读故障分类。大型JSON响应大小上限为8 MiB，截图另外强制执行像素和6 MiB PNG限制，短寿命的子进程/导入命令捕获的输出大小上限为16 MiB。限制失败是明确的；调用者可以缩小资源/导入查询以避免接收部分未标记的数据。
## 架构
服务器使用三种有限的执行路径：
1. **场景和资源创作** - `GODOT_MCP_AUTHORING_MODE=persistent` 重用了一个有头、确定性的 Godot 主循环，避免了每次编辑的引擎启动成本。`GODOT_MCP_AUTHORING_MODE=headless` 不创建辅助窗口，并将每个调用发送到其声明的单次 `--headless` 子进程备用。
2. **运行游戏套接字** - `run_project` 启动用户的游戏，并通过 `override.cfg` 注入身份验证的 `mcp_interaction_server.gd` 自动加载，以实现高保真运行时交互。
3. **其他单次子进程工作** - 验证、导入和导出操作可能会调用 Godot 一次然后退出。无头创作并不使视觉工作无显示：运行游戏、截图和视觉检查仍然需要桌面显示、Xvfb 或另一个可达的渲染上下文。
### 源代码布局
| 路径 | 描述 |
| ------ | ------------- |
| `src/index.ts` | MCP 服务器入口点 |
| `src/tool-definitions.ts` | 工具名称和 JSON 模式 |
| `src/tool-manifest.ts` | 每个工具的领域、后端和操作声明 |
| `src/tool-surface.ts` | 审查的核心成员资格、发现排名、兼容性模式和生成的大小预算 |
| `src/tool-handlers/` | 生命周期、项目和游戏处理程序实现 |
| `src/scripts/godot_operations.gd` | 持久和单次 GDScript 操作运行器 |
| `src/scripts/mcp_interaction_server.gd` | TCP 交互服务器自动加载 |
| `tests/` | Vitest 单元测试、E2E 和 Godot 测试套件 |
## 测试
该项目使用 Vitest 以及直接的 Godot 和完整的 MCP-to-Godot 测试套件。从源代码导出的工具、操作、命令和测试套件清单发布在 [覆盖率报告](docs/coverage/coverage-report.md) 中。
```bash
npm run check # TypeScript 测试、lint、构建和覆盖率检查
npm run test:e2e # 通过真实客户端和 Godot 构建的 MCP 服务器
npm run test:golden-agent # 冷代理游戏构建验收门控
npm run test:godot # 严格解析、子进程操作、运行时协议
npm run test:watch # 监视模式
```
已发布的构建、调试、验证和发布技能场景版本存放在 `evals/` 下。它们的提交状态故意设置为 `not_run`，直到故意运行当前模型的客户端记录版本化的输入和模式验证的指标；确定性的黄金重放不能代替该运行。
## 示例提示
```text
"运行我的 Godot 项目并检查错误"
"创建一个名为 'MyGame' 的新 Godot 项目并编写一个玩家脚本"
"读取 test_level.tscn 场景并显示节点树"
"在运行游戏之前检查所有更改的 GDScript 文件的语法错误"
"按住 W 键 2 秒以测试行走"
"暂停游戏并截图"
"获取性能指标 - 我的 FPS 和绘制调用次数是多少？"
"将玩家的生命值设置为 100"
"将敌人的 'died' 信号连接到游戏管理器的 'on_enemy_died' 方法"
"创建一个新的 C# (.NET) Godot 项目并添加一个 CharacterBody2D 脚本"
```
## 社区
- [贡献指南](CONTRIBUTING.md) — 开发工作流、检查和 PR 期望
- [安全策略](SECURITY.md) — 如何报告漏洞
- [行为准则](CODE_OF_CONDUCT.md)
- [变更日志](CHANGELOG.md) 和 [发布说明](docs/releases)
- [问题](https://github.com/beremaran/godot-agent-loop/issues) — 错误报告和功能请求
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 血统
- **原始项目：** [godot-mcp](https://github.com/Coding-Solo/godot-mcp) 由 [Solomon Elias (Coding-Solo)](https://github.com/Coding-Solo) 提供，它提供了基础的 TypeScript MCP 服务器、无头 GDScript 操作和 TCP 运行时交互架构。
- **继承自：** [Tugcan Topaloglu](https://github.com/tugcantopaloglu) 的 [godot-mcp](https://github.com/tugcantopaloglu/godot-mcp)，它在原始项目的基础上扩展了网络、3D/2D 渲染、UI 控件、音频、动画、文件 I/O、运行时代码执行、项目创建和物理，同时保留了 MIT 许可证。
- **Godot 代理循环：** 由 [Berke Arslan](https://github.com/beremaran) 维护和大幅扩展，保留了完整的 Git 历史记录和每个继承的 MIT 通知。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器