企业官网建设流程全解析

1. 项目概述：为什么Unity MCP值得你投入时间？

最近在跟几个做AI Agent和游戏开发的朋友聊天，发现大家不约而同地提到了一个词：Unity MCP。乍一听，这像是Unity引擎里又一个晦涩难懂的SDK或者插件。但当我真正花时间去研究它的目录结构、运行机制，并尝试从零开始构建一个自己的MCP工具后，我发现这玩意儿远不止是一个“插件”那么简单。它本质上是在重新定义我们与AI协作开发游戏的方式。

简单来说，Model Context Protocol是一个开放协议，它让像Claude、Cursor这类AI助手，能够以一种标准化、安全的方式，去“操作”外部的工具和环境。而Unity MCP，就是Unity官方基于这个协议，为Unity编辑器打造的一座“桥梁”。这座桥的一端连着AI，另一端直接连着你正在编辑的场景、资产和代码。这意味着什么？意味着你可以用自然语言告诉AI：“在场景中央创建一个立方体，给它附上红色的材质，再写一段让它旋转的脚本。” AI通过MCP，就能像你亲手操作一样，在Unity里完成这些任务。

这听起来很酷，但网上能找到的资料大多是官方文档的翻译，或者一些简单的使用演示。很少有人去拆解：这个协议在Unity里到底是怎么跑起来的？~/.unity/relay/这个目录里藏着什么秘密？我们自己写的工具，又是如何通过几个简单的文件，就被AI识别和调用的？如果你也对这些“黑盒”里的细节感到好奇，想不只是“使用”MCP，而是真正“理解”并“创造”属于自己的MCP能力，那么这篇从目录结构入手，带你从零打造MCP工具的文章，就是为你准备的。

2. 核心架构与目录结构深度解析

要打造自己的MCP工具，第一步不是急着写代码，而是彻底理解Unity MCP这套系统是如何组织起来的。很多问题，比如“为什么我的工具没被加载？”、“日志去哪了？”，答案都藏在它的目录结构里。

2.1 核心三组件与数据流向

根据官方文档和实际探查，Unity MCP的运行依赖于三个核心组件，它们之间的数据流向构成了整个系统的骨架：

1. AI客户端：比如你正在使用的Cursor编辑器，或者集成了Claude Code的IDE。它内置了MCP客户端的能力，负责发起请求、解析响应。
2. 中继服务器：这是一个独立的二进制程序，默认安装在~/.unity/relay/（macOS/Linux）或%USERPROFILE%\.unity\relay\（Windows）目录下。它是整个MCP通信的枢纽。AI客户端通过标准输入输出与中继通信，中继再通过本地进程间通信与Unity编辑器对话。
3. Unity编辑器：作为MCP的“服务端”，它内部运行着一个MCP Bridge。这个Bridge负责管理所有注册进来的工具，并将中继服务器传来的协议指令，翻译成对Unity编辑器API的实际调用。

它们之间的通信路径可以清晰地表示为：

AI客户端 (MCP Client) <--[stdio， JSON-RPC over MCP]--> 中继服务器 (Relay) <--[IPC: Named Pipe/Unix Socket]--> Unity编辑器 (MCP Bridge) <--> 具体的工具实现

这个架构的精妙之处在于解耦。AI客户端不需要知道Unity编辑器的复杂内部结构，它只需要遵循MCP协议与中继对话。中继服务器作为一个轻量的、语言无关的中间层，负责协议转换和连接管理。而Unity编辑器则专注于暴露安全的、结构化的工具接口。

2.2 关键目录与文件剖析

理解了架构，我们再来看看硬盘上那些实实在在的文件。这些目录是故障排查和深度定制的关键。

~/.unity/relay/目录这是整个MCP系统的“心脏”。首次成功运行Unity MCP后，这个目录会被自动创建。里面通常包含以下关键内容：

