AI导哈

资源UID生成工具

一个用于生成和管理Godot资源UID的插件和服务器工具，通过TCP通信与Godot编辑器实例交互。

  • by lpenguin
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 lpenguin/godot-mcp

使用说明

Godot资源UID MCP服务器和插件

一个包含Godot 4编辑器插件和TypeScript MCP（模型上下文协议）服务器的monorepo，允许AI代理生成和管理有效的Godot uid:// 通过TCP与正在运行的Godot编辑器实例通信。该系统智能地缓存资源路径的UID，并重用现有的UID。

📦 存储库结构

/
├── godot_plugin/       # Godot 4 Addon
│   └── addons/
│       └── lpenguin-mcp-server/
│           ├── plugin.cfg
│           └── mcp_bridge.gd
├── mcp_server/         # TypeScript MCP Server (Published to NPM)
│   ├── src/
│   ├── tests/
│   └── package.json
├── package.json        # Root workspace config
└── .github/workflows/  # Publishing Workflow

🚀 快速开始

1.安装Godot插件

  1. 复制 godot_plugin/addons/lpenguin-mcp-server/ 将文件夹放入Godot项目的 addons/ 目录
  2. 打开您的Godot项目
  3. 首选 项目>项目设置>插件
  4. 启用 MCP电桥 插件
  5. TCP服务器将在端口上自动启动 8085

2.使用MCP服务器

MCP服务器可以通过以下方式运行 npx 无需安装：

npx @lpenguin/godot-mcp

或者全局安装：

npm install -g @lpenguin/godot-mcp
godot-mcp

🔧 运作原理

Godot插件（TCP服务器）

Godot插件创建了一个TCP服务器，该服务器在端口8085上监听JSON命令：

请求格式：

{
  "command": "get_path_uid",
  "args": {
    "path": "res://scenes/player.tscn"
  }
}

响应格式：

{
  "status": "success",
  "uid": "uid://dmbxm1qp5555x"
}

该插件使用Godot的内置 ResourceUID 带智能缓存的API：

# Check if UID already exists for this path
if path_to_uid.has(path):
    return path_to_uid[path]  # Return cached UID
else:
    var cached_uid = ResourceUID.path_to_uid(path)
    if cached_uid != path:  # Path has existing UID
        return cached_uid
    else:  # Generate new UID
        var new_id = ResourceUID.create_id()
        var uid_string = ResourceUID.id_to_text(new_id)
        ResourceUID.add_id(new_id, path)
        path_to_uid[path] = uid_string
        return uid_string

MCP服务器（TCP客户端）

MCP服务器提供 generate_godot_uid 该工具：

  1. 接受a path 参数（例如。， "res://scenes/player.tscn")
  2. 连接到 localhost:8085 通过TCP
  3. 发送 get_path_uid 带路径的命令
  4. 接收并返回生成或缓存的UID字符串
  5. 优雅地处理错误（连接被拒绝、超时、数据格式错误）

🧪 发展

先决条件

  • Node.js 20+
  • npm
  • Godot 4.x（用于测试插件）

设置

# Install dependencies
npm install

# Build the MCP server
npm run build

# Run tests
npm run test

没有Godot的测试

测试套件包括一个模拟Godot插件的模拟TCP服务器：

cd mcp_server
npm test

测试场景包括：

  • ✅ UID生成成功
  • ❌ 连接被拒绝（Godot未运行）
  • ❌ JSON响应格式错误
  • ❌ 超时处理

📤 出版

该存储库包括一个用于发布到NPM的GitHub Actions工作流：

手工出版

首选 操作>发布到NPM>运行工作流

选项：

  • 版本：留空以发布当前 package.json 版本，或指定：
    • 学期： 1.0.1, 2.0.0
    • 碰撞类型： major, minor, patch

工作流程步骤

  1. 构建与测试：编译TypeScript并运行集成测试
  2. 版本颠簸 （可选）：运行 npm version 并创建一个git标签
  3. 发布：上传到NPM，可供公众访问
  4. GitHub发布 （可选）：创建带有版本标记的版本

必需的秘密

将这些秘密添加到您的GitHub存储库中：

  • NPM_TOKEN：具有发布权限的NPM身份验证令牌

🛠️ 配置

Godot插件

要更改TCP端口，请编辑 mcp_bridge.gd:

var server_port: int = 8085  # Change this value

MCP服务器

MCP服务器连接到 localhost:8085 默认情况下。要自定义，请执行以下操作：

const client = new GodotClient('localhost', 8085, 2000);

📝 用法示例

使用克劳德桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@lpenguin/godot-mcp"]
    }
  }
}

然后在克劳德：

"Generate a Godot ResourceUID for res://scenes/player.tscn"

克劳德将使用 generate_godot_uid 工具并返回有效 uid:// 弦。相同的路径将始终返回相同的UID。

🤝 贡献

欢迎投稿！拜托：

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

📄 许可证

麻省理工学院

🐛 故障排除

“无法连接到Godot编辑器”

  • 确保Godot编辑器正在运行
  • 验证MCP网桥插件是否已启用
  • 检查端口8085是否未被防火墙阻止

“连接超时”

  • Godot编辑器可能已冻结或正忙
  • 尝试重新启动Godot编辑器
  • 增加超时时间 GodotClient 构造函数

测试失败

# Make sure no other service is using port 8085
lsof -i :8085

# Run tests with verbose output
npm test -- --verbose

📚 资源

相关 MCP