内容
# UnityRuntimeMCP
UnityRuntimeMCP 是模型上下文协议（MCP）的实现，作为 Unity IL2CPP 游戏的 BepInEx 6 插件。它使外部 AI 代理能够通过基于反射的工具与游戏运行时交互。
## 功能特点
- **实时检查与对象缓存**：发现和检查 Unity `GameObject`/`Component` 实例，以及非 Unity 引用类型（类和数组）。
- **稳定的身份映射**：维护所有遇到的 Unity 对象和非 Unity 引用类型的弱引用缓存。非 Unity 对象分配动态 ID，从 `1,000,000,000` 开始，以保证跨帧引用稳定性。
- **深度反射与序列化**：访问 IL2CPP 环境中派生类型的字段、属性和方法。自动序列化集合和数组，最多 20 个元素，缓存嵌套的非 Unity 对象以便进一步检查。
- **运行时修改**：读取和写入对象字段和属性的值，支持嵌套的点表示法路径。
- **视觉反馈**：以 Base64 PNG 格式捕获游戏视图截图，或保存到跨平台临时目录。
- **线程安全**：自动将 Unity API 调用分派到主线程。
- **生命周期管理**：保护免受场景清理和 IL2CPP 特定对象销毁的影响。
## 提供的工具
服务器注册了以下 MCP 工具：
| 工具 | 描述 |
| :--- | :--- |
| `find_objects` | 按类名查找活跃的 GameObjects。返回具有 `instance_id` 的身份对象。如果类不存在，则返回空列表。 |
| `get_hierarchy` | 返回 Unity GameObjects/Components 的直接父级和子级 ID。仅限于 Unity 对象。 |
| `inspect_object` | 详细的成员视图。支持 Unity 和缓存的非 Unity 对象。`include_methods` 默认设为 `false` 以提高效率。 |
| `read_field` | 读取值。支持点表示法路径（例如，`transform.parent.name`）。对于断开的路径，返回 `null`。 |
| `write_field` | 写入值。支持嵌套路径。建议优先使用属性设置器而不是私有后备字段，以确保执行副作用。 |
| `invoke_method` | 在 Unity 或缓存的非 Unity 对象上执行方法。支持通过 `type_args` 实现泛型方法。 |
| `take_screenshot` | 捕获游戏屏幕。支持 `scale`（0.1 到 1.0，默认为 0.5）和 `save_to_file`（布尔值）。使用稳定的自定义管道避免 IL2CPP 原生 JPG 崩溃。 |
## 功能亮点
- **身份映射与缓存**：服务器维护所有遇到的 Unity 对象和非 Unity 引用类型的弱引用缓存（分配动态 ID >= 1,000,000,000）。这确保 `instance_id` 引用在帧之间保持稳定，即使对象不活动或难以通过标准搜索定位。
- **强大的路径遍历**：`read_field` 和 `write_field` 中的点表示法支持允许在单个调用中进行深入检查。系统优雅地处理空段，返回标准 JSON `null` 而不是错误。
- **泛型方法解析**：代理可以通过提供 `type_args`（完整类型名称列表）调用泛型 Unity 方法，从而实现 `GetComponent<TextMeshProUGUI>()` 等高级操作。
- **自定义截图引擎**：通过绕过原生 IL2CPP `EncodeToJPG` 委托避免原生 IL2CPP `AccessViolationException` 崩溃。相反，它将原生屏幕缓冲区闪存到缩放的 `RenderTexture` 并将其编码为 PNG。缩放输出减少了有效载荷大小，并且设置 `save_to_file` 直接保存到系统临时目录（Windows 上为 `C:\Users\Public\UnityRuntimeMCP_Temp`，macOS/Linux 上为 `/tmp/UnityRuntimeMCP_Temp`）。
## 安装
1. 在目标游戏安装 BepInEx 6（IL2CPP）。
2. 将 `UnityRuntimeMCP.dll` 放置在 `BepInEx/plugins` 目录中。
3. 启动游戏；MCP 服务器在配置的端口上初始化。
### 配置
配置通过 `BepInEx/config/me.pokelege.unityruntimemcp.cfg` 管理：
- `Port`：服务器监听端口（默认：3000）。
- `Host`：服务器绑定地址（默认：127.0.0.1）。
## 构建
如果您不使用预构建的版本，可以从源代码构建插件：
### 先决条件
- [.NET 6.0 SDK](https://dotnet.microsoft.com/download/dotnet/6.0)
- 将 Unity 游戏程序集放在 `libs/` 目录中（这些已经包含在存储库中以供参考）。
### 构建命令
要构建项目，请在项目根目录运行以下命令之一：
- **调试构建**：
```powershell
dotnet build
```
编译的 DLL 将位于 `bin/Debug/net6.0/UnityRuntimeMCP.dll`。
- **发布构建**：
```powershell
dotnet build -c Release
```
编译的 DLL 将位于 `bin/Release/net6.0/UnityRuntimeMCP.dll`。
## 连接
服务器使用 HTTP/SSE 传输。
### 客户端配置
MCP 客户端应连接到以下端点：
`http://127.0.0.1:3000/mcp`
### 技术规格
- **协议**：JSON-RPC 2.0，基于服务器发送事件（SSE）。
- **初始化**：需要标准的 MCP 初始化握手。
- **会话管理**：支持 JSON-RPC 合规的请求 ID 跟踪。
## 技术架构
- **主线程调度器**：一个持久的 MonoBehaviour，管理线程安全的执行队列。
- **IL2CPP 桥接器**：自定义类型解析映射，将 IL2CPP 内部类型映射到托管的 System.Type 以实现反射准确性。
- **模块化设计**：工具实现解耦，以提高可扩展性。
## 禁止使用
本软件用于研究和开发目的。严禁将本软件用于促进多人或在线游戏中的作弊。用户承担因反作弊系统检测及后续账户操作带来的所有风险。
## 许可证
本项目根据 GNU Lesser General Public License v2.1 许可。有关完整的许可文本和免责声明，请参见 [LICENSE](LICENSE) 文件。
