gopeak

GoPeak

🌐 语言：English | 한국어 | 日本語 | Deutsch | Português | 简体中文

GoPeak 是一款面向 Godot 的 MCP 服务，可让 AI 助手端到端地运行、检查、修改和调试真实项目。

英文版是唯一权威源。其他语言的 README 是简要概览，内容可能落后于 README.md。

Discord 社区聊天暂时不可用，邀请链接正在更新。期间请使用 GitHub Discussions：https://github.com/HaD0Yun/Gopeak-godot-mcp/discussions

---

快速开始（3 分钟）

要求

• Godot 4.x
• Node.js 18+
• 兼容 MCP 的客户端（Claude Desktop、Cursor、Cline、OpenCode 等）

1) 运行 GoPeak

npx -y gopeak

或全局安装：

npm install -g gopeak
gopeak

更新通知的可选 shell 钩子现已改为选择加入：

gopeak setup

只有在明确运行 gopeak setup 时，它才会修改受支持的 bash/zsh rc 文件。npm install 不再自动安装 shell 钩子。

2) 添加 MCP 客户端配置

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gopeak"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

GOPEAK_TOOL_PROFILE=compact 是默认设置。它提供可信的核心功能，并按需启用动态工具组，在降低 token 用量的同时，明确标示实验性或依赖环境的功能。

3) 可尝试的首批提示词

• “列出 /your/projects 中的 Godot 项目并显示项目信息。”
• “创建以 CharacterBody2D 为根节点的 scenes/Player.tscn，并添加移动脚本。”
• “运行项目，获取调试输出，然后修复最上方的错误。”

---

为什么选择 GoPeak

• 真实项目反馈循环：运行游戏、检查日志，并在上下文中修复问题。
• 可信的 Godot 4 工作流工具：涵盖项目发现、场景/脚本/资源编辑、运行时/LSP/DAP 集成、测试和资源工作流。
• 默认节省 token：精简的核心功能加上动态工具组。只激活所需的功能组，而无需加载完整的旧版功能。
• 带有明确成熟度标签的动态工具组：使用 tool.catalog 搜索即可自动激活匹配的工具组，也可以使用 tool.groups 手动激活。
• 深度集成 Godot，并设有配置门槛：ClassDB 查询、运行时检查、调试器钩子，以及基于桥接的场景/资源编辑，都会明确说明对插件、编辑器、LSP、DAP 或运行时的要求。

最适合

• 希望借助 AI 快速推进的个人/独立开发者
• 需要 AI 基于实际项目/运行时状态工作的团队
• 以调试为主的工作流（断点、堆栈跟踪、实时运行时检查）

---

工具暴露模式（重要）

GoPeak 支持三种暴露配置：

• compact（默认）：可信的核心工具，以及按需激活的动态工具组。
• full：暴露完整的旧版工具列表，用于兼容和审计工作。
• legacy：与 full 暴露行为相同，适用于较旧的配置。

可通过以下任一变量进行配置：

• GOPEAK_TOOL_PROFILE
• MCP_TOOL_PROFILE（备用别名）

动态工具组（紧凑模式）

在 compact 模式下，其他工具会组织成动态组，并在需要时自动激活。在每个组都有 Godot 4 fixture 证据之前，成熟度标签会有意保持保守：

组	成熟度	描述 / 设置门槛
scene_advanced	audit-required	复制、重新设置节点父级、加载精灵；在 Godot 4 fixture 中验证场景所有权/持久性后，才能将其视为可信。
uid	audit-required	资源 UID 管理；根据 Godot 版本和资源保存/加载证据设置行为门槛。
import_export	audit-required	导入管线、重新导入、验证项目；需要针对导入设置和导出命令构造进行 fixture 检查。
autoload	audit-required	Autoload 单例、主场景；需要往返验证项目设置。
signal	audit-required	断开信号、列出连接；需要往返验证信号。
runtime	optional-runtime	实时场景检查、运行时属性、指标；需要运行时 addon/socket。
resource	audit-required	创建/修改材质、着色器、资源；需要进行资源保存/加载 fixture 检查。
animation	audit-required	动画、轨道、动画树、状态机；需要进行已保存场景/资源 fixture 检查。
plugin	optional-editor	启用/禁用/列出编辑器插件；需要编辑器插件可用。
input	audit-required	输入操作映射；需要往返验证项目设置。
tilemap	audit-required	TileSet 和 TileMap 单元格绘制；在将其提升为可信之前，必须考虑 Godot 4.3+ 的 TileMapLayer 行为。
audio	audit-required	音频总线、效果、音量；需要进行总线布局 fixture 检查。
navigation	audit-required	导航区域和 Agent；需要进行已保存场景/资源 fixture 检查。
theme_ui	audit-required	主题颜色、字体大小、着色器；需要进行资源保存/加载 fixture 检查。
asset_store	optional-network	搜索/下载外部 CC0 资源；需要网络/提供方可用，并应保持为可选项。
testing	optional-runtime	截图、视口捕获、输入注入；需要运行时 addon/编辑器可用。
dx_tools	audit-required	错误日志、项目健康状况、查找用法、脚手架；需要确定性的静态 fixture 检查。
intent_tracking	workflow-layer	意图捕获、决策日志、交接简报；这不是 Godot 引擎原语，应保持为选择启用/限定在工作流范围内。
class_advanced	trusted-static	类继承检查；根据 ClassDB/静态证据进行验证。
lsp	optional-lsp	GDScript 补全、悬停、符号；需要 Godot LSP 在端口 6005 上运行。
dap	optional-dap	断点、单步执行、堆栈跟踪；需要 Godot DAP 在端口 6006 上运行。
version_gate	audit-required	版本验证和补丁验证；需要明确的版本 fixture 证据。

