YetAnotherUnityMcp

请勿使用此项目。这是一个玩具项目，用于测试我能否使用 Claude 代码进行开发。
我正在尝试评估一个开发者是否能够仅通过直觉编码正确地工作。
到目前为止，似乎情况并非如此！

一个 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 编辑器中的 C# 插件，托管一个 TCP 服务器
2. FastMCP Python 客户端 – 一个实现 Unity MCP 接口的 Python 应用程序
3. MCP 客户端（AI 或外部） – 外部实体（如 AI 助手或测试脚本），发送 MCP 请求

什么是 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 套接字实现实时通信
• 直接在 Unity 中托管 TCP 服务器
• 快速高效的 JSON 序列化
• 动态资源调用，带类型安全的参数映射
• 基于模式的输入验证，用于工具和资源

入门

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 客户端设置

# 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 消息
• 处理连接重试和保活 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)

每条消息都是一个至少包含 命令或响应类型、唯一ID（用于将请求与响应配对）、以及参数或结果对象的 JSON 对象。通过定期发送 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 文件。

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