godotmcp (Rectangle Equals)

GodotMCP

基于人工智能的Godot 4.4+通过模型上下文协议进行项目管理

GodotMCP是一个模型上下文协议（MCP）服务器，使Claude和其他AI助手能够通过GodotAI GDExtension管理Godot游戏项目。它提供全面的项目管理、文件操作、基于git的修改跟踪和调试功能，所有这些都具有用户审批工作流。

🎯 特性

• 📁 项目管理：获取项目信息、文件结构和Godot设置
• 📝 文件操作：使用git跟踪读取、创建、修改和删除文件
• 🔄 Git集成：具有差异查看、批准/拒绝、撤消/重做功能的完整git工作流
• 🐛 调试支持：通过VS Code集成运行和调试Godot项目
• 🔒 权限系统：精细的文件夹访问控制和自动审批规则
• ✅ 用户批准：在申请之前，审查并批准所有AI建议的更改
• 📊 变更历史：跟踪和浏览所有修改

🏗️ 建筑

Claude Desktop ↔ Docker MCP Toolkit ↔ GodotMCP (Docker) ↔ GodotAI (GDExtension) ↔ Godot Project

• GodotMCP：运行在Docker中的Python MCP服务器，代理Claude和GodotAI之间的请求
• GodotAI：C++GDExtension在Godot项目中运行，执行实际的文件和git操作
• 沟通：GodotMCP和GodotAI之间的异步HTTP/SSE，克劳德桌面的stdio

📋 先决条件

• Windows 10/11 WSL 2
• Docker桌面 启用MCP Toolkit测试版功能
• 克劳德桌面 对于Windows
• 戈多4.4+ 与您的游戏项目
• Python 3.11+ （用于发展）

🚀 快速开始

1.克隆存储库

git clone https://github.com/RectangleEquals/godotmcp.git
cd godotmcp

2.运行安装脚本

打开PowerShell并运行：

.\install.ps1

这将：

• 将MCP配置文件复制到Docker MCP目录
• 构建Docker镜像
• 在Docker Desktop上注册服务器
• 可选配置克劳德桌面

3.安装GodotAI GDExtension

*（GodotAI设置说明将另行提供）*

1. 从发布页面下载GodotAI
2. 提取到 res://addons/godotai/ 在您的Godot项目中
3. 配置 res://addons/godotai/config.json
4. 在Godot的项目设置中启用插件

4.在Claude Desktop中开始使用

打开克劳德桌面，您现在可以使用GodotMCP工具：

Can you show me the structure of my Godot project?

Create a new Player script at res://scripts/player.gd with basic movement code

Show me pending changes and let me approve them

🔧 配置

环境变量

GodotMCP支持以下环境变量：

您可以在Docker配置中或构建映像时设置这些。

GodotAI配置

通过编辑配置GodotAI res://addons/godotai/config.json:

{
  "listen_port": 9876,
  "permissions": {
    "allowed_folders": [
      "res://scripts/**",
      "res://scenes/**",
      "res://assets/**"
    ],
    "denied_folders": [
      "res://addons/godotai/**"
    ]
  },
  "auto_approve": {
    "patterns": [],
    "max_file_size_kb": 0
  },
  "auto_deny": {
    "patterns": [
      "**/*.import",
      ".godot/**"
    ]
  },
  "max_undo_history": 50,
  "enable_debug_mode": false
}

📚 可用工具

项目信息

• get_project_info -获取项目名称、Godot版本和设置
• get_project_structure -获取完整的文件/文件夹结构
• get_git_status -获取当前git状态和历史记录

文件操作

• read_file(path) -读取文件内容
• list_files(directory) -列出目录中的文件
• search_files(pattern, directory) -搜索与模式匹配的文件

文件修改（Git跟踪）

• create_file(path, content, commit_message) -创建新文件
• modify_file(path, content, commit_message) -修改现有文件
• delete_file(path, commit_message) -删除文件

Git工作流

• get_pending_changes() -查看等待批准的更改
• approve_changes(change_ids) -批准一项或多项更改
• deny_changes(change_ids) -拒绝并恢复更改
• retry_change(change_id) -拒绝并要求克劳德重试
• undo_changes(count) -撤消最近的更改
• redo_changes(count) -重做已撤消的更改
• get_change_history(limit) -查看更改历史记录

调试与执行

• run_project(scene) -运行Godot项目
• debug_project(scene, breakpoints) -使用VS代码开始调试
• stop_project() -停止运行/调试项目
• get_debug_logs(since, level) -获取调试日志

配置

• get_godotai_config() -获取GodotAI设置
• update_godotai_config(config) -更新GodotAI设置
• health_check() -检查GodotAI连接状态

🔄 工作流示例

创建和批准更改

1. 让Claude创建一个文件：

   Create a player controller script at res://scripts/player_controller.gd

1. 克劳德使用 create_file 工具 -创建文件并跟踪git

1. 查看待定更改：

   Show me what changes are pending approval

1. 查看差异 -克劳德给你看git diff

1. 批准或拒绝：

   Approve all pending changes

或

   Deny the last change and let's try again with more detailed comments

1. 必要时撤消：

   Actually, undo the last 2 changes

🏗️ 项目结构

godotmcp/
├── src/
│   └── godot_mcp_server/
│       ├── __init__.py          # Package init
│       └── server.py            # Main MCP server
├── .mcp/
│   └── catalog/
│       ├── custom-catalog.yaml  # MCP catalog config
│       └── v3/
│           └── tools/
│               └── godotmcp.json # Tool definitions
├── .claude/
│   └── claude_desktop_config.json # Claude Desktop config
├── Dockerfile                    # Docker container config
├── pyproject.toml               # Python project config
├── install.ps1                  # Windows installation script
├── README.md                    # This file
└── LICENSE                      # MIT License

🧪 发展

在当地建设

# Build Docker image
docker build -t godotmcp:latest .

# Run locally for testing
docker run -it --rm \
  -e GODOTAI_HOST=host.docker.internal \
  -e GODOTAI_PORT=9876 \
  godotmcp:latest

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Type checking
mypy src/

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔗 相关项目

• GodotAI -GodotMCP与之通信的C++GDExtension *（即将推出）*
• calcmcp -此项目所基于的模板MCP服务器
• Godot-更多-更多 -GDExtension项目模板

💬 支持

• 打开问题以获取错误报告或功能请求
• 检查 模型上下文协议文档
• 加入GitHub讨论

🙏 致谢

• 建立在 模型上下文协议
• 用途 FastMCP 用于服务器实现
• 受到对更好的AI辅助游戏开发工作流程需求的启发

______________________________________________________________________

⚠️ 备注：GodotMCP目前处于测试阶段。GodotAI GDExtension组件正在积极开发中。