Godot Forge

Godot Forge

适用于 Godot 4 的 MCP 服务。测试运行器、API 文档、脚本分析等。

AI 编码助手在结构上不擅长处理 GDScript。由于训练数据偏向 Godot 3，模型会臆造已弃用的 API（用 yield 代替 await、用 KinematicBody 代替 CharacterBody3D、用 export var 代替 @export var）。Godot Forge 可以解决这个问题。

8 个工具。零配置。兼容所有支持 MCP 的 IDE。

安装

npx -y godot-forge

就这么简单。Godot Forge 会自动检测 Godot 二进制文件（Steam、Homebrew、直接下载），并自动查找 project.godot。

添加到 IDE

claude mcp add godot-forge -- npx -y godot-forge

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "servers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "context_servers": {
    "godot-forge": {
      "command": {
        "path": "npx",
        "args": ["-y", "godot-forge"]
      }
    }
  }
}

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

工具

提示

8 个工具中有 6 个无需安装 Godot 即可使用。只有运行测试、启动项目和截屏需要 Godot 二进制文件。

功能

测试运行器

自动检测 GUT 和 GdUnit4。返回包含通过/失败数量、失败详情（包括文件路径和行号）的结构化 JSON。支持按脚本、方法或内部类筛选。

Ask your AI: "Run the water profile tests"
→ { total: 5, passed: 5, failed: 0, duration_ms: 462 }

Godot 3→4 迁移映射

AI 写出有问题的 GDScript 的头号原因。当 AI 查询已弃用的 API 时，它能立即获取正确的 Godot 4 等效项（30 多项映射，涵盖类、方法、语法和常量）。

Query: "KinematicBody"  →  "Renamed to CharacterBody3D in Godot 4"
Query: "yield"          →  "yield(obj, 'signal') → await obj.signal"
Query: "instance()"     →  "instance() → instantiate()"

脚本分析：10 个常见问题

检测游戏开发中实际遇到的每个常见问题：

场景分析

解析 .tscn 和 .tres 文件。检测深层嵌套（>8 层）、过大的场景（>100 个节点）、缺失的脚本引用、.tres 中的 preload()、整数资源 ID 等。

LSP 诊断

连接到 Godot 内置的语言服务器（编辑器打开时会自动运行）。返回真实的编译器错误和警告（不靠猜测）。

说明

需要运行 Godot 编辑器并打开项目。其他所有工具均可在编辑器未运行时使用。

截图捕获

将游戏视口捕获为 PNG 图像。加载项目的主场景（或指定场景），等待渲染完成，并以 base64 格式返回截图，供 AI 查看。

配置

Godot 二进制文件

按以下顺序自动检测：

1. GODOT_PATH 环境变量
2. PATH 中的 godot / godot4
3. Steam 安装（macOS、Windows、Linux）
4. 平台默认位置（/Applications/Godot.app、Homebrew、Scoop、Flatpak、Snap 等）

手动指定：

export GODOT_PATH="/path/to/godot"

完整的搜索路径列表请参阅 Godot 检测。

项目目录

从当前目录开始向上查找 project.godot，自动检测项目目录。手动指定：

npx godot-forge --project /path/to/godot/project

要求

• Node.js 18+：用于执行 npx
• Godot 4.x：自动检测（8 个工具中有 6 个可选）
• 任意兼容 MCP 的 IDE：Claude Code、Cursor、VS Code、Windsurf、Zed 等更多

设计原则

• 关注结果，而非操作：每个工具都提供完整结果，而不是对原始 API 的简单封装
• 8 个精选工具：避免 93 个工具导致的上下文臃肿（为何这很重要）
• 渐进式呈现：先给出摘要，再按需展示详情
• 使用 spawn()，而非 exec()：避免命令注入和 Windows 引号错误
• 提供可操作的错误信息：每条错误信息都包含 AI 可执行的建议
• 跨平台：macOS、Windows、Linux。支持 Steam 安装和非 Steam 安装。

贡献

欢迎贡献！请参阅贡献指南。

• 错误报告：提交问题
• 功能请求：发起讨论
• 拉取请求：Fork、创建分支、测试并提交 PR

开发

git clone https://github.com/gregario/godot-forge.git
cd godot-forge
npm install
npm run build
npm test        # 74 tests across 12 test files

本地运行

# Point your IDE at the local build
claude mcp add godot-forge-dev -- node /path/to/godot-forge/dist/index.js

路线图

请参阅 ROADMAP.md 了解计划中的功能。

阶段 2：输入模拟、运行时场景树检查、性能分析、着色器验证、导出/CI 流水线。

许可证

MIT