YetAnotherUnityMcp

请勿使用。这是一个玩具项目，用于了解我可以使用 CLAUDE CODE 做什么。 我正在尝试评估开发人员是否可以仅通过 VIBE 编码正确工作 到目前为止，情况似乎并非如此！

一个 Unity 主控制协议 (MCP) 实现，允许 AI 代理控制和与 Unity 交互。

概述

YetAnotherUnityMcp 是一个使用模型上下文协议 (MCP) 将 Unity 游戏引擎与 AI 驱动的工具连接起来的系统。 它由一个作为 MCP TCP 服务器的 Unity .NET/C# 插件和一个处理来自 AI 代理请求的 Python MCP 客户端（使用 FastMCP 构建）组成。 Unity 和客户端之间的通信通过自定义 TCP 协议完成，从而实现 JSON 消息和图像数据的实时双向交换。

这种架构将游戏引擎的关注点与 AI 逻辑清晰地分离，从而提高了可扩展性和可维护性。 目标是允许 AI 代理（例如，基于 LLM 的助手）以结构化、安全的方式检查和控制正在运行的 Unity 场景。 基于容器的方法来组织资源和工具进一步改进了代码组织并减少了样板代码。

主要组件包括：

1. Unity MCP 插件（服务器） – 集成到 Unity 编辑器中并托管 TCP 服务器的 C# 插件
2. FastMCP Python 客户端 – 一个实现 Unity 的 MCP 接口的 Python 应用程序
3. MCP 客户端（AI 或外部） – 发送 MCP 请求的外部实体（例如 AI 助手或测试脚本）

什么是 MCP？

模型上下文协议 (MCP) 是 AI 模型与应用程序交互的一种标准化方式。 它将提供上下文的关注点与 LLM 交互本身分离，从而允许：

• 资源：向 LLM 提供数据（例如 Unity 场景层次结构）
• 工具：允许 LLM 采取行动（例如在 Unity 中执行代码）
• 提示：定义交互模板（例如如何创建 GameObject）

YetAnotherUnityMcp 完全符合官方 MCP 规范，包括：

• 基于内容数组的响应
• 基于 URI 的资源描述符
• 模式级别所需的参数数组
• 资源的 MIME 类型规范

特点

• 从 AI 代理在 Unity 中执行 C# 代码
• 通过具有动态参数处理的 MCP 资源查询 Unity 编辑器状态
• 在逻辑容器中组织 MCP 资源和工具，以实现更好的组织
• 使用 AI 驱动的参数捕获屏幕截图
• 通过实时监控和增量检索从 Unity 获取日志和调试信息
• 在 AI 辅助下修改 GameObject 属性
• 列出和导航 GameObject 层次结构
• 通过 MCP 提示提供上下文模板
• 通过 TCP 套接字进行实时通信
• TCP 服务器直接托管在 Unity 中
• 快速、高效的 JSON 序列化
• 具有类型安全参数映射的动态资源调用
• 基于 Schema 的工具和资源输入验证

入门

Unity 服务器设置

1. 打开您的 Unity 项目（2020.3 或更高版本）
2. 使用以下方法之一导入 YetAnotherUnityMcp 插件：
   • 将 plugin/Scripts 文件夹复制到 Unity 项目的 Assets 目录
   • 创建一个 Unity 包并导入它
   • 创建一个用于开发的符号链接（Windows PowerShell 示例）：

     New-Item -ItemType SymbolicLink -Target "D:\Dev\YetAnotherUnityMcp\plugin" -Path "C:\Users\azrea\My project\Assets\Plugins\YetAnotherUnityMcp"
     

3. 启动 TCP 服务器：
   • 从菜单：MCP > TCP Server > Start Server
   • 或者：Window > MCP Server > Start Server
4. 记下 TCP 服务器地址（默认：localhost:8080）

Python 客户端设置

# 克隆存储库
git clone https://github.com/yourusername/YetAnotherUnityMcp.git
cd YetAnotherUnityMcp

# 使用 uv 创建并激活虚拟环境
uv venv -p 3.11
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装带有开发依赖项的服务器
uv pip install -e ".[dev]"

# 运行 MCP 客户端
python -m server.mcp_server

MCP 集成

# 安装 FastMCP 和工具
uv pip install fastmcp

# 运行带有 MCP 检查器的客户端以进行调试
fastmcp dev server/mcp_server.py

# 在 Claude Desktop 中安装
fastmcp install server/mcp_server.py --name "Unity Controller"