• unity-mcp-relay（或带后缀的可执行文件）：这就是上文提到的中继服务器二进制文件。它的版本会随着Unity版本更新。
• config.json：中继服务器的配置文件。你可能需要在这里调整日志级别、设置超时时间，或者指定连接Unity的IPC socket路径。例如，当遇到mcp client for \codex_apps` timed out after 30 seconds` 这类错误时，第一个检查点就应该是这个配置文件里的超时设置。
• logs/目录：存放中继服务器的运行日志。当通信出现问题时（比如AI客户端连接不上），这里的日志是首要的排查依据。日志会详细记录连接建立、请求接收、转发、错误等信息。

注意：~/.unity/目录是Unity存放用户级全局配置和缓存的地方，类似Maven的.m2仓库。清理Unity缓存或重装时，如果这个目录被误删，会导致MCP需要重新下载和初始化中继，这可能就是某些情况下“Unity WebGL初始化很久”或“Unity程序打开黑屏无响应”的间接原因之一——系统在后台尝试恢复MCP组件。

Unity项目内的MCP相关结构在Unity项目内部，MCP工具的注册和发现主要依赖于C#的反射机制和特定的程序集。虽然没有一个固定的“MCP”项目目录，但其逻辑结构清晰：

• 工具定义：任何实现了IMcpTool接口或使用了[McpTool]属性的C#类，都会被视作一个MCP工具。
• 程序集扫描：Unity编辑器启动时，MCP Bridge会扫描所有已加载的程序集（包括Assets目录下的脚本、Packages中的插件），寻找这些工具类并自动注册。
• 配置界面：在Edit > Project Settings > AI > Unity MCP页面里，你可以看到所有被发现的工具列表，并可以单独启用或禁用它们。这个配置是项目特定的，会保存在项目的ProjectSettings/目录下。

与“Skill”目录结构的对比思考在讨论MCP时，常有人问它和“Agent Skill”有什么区别。你可以这样理解：Skill（技能）是能力的具体实现，而MCP是调用这些能力的标准化协议和通信管道。 一个Skill目录可能包含复杂的逻辑、模型和数据文件。而MCP目录（~/.unity/relay/）则更轻量，只关心如何安全、高效地将外部请求路由到对应的Skill实现。MCP让AI可以动态发现并调用这些Skill，而无需硬编码集成。因此，在规划你自己的工具时，应该将业务逻辑（Skill）和协议适配层（MCP Tool包装器）分开，这符合单一职责原则，也便于后续维护和扩展。

3. 从零打造自定义MCP工具：实战指南

理论说得再多，不如动手做一遍。接下来，我将带你完整实现一个自定义MCP工具。我们的目标是：创建一个能让AI通过自然语言，快速在场景中查找并高亮显示所有使用了特定Shader的材质球的工具。这在实际项目优化（比如排查URP Shader体积光性能问题）时非常有用。

3.1 环境准备与项目设置

首先，确保你的环境符合要求：

• Unity版本：2022.3 LTS 或更新版本。MCP功能在较新的版本中才完整支持。
• AI客户端：安装并配置好Cursor（推荐）或其它支持MCP协议的IDE。确保其MCP客户端功能已开启。
• Unity MCP启用：在Unity中，打开Edit > Project Settings > AI > Unity MCP，确保“Enable Unity MCP”是打开状态。首次启用时，Unity可能会自动下载中继服务器到~/.unity/relay/目录。

实操心得：如果你遇到连接问题，一个有效的排查步骤是，先在Unity的MCP设置页面，尝试手动“Stop”然后“Start”Bridge。同时，在Cursor的设置中，检查MCP服务器配置是否正确指向了unity类型或对应的中继路径。有时候仅仅是重启两边客户端就能解决临时的socket占用问题。

3.2 定义第一个MCP工具：Shader材质查找器

我们在Unity项目中创建一个新的C#脚本，命名为FindMaterialsByShaderTool.cs。工具的核心是定义一个类，并实现IMcpTool接口。为了更简单，我们也可以使用属性标记法。