工作原理：

1. 通过目录自动激活：使用 tool.catalog 搜索时，匹配的组会自动激活。

   “使用 tool.catalog 搜索 animation，并显示相关工具。”

2. 手动激活：使用 tool.groups 直接激活一个组。

   “使用 tool.groups 激活 dap 组以进行调试。”

3. 停用：完成后移除组，以减少上下文。

   “使用 tool.groups 重置所有已激活的组。”

服务端会发送 notifications/tools/list_changed，使 MCP 客户端（Claude Code、Claude Desktop）自动刷新工具列表。 如果你的 MCP 客户端会积极缓存工具，且激活后没有刷新，请重新连接客户端，或直接调用一次新激活的工具，以强制执行一次新的 tools/list 往返。

场景工具的类型化属性值

由 Bridge 驱动的场景工具（add_node、set_node_properties）现在会为 position 和 scale 等类型化属性，将 { "x": 100, "y": 200 } 和 [100, 200] 等常见向量数据转换为相应类型。带类型标签的值仍是跨工具使用时最安全的形式：

{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

内部无头序列化器使用 _type，但 MCP 调用方需要指定跨工具通用的 Godot 值标签时，应优先使用 type。

不必担心令牌用量

GoPeak 使用基于游标的分页来处理 tools/list——即使在 full 配置中，工具也会按页（默认每页 33 个）发送，而不是一次性倾倒整个旧版定义集。只有在需要时，AI 客户端才会获取下一页。

使用 GOPEAK_TOOLS_PAGE_SIZE 设置每页大小：

{
  "env": {
    "GOPEAK_TOOLS_PAGE_SIZE": "25"
  }
}

---

安装选项

A）推荐：npx

npx -y gopeak

B）全局安装

npm install -g gopeak
gopeak

仍可通过以下方式选择安装用于更新通知的 Shell 钩子：

gopeak setup

C）从源代码安装

git clone https://github.com/HaD0Yun/Gopeak-godot-mcp.git
cd godot-mcp
npm install
npm run build
node build/index.js

GoPeak 还提供两个 CLI 二进制名称：

• gopeak
• godot-mcp

---

文档

• 文档索引
• 架构
• 平台路线图
• Unity-MCP 基准测试计划
• 发布流程

CI

GitHub Actions 会在推送或 PR 时运行，并执行：

1. npm run build
2. npx tsc --noEmit
3. npm run smoke

提交 PR 前，请在本地运行相同的检查：

npm run ci
npm run test:dynamic-groups
npm run test:integration

---

版本管理与发布

使用内置的版本递增脚本，让 package.json 和 server.json 保持同步：

node scripts/bump-version.mjs patch
node scripts/bump-version.mjs minor --dry-run

完整的发布检查清单：docs/release-process.md。

---

插件（推荐）

自动重新加载 + 编辑器 Bridge + 运行时插件安装程序

在 Godot 项目文件夹中安装：

curl -sL https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.sh | bash

PowerShell：

iwr https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex

然后在 项目设置 → 插件 中启用插件（尤其是 godot_mcp_editor，它用于由 Bridge 驱动的场景/资源工具）。

---

核心功能

这些功能按工作流价值分组。可选的运行时/LSP/DAP/网络分组需要先完成相应的设置步骤才能使用；需要审计的分组只有在有夹具证据后才应推广。

• 项目控制：启动编辑器、运行/停止项目、捕获调试输出
• 场景编辑：创建场景、添加/删除/重新设定节点父级、编辑属性
• 脚本工作流：创建/修改脚本、检查脚本结构
• 资源：创建/修改资源、材质、着色器、图块集
• 信号/动画：连接信号、构建动画/轨道/状态机
• 运行时工具：检查实时树、设置属性、调用方法、查看指标（需要运行时插件/套接字）
• LSP + DAP：诊断/补全/悬停 + 断点/单步/堆栈跟踪（需要 Godot LSP/DAP 端口）
• 输入 + 截图：注入键盘/鼠标/动作输入并捕获视口（需要配置运行时/编辑器 Bridge）
• 资源库：搜索/获取 CC0 资源（可选的网络/提供方工作流）

工具类别（示例）

区域	示例
项目	project.list、project.info、editor.run
场景/节点	scene.create、scene.node.add、set_node_properties
脚本	script.create、script.modify、script.info
运行时	runtime.status、inspect_runtime_tree、call_runtime_method
LSP/DAP	lsp.diagnostics、lsp_get_hover、dap_set_breakpoint、dap.output
输入/视觉	inject_key、inject_mouse_click、capture_screenshot

---

项目可视化工具

使用 visualizer.map（旧版名称为 map_project）可视化整个项目架构。脚本会按文件夹结构分组，并归入不同的颜色类别。

---

快速提示词示例

构建

• “创建一个 Player 场景，包含 CharacterBody2D、Sprite2D、CollisionShape2D 和基础移动脚本。”
• “添加敌人生成器场景，并将生成信号连接到 GameManager。”

调试

• “运行项目，收集错误，并自动修复最重要的 3 个问题。”
• “在 scripts/player.gd:42 设置断点，继续执行，并在断点命中时显示堆栈跟踪。”

运行时测试

• “按下 ui_accept，将鼠标移动到 (400, 300)，单击，然后截取屏幕截图。”
• “检查实时场景树，并报告缺少脚本或引用无效的节点。”

发现与动态组

• “使用查询 tilemap 调用 tool.catalog，并列出最相关的工具。”
• “使用 tool.groups 激活 dap 工具组，以进行断点调试。”
• “使用 tool.catalog 搜索 import 查询以查找导入流水线工具，并运行最适合纹理设置的工具。”
• “使用 tool.groups 重置所有已激活的工具组，以减少上下文。”

---

迁移与弃用政策

GoPeak 将 compact 视为安全的默认配置，并将 full/legacy 视为兼容配置。今后任何隐藏、移除、重命名或 API 契约变更都必须包含：

1. 旧名称 → 新名称的映射，或明确说明没有替代项；
2. 受影响的配置（compact、full、legacy 或选择加入的工具组）；
3. 是否保留别名以及计划的移除时间窗口；
4. README/文档和发行说明更新；
5. 用于验证 tools/list 可见项和别名行为的命令；
6. 常见 Godot 工作流的迁移提示词示例。

当前兼容策略：继续支持旧版工具名称和 compact 别名。对于带有可选外部依赖的动态组（runtime、testing、lsp、dap、asset_store），文档应说明这些组需要选择加入/完成设置，而不应宣传为始终可用的核心功能。

技术参考

环境变量

名称	用途	默认值
GOPEAK_TOOL_PROFILE	工具可见配置：compact、full、legacy	compact
MCP_TOOL_PROFILE	后备配置环境变量别名	compact
GODOT_PATH	显式指定 Godot 可执行文件路径	自动检测
GODOT_BRIDGE_PORT	Bridge/Visualizer HTTP+WS 端口覆盖（别名：MCP_BRIDGE_PORT、GOPEAK_BRIDGE_PORT）	6505
DEBUG	启用服务调试日志（true/false）	false
LOG_MODE	记录模式：lite 或 full	lite
GOPEAK_TOOLS_PAGE_SIZE	每页 tools/list 的工具数（分页）	33
GOPEAK_BRIDGE_PORT	统一的 bridge/visualizer 服务端口	6505
GOPEAK_BRIDGE_HOST	bridge/visualizer 服务的绑定主机	127.0.0.1

端口

端口	服务
6505（默认）	统一的 Godot Bridge + Visualizer 服务（含 /health、/mcp），默认绑定到回环地址
6005	Godot LSP
6006	Godot DAP
7777	运行时插件命令套接字（仅运行时工具需要）

最小端口配置

• 仅核心编辑：bridge 端口（GODOT_BRIDGE_PORT，默认 6505）
• 核心功能 + 运行时操作（屏幕截图/输入/运行时检查）：bridge 端口 + 7777
• 完整调试 + 诊断：bridge 端口 + 6005 + 6006 + 7777

---

故障排除

• 找不到 Godot → 设置 GODOT_PATH
• 看不到 MCP 工具 → 重启 MCP 客户端
• 项目路径无效 → 确认 project.godot 存在
• 运行时工具无法使用 → 安装/启用运行时插件
• 需要的工具未显示 → 运行 tool.catalog 进行搜索并自动激活匹配的组，或使用 tool.groups 激活特定组
• get_editor_status 显示已断开，但 Godot 编辑器显示已连接 → 检查是否有其他 gopeak/MCP 服务实例已占用 bridge 端口 6505；状态载荷现在会报告启动错误，并建议停止重复的服务实例

---

文档与项目链接

• 架构（MCP 平台方向）
• 平台路线图（P1/P2/P3）
• 变更日志
• 路线图
• 贡献指南

---

许可证

MIT — 详见 LICENSE。

致谢

• 原始 MCP 服务由 Coding-Solo 开发
• GoPeak 增强功能由 HaD0Yun 开发
• 项目可视化工具的灵感来自 tomyud1/godot-mcp