项目结构

YetAnotherUnityMcp/
├── server/                      # Python MCP 客户端
│   ├── unity_client_util.py     # Unity 客户端实用程序函数
│   ├── unity_tcp_client.py      # 高级 Unity TCP 客户端
│   ├── mcp_server.py            # MCP 服务器实现
│   ├── dynamic_tool_invoker.py  # 动态工具调用系统
│   ├── dynamic_tools.py         # 动态工具管理器
│   ├── connection_manager.py    # 连接生命周期管理
│   └── websocket_client.py      # 低级 TCP 客户端（旧名称）
├── plugin/                      # Unity C# 插件
│   ├── Scripts/                 # 插件源代码
│   │   ├── Editor/              # 编辑器扩展
│   │   │   ├── Commands/        # 编辑器命令实现
│   │   │   ├── MCPWindow.cs     # 服务器控制窗口
│   │   │   ├── MCPMenu.cs       # Unity 菜单集成
│   │   │   ├── MCPTcpServer.cs  # 主要 TCP 服务器实现
│   │   │   ├── CommandExecutionMonitor.cs # 性能监控
│   │   │   ├── Models/          # 编辑器的数据模型
│   │   │   └── Net/             # TCP 通信实现
│   │   └── YetAnotherUnityMcp.asmdef  # 程序集定义
│   └── README.md                # 插件文档
└── tests/                       # 测试套件

架构

Unity TCP 服务器

Unity 插件托管一个 TCP 服务器，该服务器侦听来自 MCP 客户端的连接。 该服务器：

• 使用简单的帧协议管理客户端连接和消息路由
• 支持握手和 ping/pong 以进行连接健康监控
• 使用基于反射属性发现的工具和资源的动态注册表
• 提供用于按名称动态访问资源和工具的调用器
• 支持基于容器的工具和资源组织
• 执行客户端发送的命令（例如，运行 C# 代码、拍摄屏幕截图）
• 将结果返回给客户端
• 提供一个 UI 用于监控连接和调试

有关基于容器的方法的详细信息，请参阅 MCP 容器文档。

Python MCP 客户端

Python 客户端连接到 Unity TCP 服务器，并为 AI 工具提供 MCP 接口。 它：

• 将 MCP 请求转换为 Unity 的帧 TCP 消息
• 处理连接重试和保持活动 ping
• 将 Unity 响应转换为 MCP 资源数据
• 使用 FastMCP 的生命周期管理进行连接生命周期管理
• 提供标准化的错误处理和重新连接逻辑
• 为所有操作实现统一的执行模式
• 通过 FastMCP 框架提供工具和资源

MCP 资源和工具

资源

• unity://info - 关于 Unity 环境的基本信息
• unity://logs - 用于调试的编辑器日志
• unity://scene/{scene_name} - 关于特定场景的信息
• unity://object/{object_id} - 关于特定 GameObject 的详细信息

工具

• execute_code_in_unity - 在 Unity 编辑器中运行 C# 代码
• unity_screenshot - 拍摄 Unity 编辑器的屏幕截图
• unity_modify_object - 更改 Unity GameObject 的属性
• unity_logs - 从 Unity 获取日志，可以选择仅检索新日志

通信协议

Unity 服务器和 Python 客户端之间的所有通信都使用TCP 套接字连接和简单的帧协议，该协议允许持久、低延迟的双向消息传递。 连接由 Python 客户端发起到 Unity 服务器的 TCP 端点（例如 localhost:8080）。

该协议使用简单的帧机制：

• 开始标记 (STX, 0x02)
• 4 字节长度前缀
• JSON 消息内容
• 结束标记 (ETX, 0x03)

每条消息都是一个 JSON 对象，至少包含一个命令或响应类型、一个唯一 ID（用于将请求与响应配对）以及一个参数或结果对象。 连接通过周期性的 ping/pong 消息来维护。 有关通信协议的更多详细信息，请参阅 技术细节 文档。

开发

# Python 客户端开发
python -m pytest                    # 运行测试
python -m black .                   # 格式化代码
python -m flake8                    # 检查代码
python -m mypy .                    # 类型检查

# MCP 开发
fastmcp dev server/mcp_server.py    # 使用 MCP Inspector UI 运行

# Unity 服务器开发
# 使用 Unity 中的 MCP Server 窗口进行调试
# 实时监控连接和消息

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

有关架构、实现和可扩展性的更多详细信息，请参阅 技术细节 文档。