using UnityEngine; using UnityEditor; using System.Collections.Generic; using Unity.AI.Mcp; // 需要引用Unity的MCP命名空间 // 使用McpTool属性标记这是一个MCP工具，并定义工具的名称和描述。 // 描述非常重要，AI客户端会读取它来理解这个工具的功能。 [McpTool("find_materials_by_shader", "Finds all materials in the project that use a specified shader, and highlights their GameObjects in the scene.")] public class FindMaterialsByShaderTool : IMcpTool { // 定义工具的输入参数。这里我们只需要一个参数：目标Shader的名字。 [McpToolArgument("shader_name", typeof(string), "The name of the shader to search for (e.g., 'Universal Render Pipeline/Lit').")] public string TargetShaderName { get; set; } // Execute方法是工具的核心，AI客户端调用工具时，就会运行这个方法。 [McpToolExecute] public McpToolResult Execute() { if (string.IsNullOrEmpty(TargetShaderName)) { return McpToolResult.Error("Shader name cannot be empty."); } // 1. 在项目中查找指定Shader Shader targetShader = Shader.Find(TargetShaderName); if (targetShader == null) { return McpToolResult.Error($"Shader '{TargetShaderName}' not found in the project."); } // 2. 获取项目中所有材质球的GUID string[] materialGuids = AssetDatabase.FindAssets("t:Material"); List<string> foundMaterialPaths = new List<string>(); List<GameObject> affectedGameObjects = new List<GameObject>(); // 3. 遍历所有材质，检查其使用的Shader foreach (string guid in materialGuids) { string path = AssetDatabase.GUIDToAssetPath(guid); Material material = AssetDatabase.LoadAssetAtPath<Material>(path); if (material != null && material.shader == targetShader) { foundMaterialPaths.Add(path); // 4. 查找场景中使用此材质的GameObject并高亮 FindAndHighlightInScene(material, affectedGameObjects); } } // 5. 准备返回结果 if (foundMaterialPaths.Count == 0) { return McpToolResult.Ok($"No materials found using shader '{TargetShaderName}'."); } // 将结果格式化为对AI友好的文本，同时包含结构化数据（可选） string resultMessage = $"Found {foundMaterialPaths.Count} material(s) using shader '{TargetShaderName}':\n" + string.Join("\n", foundMaterialPaths) + $"\n\nHighlighted {affectedGameObjects.Count} GameObject(s) in the Scene Hierarchy."; // 你可以返回一个包含复杂对象的Result，AI客户端可以解析它。 var resultData = new { shaderName = TargetShaderName, materialCount = foundMaterialPaths.Count, materialPaths = foundMaterialPaths, highlightedObjectCount = affectedGameObjects.Count }; return McpToolResult.Ok(resultMessage); // 目前先返回简单消息 } // 辅助方法：在场景中查找使用该材质的Renderer并高亮（通过Ping对象） private void FindAndHighlightInScene(Material material, List<GameObject> collection) { // 这里使用一个简单的方法：获取所有Renderer，检查其sharedMaterials。 // 注意：这只检查当前打开的场景。对于多场景或Prefab，需要更复杂的逻辑。 Renderer[] allRenderers = Object.FindObjectsByType<Renderer>(FindObjectsSortMode.None); foreach (Renderer renderer in allRenderers) { if (renderer.sharedMaterials != null) { foreach (var mat in renderer.sharedMaterials) { if (mat == material) { collection.Add(renderer.gameObject); // 在Project窗口和Scene Hierarchy中高亮该物体 EditorGUIUtility.PingObject(renderer.gameObject); break; } } } } } }

代码关键点解析：

