# Godot MCP Lite

本地加固版 Godot MCP，fork 自 [KeeVeeG/godot-mcp](https://github.com/KeeVeeG/godot-mcp) 并做安全与生命周期加固，替换 `agents/cursor/mcp.json` 中旧的 `godot-keeveeg` 条目（现名为 `godot`）。

## 解决的问题

| 痛点（原 KeeVeeG） | 本版处理 |
|---|---|
| 无鉴权，监听 6505-6514 多端口，本机任意进程可连入操作编辑器 | 固定单端口 + `auth` 消息携带共享 token 校验，失败即断开 |
| Godot 关闭后 MCP 服务器空转占 CPU | 检测到绑定的 Godot 编辑器进程关闭后退出；Godot 打开期间保持存活，避免会话中途掉线 |
| 300+ 工具含任意执行/输入模拟等高危能力 | `TOOL_ALLOWLIST` 白名单只保留 43 个安全工具，且 addon 端同步裁剪 |
| `GODOT_MCP_PROJECT` 曾被忽略，只认 `cwd` | 优先读 `GODOT_MCP_PROJECT` 并校验 `project.godot` |

## 架构

```
Cursor / MCP client
   │ stdio (JSON-RPC 2.0)
   ▼
Node.js MCP Server (godot)                 ← 固定端口 6510，token 鉴权，Godot 关闭时自退
   │ WebSocket (JSON-RPC 2.0) + auth token
   ▼
Godot Editor Plugin (addons/godot_mcp)
   ├── command_router → scene/node/script/editor/project/runtime 模块
   └── mcp_runtime autoload（运行时读属性/截图，走文件 IPC）
```

## 连接与鉴权

- 端口默认 `6510`，server 用 `GODOT_MCP_PORT` 覆盖；addon 端固定 `FIXED_PORT = 6510`（或 `res://godot_mcp_config.json` 的 `port`）。
- token 存于项目根 `.godot/mcp_token`（0600，git 忽略）。server 启动时若无则生成，addon 从同路径读取后以 `auth` 消息上报，server 校验通过才回 `server_hello`。
- 一个 server 同时只服务**一个**项目（`GODOT_MCP_PROJECT`）。换项目改 `mcp.json` 的该 env 即可。

## 安装

### 1. Server

改 `agents/cursor/mcp.json`（已在仓库内）：

```json
{
  "mcpServers": {
    "godot": {
      "command": "/Users/max/.local/node/bin/node",
      "args": ["/Users/max/Documents/Agent/agents/mcp/godot/godot-mcp-lite/server/dist/index.js"],
      "env": {
        "GODOT_MCP_PORT": "6510"
      }
    }
  }
}
```

> **项目自动跟随**：无需写死 `GODOT_MCP_PROJECT`。server 启动时**扫描运行中的 Godot 编辑器进程**，取它打开的 `--path` 项目；没有就用 `cwd` 向上找。因此它会自动跟随当前打开的 Godot 项目，切项目不用改配置。仅当需要显式指定某项目时，才设 `GODOT_MCP_PROJECT`（优先级最高）。

改动后需在 Cursor 的 Settings → MCP 里刷新/重启该 server。

### 2. Godot 插件

把 `addons/godot_mcp/` 拷贝到你的 Godot 项目 `addons/` 下，然后 Project → Project Settings → Plugins 设为 Active。首次打开时会自动注入 `MCPRuntime` autoload。

## 构建（改 TS 源码后）

```bash
cd godot-mcp-lite/server && npm install && npx tsc
```

## 日志（调试用）

Server 把运行日志写入文件，便于 MCP 排查，同时**自动按大小滚动 + 数量/天数清理**，避免磁盘膨胀。

- 默认路径：`server/logs/godot-mcp.log`（`GODOT_MCP_LOG_DIR` 可改）
- 内容含：启动、端口监听、连接/鉴权、工具调用失败、白名单 drop、关闭等关键事件
- 级别：默认 `info`；设置 `GODOT_MCP_DEBUG` 或 `GODOT_MCP_LOG_LEVEL=debug` 可看更细（含白名单 drop 噪音）

| 环境变量 | 默认 | 作用 |
|---|---|---|
| `GODOT_MCP_FILE_LOG` | `1` | `0`/`false` 关闭文件日志 |
| `GODOT_MCP_LOG_DIR` | `server/logs` | 日志目录 |
| `GODOT_MCP_LOG_LEVEL` | `info` | 文件日志级别（`debug`/`info`/`warn`/`error`） |
| `GODOT_MCP_LOG_MAX_BYTES` | `2097152` (2 MiB) | 单文件滚动阈值 |
| `GODOT_MCP_LOG_MAX_FILES` | `5` | 保留的滚动文件数（旧的删除） |
| `GODOT_MCP_LOG_RETENTION_DAYS` | `0` | 保留天数，`0`=不按天删 |

日志写入失败的异常被静默吞掉，不会影响 server 运行。

## 保留的工具集（43 个）

- 项目：`get_project_info`、`get_project_settings`
- 场景：`get_scene_tree`、`create_scene`、`open_scene`、`play_scene`、`stop_scene`、`save_scene`、`get_loaded_scenes`、`set_main_scene`、`get_main_scene`、`close_scene` 等
- 节点：`add_node`、`delete_node`、`move_node`、`update_property`、`get_node_properties`、`rename_node`、`get_node_groups` 等
- 校验/读取：`validate_script`、`read_script`、`get_open_scripts`
- 日志/错误：`get_editor_errors`、`get_output_log`、`clear_output`、`get_diagnostics`
- 运行时（只读/截图）：`get_game_scene_tree`、`get_game_node_properties`、`capture_frames`、`get_game_screenshot`

默认**不注册**：`execute_editor_script`、`execute_game_script`、`delete_scene`、`set_game_node_property`、输入模拟、录制回放、批量写、路径遍历类。

## 安全模型

- 仅监听 `127.0.0.1` 固定端口，未带有效 token 的连接一律 `1008` 关闭。
- Token 不进 git，权限 0600，目录在 `.godot/`。
- 工具白名单在 server（`TOOL_ALLOWLIST`）与 addon（`plugin.gd` module_paths）双层落实；危险工具既不注册也不加载。
- Godot 打开期间 server 保持存活（不做空闲超时，避免会话中途掉线）；检测到绑定的 Godot 编辑器进程关闭后退出，不留常驻进程。

## 相关

- 上游：KeeVeeG/godot-mcp（MIT，本版仅精调其 server/addon）
- 本地资源：`agents/mcp/godot/godot-mcp-lite/`