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.克隆存储库```bash
git clone https://github.com/RectangleEquals/godotmcp.git
cd godotmcp
2.运行安装脚本
打开PowerShell并运行:```powershell
.\install.ps1
这将:
- 将MCP配置文件复制到Docker MCP目录
- 构建Docker镜像
- 在Docker Desktop上注册服务器
- 可选配置克劳德桌面
### 3.安装GodotAI GDExtension
*(GodotAI设置说明将另行提供)*
1. 从发布页面下载GodotAI
1. 提取到 `res://addons/godotai/` 在您的Godot项目中
1. 配置 `res://addons/godotai/config.json`
1. 在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支持以下环境变量:
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_HOST |
127.0.0.1 |
MCP服务器主机 |
MCP_PORT |
8080 |
MCP服务器端口 |
GODOTAI_HOST |
host.docker.internal |
GodotAI运行的主机 |
GODOTAI_PORT |
9876 |
GodotAI正在监听的端口 |
GODOTAI_TIMEOUT |
30 |
GodotAI请求超时(秒) |
您可以在Docker配置中或构建映像时设置这些。
GodotAI配置
通过编辑配置GodotAI res://addons/godotai/config.json:```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
-
克劳德使用
create_file工具 -创建文件并跟踪git -
查看待定更改:```
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
## 🧪 发展
### 在当地建设```bash
# 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
运行测试```bash
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组件正在积极开发中。