1. [McpTool]属性：这是工具的“身份证”，name参数是AI调用时使用的标识符，description会帮助AI理解工具用途。描述写得越清晰，AI调用得越准确。
2. [McpToolArgument]属性：定义了工具的输入参数。AI客户端会根据这个定义来构造请求。我们定义了一个shader_name字符串参数。
3. [McpToolExecute]方法：必须标记此属性，这是工具的入口点。方法返回McpToolResult对象，Ok表示成功并返回结果，Error表示失败并返回错误信息。
4. Shader.Find与AssetDatabase：使用了Unity Editor API来查询资产。切记，MCP工具运行在编辑器上下文中，可以安全使用这些API。
5. 高亮与交互：EditorGUIUtility.PingObject是一个简单的编辑器交互，可以让场景中的物体在Hierarchy中闪烁选中，给用户直观的反馈。更复杂的工具可以返回操作指令，让AI客户端决定如何展示。

3.3 编译、注册与测试

1. 编译脚本：将脚本放在项目的Assets/Editor/或任何Editor文件夹下，确保它只在编辑器中编译。Unity会重新编译项目。
2. 查看注册：编译成功后，再次打开Edit > Project Settings > AI > Unity MCP，在工具列表里你应该能看到名为find_materials_by_shader的新工具，并且处于启用状态。
3. 在AI客户端中测试：
   • 打开Cursor，确保它已连接到Unity（通常会自动发现）。
   • 在Chat界面中，尝试输入指令：“请使用find_materials_by_shader工具，帮我找找项目里所有使用了 ‘Universal Render Pipeline/Lit’ 这个Shader的材质。”
   • Cursor的AI应该会理解你的意图，自动构造并发送MCP请求。如果一切正常，你会在Unity编辑器中看到对应的材质路径被输出到控制台（我们需要稍作修改来输出日志），并且场景中使用这些材质的物体会被高亮。

让工具输出日志：为了更好的调试和用户反馈，我们可以修改Execute方法，将结果也打印到Unity控制台。

