YetAnotherUnityMcp
别用这个。这只是个玩具项目，用来测试一下我能用 Claude Code 做什么。我正在尝试评估开发者能否仅使用 Vibe Coding 就能正常工作，目前看来似乎不行！
Unity 主控制协议 (MCP) 实现允许 AI 代理控制 Unity 并与之交互。
概述
YetAnotherUnityMcp是一个使用模型上下文协议 (MCP)将 Unity 游戏引擎与 AI 驱动工具连接起来的系统。它由一个充当 MCP TCP 服务器的 Unity .NET/C# 插件和一个处理 AI 代理请求的Python MCP 客户端（使用 FastMCP 构建）组成。Unity 与客户端之间的通信通过自定义 TCP 协议进行，从而实现 JSON 消息和图像数据的实时双向交换。
该架构将游戏引擎关注点与AI逻辑清晰地分离，从而提高了可扩展性和可维护性。其目标是允许AI代理（例如基于LLM的助手）以结构化、安全的方式检查和控制正在运行的Unity场景。基于容器的资源和工具组织方法进一步优化了代码组织，并减少了样板代码。
关键组件包括：
- Unity MCP 插件（服务器） ——集成到 Unity 编辑器的 C# 插件，可托管 TCP 服务器
- FastMCP Python 客户端– 一个为 Unity 实现 MCP 接口的 Python 应用程序
- MCP 客户端（AI 或外部） ——发送 MCP 请求的外部实体（例如 AI 助手或测试脚本）
什么是 MCP？
模型上下文协议 (MCP)是 AI 模型与应用程序交互的标准化方式。它将提供上下文的关注点与 LLM 交互本身分离开来，从而允许：
- 资源：向 LLM 提供数据（如 Unity 场景层次结构）
- 工具：允许 LLM 采取行动（例如在 Unity 中执行代码）
- 提示：定义交互模板（例如如何创建游戏对象）
YetAnotherUnityMcp 完全符合官方 MCP 规范，包括：
- 基于内容数组的响应
- 基于 URI 的资源描述符
- 架构级别所需的参数数组
- 资源的 MIME 类型规范
特征
- 从 AI 代理在 Unity 中执行 C# 代码
- 通过具有动态参数处理的 MCP 资源查询 Unity 编辑器状态
- 将 MCP 资源和工具组织到逻辑容器中，以便更好地组织
- 使用 AI 驱动的参数截取屏幕截图
- 通过实时监控和增量检索从 Unity 获取日志和调试信息
- 使用 AI 辅助修改 GameObject 属性
- 列出并导航 GameObject 层次结构
- 通过 MCP 提示提供上下文模板
- 通过 TCP 套接字进行实时通信
- TCP 服务器直接托管在 Unity 中
- 快速、高效的 JSON 序列化
- 具有类型安全参数映射的动态资源调用
- 基于模式的工具和资源输入验证
入门
Unity 服务器设置
- 打开你的 Unity 项目（2020.3 或更高版本）
- 使用以下方法之一导入 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"
- 启动TCP服务器：
- 从菜单：MCP > TCP 服务器 > 启动服务器
- 或者：窗口 > MCP 服务器 > 启动服务器
- 记下 TCP 服务器地址（默认值：localhost:8080）
Python 客户端设置
# Clone the repository
git clone https://github.com/yourusername/YetAnotherUnityMcp.git
cd YetAnotherUnityMcp
# Create and activate a virtual environment using uv
uv venv -p 3.11
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the server with development dependencies
uv pip install -e ".[dev]"
# Run the MCP client
python -m server.mcp_server
MCP 集成
# Install FastMCP and tools
uv pip install fastmcp
# Run the client with MCP inspector for debugging
fastmcp dev server/mcp_server.py
# Install in Claude Desktop
fastmcp install server/mcp_server.py --name "Unity Controller"
项目结构
YetAnotherUnityMcp/
├── server/ # Python MCP client
│ ├── unity_client_util.py # Unity client utility functions
│ ├── unity_tcp_client.py # High-level Unity TCP client
│ ├── mcp_server.py # MCP server implementation
│ ├── dynamic_tool_invoker.py # Dynamic tool invocation system
│ ├── dynamic_tools.py # Dynamic tool manager
│ ├── connection_manager.py # Connection lifecycle management
│ └── websocket_client.py # Low-level TCP client (legacy name)
├── plugin/ # Unity C# plugin
│ ├── Scripts/ # Plugin source code
│ │ ├── Editor/ # Editor extensions
│ │ │ ├── Commands/ # Editor command implementations
│ │ │ ├── MCPWindow.cs # Server control window
│ │ │ ├── MCPMenu.cs # Unity menu integration
│ │ │ ├── MCPTcpServer.cs # Primary TCP server implementation
│ │ │ ├── CommandExecutionMonitor.cs # Performance monitoring
│ │ │ ├── Models/ # Data models for Editor
│ │ │ └── Net/ # TCP communication implementation
│ │ └── YetAnotherUnityMcp.asmdef # Assembly definition
│ └── README.md # Plugin documentation
└── tests/ # Test suite
建筑学
Unity TCP服务器
Unity 插件托管一个 TCP 服务器，用于监听来自 MCP 客户端的连接。该服务器：
- 使用简单的框架协议管理客户端连接和消息路由
- 支持握手和 ping/pong 以监控连接健康
- 使用基于反射的属性发现和工具和资源的动态注册表
- 提供通过名称动态访问资源和工具的调用程序
- 支持基于容器的工具和资源组织
- 执行客户端发送的命令（例如，运行 C# 代码、截取屏幕截图）
- 将结果返回给客户端
- 提供用于监控连接和调试的 UI
有关基于容器的方法的详细信息，请参阅MCP 容器文档。
Python MCP 客户端
Python 客户端连接到 Unity TCP 服务器，并为 AI 工具提供 MCP 接口。它：
- 将 MCP 请求转换为 Unity 的 TCP 消息
- 处理连接重试和保持连接
- 将 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 GameObjects 的属性unity_logs - 从 Unity 获取日志，并可选择仅检索新日志
通信协议
Unity 服务器和 Python 客户端之间的所有通信都使用带有简单帧协议的TCP 套接字连接，从而实现持久、低延迟的双向消息传递。该连接由 Python 客户端发起，指向 Unity 服务器的 TCP 端点（例如localhost:8080 ）。
该协议使用简单的框架机制：
- 开始标记（STX，0x02）
- 4字节长度前缀
- JSON 消息内容
- 结束标记（ETX，0x03）
每条消息都是一个 JSON 对象，至少包含一个命令或响应类型、一个唯一 ID （用于将请求与响应配对）以及一个参数或结果对象。连接通过定期发送 ping/pong 消息来维护。有关通信协议的更多详细信息，请参阅技术细节文档。
发展
# Python client development
python -m pytest # Run tests
python -m black . # Format code
python -m flake8 # Lint code
python -m mypy . # Type check
# MCP Development
fastmcp dev server/mcp_server.py # Run with MCP Inspector UI
# Unity server development
# Use the MCP Server window in Unity for debugging
# Monitor connections and messages in real-time
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。
有关架构、实施和可扩展性的更多详细信息，请参阅技术细节文档。