[McpToolExecute] public McpToolResult Execute() { // ... 前面的查找逻辑不变 ... if (foundMaterialPaths.Count == 0) { Debug.LogWarning($"[MCP Tool] No materials found for shader: {TargetShaderName}"); return McpToolResult.Ok($"No materials found using shader '{TargetShaderName}'."); } Debug.Log($"[MCP Tool] Found {foundMaterialPaths.Count} materials for shader '{TargetShaderName}'."); foreach (var path in foundMaterialPaths) { Debug.Log($" - {path}"); } // ... 返回结果 ... }

4. 高级技巧：打造更强大、更可靠的MCP工具

基础工具跑通后，我们可以从工程化角度，让它变得更健壮、更易用。

4.1 参数验证与复杂输入

上面的工具只接受一个字符串参数。但有时我们需要更复杂的输入。MCP支持通过定义复杂的参数类来实现。

例如，我们升级工具，允许按Shader名称和材质类型（Standard， URP Lit， 等）进行过滤，并且可以指定是否搜索所有场景。

[McpTool("advanced_material_finder", "Finds materials with advanced filters like shader name, type, and search scope.")] public class AdvancedMaterialFinderTool : IMcpTool { // 使用一个嵌套类来定义复杂参数 public class SearchParameters { [McpToolArgument("shader_name_part", typeof(string), "Part of the shader name to search for (optional).")] public string ShaderNamePart { get; set; } [McpToolArgument("material_type", typeof(string), "Filter by material type keyword, e.g., 'Standard', 'URP', 'HDRP' (optional).")] public string MaterialTypeKeyword { get; set; } [McpToolArgument("search_in_all_scenes", typeof(bool), "If true, searches across all open scenes and prefabs (slower). Default is false.")] public bool SearchInAllScenes { get; set; } = false; } [McpToolArgument("params", typeof(SearchParameters), "The search criteria.")] public SearchParameters Params { get; set; } [McpToolExecute] public McpToolResult Execute() { // 参数验证 if (Params == null || (string.IsNullOrEmpty(Params.ShaderNamePart) && string.IsNullOrEmpty(Params.MaterialTypeKeyword))) { return McpToolResult.Error("At least one search criterion (shader_name_part or material_type) must be provided."); } // ... 实现更复杂的搜索逻辑 ... // 可以根据 Params.SearchInAllScenes 决定是否遍历所有场景 // 可以根据 Params.MaterialTypeKeyword 检查材质的关键字或自定义属性 } }

这样，AI就可以发送结构化的JSON参数来调用工具，表达能力大大增强。

4.2 异步操作与长时任务处理

有些工具操作可能很耗时，比如批量导入资产、烘焙光照。我们不能阻塞主线程。MCP工具支持异步方法。

[McpTool("async_texture_processor", "Processes textures asynchronously.")] public class AsyncTextureProcessorTool : IMcpTool { [McpToolArgument("texture_folder_path", typeof(string), "Path to the folder containing textures.")] public string FolderPath { get; set; } [McpToolExecute] public async Task<McpToolResult> ExecuteAsync() // 返回Task，并使用async { if (!Directory.Exists(FolderPath)) { return McpToolResult.Error("Folder does not exist."); } // 报告进度（如果AI客户端支持进度通知） // 模拟一个长时间任务 var textures = Directory.GetFiles(FolderPath, "*.png"); for (int i = 0; i < textures.Length; i++) { // 使用Unity的异步API或Task.Run将耗时操作放到后台线程 await Task.Run(() => ProcessSingleTexture(textures[i])); // 可以更新进度，这里简化处理 Debug.Log($"Processed {i+1}/{textures.Length}: {textures[i]}"); // 注意：Unity主线程相关的操作（如AssetDatabase.Refresh）需要回到主线程执行 // await Task.Delay(100); // 模拟延迟 } return McpToolResult.Ok($"Successfully processed {textures.Length} textures."); } private void ProcessSingleTexture(string path) { // 模拟处理逻辑，例如调整尺寸、格式转换 Thread.Sleep(50); // 模拟耗时 } }

重要提示：在Unity中执行异步操作时，涉及编辑器API（如AssetDatabase,EditorUtility）的调用必须在主线程。可以使用await Task.Run(() => { /* CPU密集型工作 */ })处理计算，然后用await UniTask.SwitchToMainThread()（如果使用UniTask）或通过EditorApplication.delayCall将UI更新操作派发回主线程。

4.3 错误处理与用户反馈

健壮的工具必须有良好的错误处理。除了返回McpToolResult.Error，还应该记录详细的日志。

[MpcToolExecute] public McpToolResult Execute() { try { // 业务逻辑 if (someCondition) { throw new InvalidOperationException("Specific error condition occurred."); } // ... return McpToolResult.Ok("Success!"); } catch (System.Exception ex) { // 记录详细的异常信息到Unity控制台，方便开发者调试 Debug.LogError($"[MCP Tool - {this.GetType().Name}] Execution failed: {ex.Message}\n{ex.StackTrace}"); // 返回给AI用户的信息可以更友好，避免暴露内部堆栈 return McpToolResult.Error($"Operation failed due to: {ex.Message}. Please check the Unity Console for details."); } }

同时，对于需要用户确认的操作（如删除文件、修改关键设置），工具不应该直接执行。最佳实践是让工具返回一个需要“确认”的指令或生成一个预览，然后由AI客户端引导用户进行二次确认。这符合MCP协议的安全设计哲学。

5. 调试、排查与性能优化实录

在实际开发和集成中，你肯定会遇到各种问题。以下是我踩过坑后总结的排查清单和优化建议。

5.1 常见问题与排查流程

当你发现AI客户端无法调用工具，或者调用后无反应时，可以按照以下流程排查：

5.2 性能优化要点

MCP工具运行在编辑器内，性能不佳会直接影响开发体验。

1. 缓存是金：对于频繁查询且不常变化的数据（如项目资产列表、Shader列表），考虑在工具类内部或静态类中缓存结果。例如，第一次搜索材质后，可以将结果缓存起来，并监听AssetDatabase的onPostprocessAllAssets事件来使缓存失效。
2. 分帧与异步：对于遍历成千上万个资产的操作，必须分帧或异步执行。可以使用EditorApplication.update事件来分割任务，或者直接使用async/await配合Task.Run（注意线程安全）。
3. 精简返回数据：AI客户端处理大量数据可能变慢。只返回必要的信息。例如，查找材质时，先返回数量和概要，如果AI需要详情，再提供另一个工具来获取具体列表。
4. 避免频繁Ping或选中对象：EditorGUIUtility.PingObject和Selection.activeObject会触发编辑器UI更新，频繁调用会导致卡顿。批量操作时，可以累积对象，最后一次性Ping或仅输出日志。

5.3 日志与监控

强大的日志是调试的生命线。

• 工具侧：使用Debug.Log、Debug.LogWarning、Debug.LogError分级输出信息，并加上工具名前缀便于过滤，例如Debug.Log($"[MCP-Tool-Finder] Starting search for shader: {TargetShaderName}")。
• 中继侧：定期查看~/.unity/relay/logs/下的日志。你可以修改中继的日志级别（如果config.json支持）来获得更详细的通信报文，这对理解MCP协议交互非常有帮助。
• 使用Unity的Editor Log：在macOS上可以通过Console.app查看所有系统日志，过滤unity进程；在Windows上可以使用第三方工具或查看Unity编辑器自己的Log文件。这里可以看到更底层的错误。

6. 超越基础：探索MCP工具的无限可能

掌握了创建基础工具的方法后，你的思维可以发散开来。MCP协议的精髓在于“连接”，它可以将AI的能力注入到工作流的任何一个环节。

场景一：自动化性能诊断结合Unity Performance Testing API，创建一个MCP工具。AI可以命令它：“对当前场景运行一次性能分析，找出DrawCall最高的前五个材质，并给出优化建议。” 工具自动启动性能测试套件，收集数据，分析后直接返回结构化的报告和建议。

场景二：智能资产管道当美术同学上传一批新模型时，AI可以调用MCP工具：“检查Assets/Art/Characters目录下所有新导入的FBX文件，自动配置合理的材质球（使用URP Lit Shader），生成LOD，并添加到指定的Addressables组中。” 工具将原本需要多步手动操作的工作流自动化。

场景三：实时工作流助手在编写Shader时，你可以对AI说：“将我当前打开的这个Shader文件中的#pragma multi_compile_fog指令替换为#pragma multi_compile_fog _，并保存。” AI通过MCP工具，可以直接读取、修改并保存你正在编辑的脚本文件。

与外部系统集成：MCP协议是通用的。你的Unity MCP工具甚至可以作为一个网关，去调用外部的REST API、数据库，或者像蓝湖、Figma这样的设计协作平台（即“蓝湖MCP”、“Figma MCP”的概念）。例如，创建一个工具，让AI能够从蓝湖获取最新的设计标注，并自动在Unity中创建对应的UI布局。

安全边界提醒：能力越大，责任越大。在设计具有破坏性操作（如删除文件、修改版本控制）的工具时，务必遵循“只读优先”、“预览先行”、“需显式确认”的原则。MCP的连接安全设置（如直接连接需用户批准）是第一道防线，你的工具逻辑是第二道。永远假设AI可能会误解你的意图，因此工具自身要内置安全检查和回滚机制。

从解剖~/.unity/relay/目录开始，到亲手实现一个能解决实际问题的工具，这个过程让我深刻体会到，Unity MCP不仅仅是一个功能，更是一种新的开发范式。它降低了AI与复杂创作工具之间的集成门槛。未来，随着MCP协议的普及，我们或许会看到一个由无数个细粒度、可组合的MCP工具构成的生态，而你和我的自定义工具，也将成为这个生态中有价值的一部分。