Unity MCP 遥测机制全解析隐私保护、数据采集、退出机制与源码级实现【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp本指南基于 Unity MCP 仓库中的官方架构文档 website/docs/architecture/telemetry.md系统讲解 Unity MCP 内建遥测系统的设计原则、采集范围、退出机制、本地存储与传输实现并结合 Server/src/core/telemetry.py、MCPForUnity/Editor/Helpers/TelemetryHelper.cs 等源码与测试用例进行纵深剖析。读完本文你将掌握 Unity MCP 遥测的完整工作原理、三种退出方式以及如何在 Python Server 与 Unity 编辑器两侧自定义遥测事件。遥测系统的设计初衷与四大原则Unity MCPMCP for Unity是连接 AI 助手与 Unity 编辑器的桥梁工具执行频率、成功率、场景操作分布等数据对产品质量提升至关重要。为此项目内置了一套遥测系统其官方文档明确了四条核心原则见 telemetry.md匿名Anonymous使用随机生成的 UUID 标识安装实例不携带任何个人信息非阻塞Non-blocking遥测在任何情况下都不干扰 Unity 工作流易退出Easy opt-out通过环境变量或 Unity 编辑器设置即可一键关闭透明Transparent所有采集的数据类型都在文档中公开列明。从源码实现看这四条原则并非口号。在 telemetry.py 的record()方法中事件通过queue.put_nowait()非阻塞入队队列满时直接丢弃并记录 debug 日志发送失败也仅记录日志绝不抛出影响主流程的异常。整条链路贯彻了fail-safe的设计思想。采集范围收集什么不收集什么使用分析Usage Analytics工具使用情况Tool Usage记录了哪些 MCP 工具被调用如manage_script、manage_scene等性能指标Performance工具执行耗时与成功/失败率系统信息System InfoUnity 版本、运行平台Windows/Mac/Linux、MCP 版本号里程碑事件Milestones首次使用类事件如首次创建脚本、首次调用工具等。技术诊断Technical Diagnostics连接事件Connection EventsBridge 启动、连接成功或失败错误报告Error Reports脱敏后的错误消息截断至 200 字符服务健康Server Health启动时间、连接延迟。明确不收集的内容❌ 你的代码或脚本内容❌ 项目名称、文件名或路径❌ 个人信息或标识符❌ 敏感项目数据❌ IP 地址HTTP 请求所需的最小范围除外源码层面对不收集代码内容有硬性约束record_tool_usage()中错误消息被强制截断为 200 字符str(error)[:200]record_failure()截断为 500 字符见 telemetry.py从结构上杜绝了长文本泄露的可能性。如何退出遥测三种方式详解方式一环境变量推荐官方文档推荐设置以下任一环境变量为true即可全局禁用# 禁用全部遥测 export DISABLE_TELEMETRYtrue # MCP for Unity 专用 export UNITY_MCP_DISABLE_TELEMETRYtrue # MCP 协议级通用开关 export MCP_DISABLE_TELEMETRYtrue从源码看这一开关同时作用于 Python Server 与 Unity 编辑器两侧。Python 侧在 telemetry.py 的_is_disabled()中依次检查DISABLE_TELEMETRY、UNITY_MCP_DISABLE_TELEMETRY、MCP_DISABLE_TELEMETRY三个变量且取值识别范围更宽——true、1、yes、on均视为关闭Unity 侧在 TelemetryHelper.cs 的IsEnabled属性中同样检查这三个环境变量。两端的判定逻辑保持了一致性。方式二Unity 编辑器设置Coming Soon官方文档标注该入口即将推出Window MCP for Unity Settings Disable Telemetry。虽然菜单入口尚未开放但底层能力已经就绪——TelemetryHelper提供了DisableTelemetry()/EnableTelemetry()方法将布尔值写入MCPForUnity.TelemetryDisabled这个 EditorPrefs 键见 EditorPrefKeys.cs。IsEnabled在环境变量检查通过后还会读取EditorPrefs.GetBool(MCPForUnity.TelemetryDisabled, false)作为最终开关说明编辑器 UI 只需接入现有 API 即可生效。方式三MCP 客户端配置如果你的 MCP 客户端通过配置文件启动 Server可以在配置的env段注入环境变量{ env: { DISABLE_TELEMETRY: true } }注意方式三本质上是方式一的落地形式——MCP 客户端启动子进程时注入环境变量Server 进程启动后即被_is_disabled()捕获。技术实现从采集到传输的完整链路整体架构官方文档给出的架构分工为Python Server核心遥测采集与传输Unity Bridge从 Unity 编辑器侧进行本地事件采集匿名 UUID按安装实例生成用于聚合分析线程安全后台线程非阻塞传输容错Fail-safe任何错误都不会中断工作流。实际代码将这条链路实现为两个独立的采集源最终都汇聚到同一个遥测端点。Python Server 侧TelemetryCollector 单例与后台 Workertelemetry.py 中的TelemetryCollector是核心采集类初始化时加载持久化数据UUID 与里程碑随后启动一个守护线程daemonTrue作为唯一的后台 Workerrecord()将TelemetryRecord通过put_nowait()放入容量为 1000 的有界队列非阻塞且队列满时静默丢弃Worker 循环每 0.5 秒取一条记录调用_send_telemetry()发送天然串行化所有请求。模块还提供了全局单例get_telemetry()与便捷函数record_telemetry()、record_milestone()、record_tool_usage()、record_resource_usage()、record_latency()、record_failure()见 telemetry.py。测试 test_telemetry_queue_worker.py 验证了队列背压行为50 次快速record()调用在队列满载时仍能于 500ms 内全部返回不阻塞且确认整个 Collector 只存在一个 Worker 线程。RecordType枚举定义了九类记录VERSION、STARTUP、USAGE、LATENCY、FAILURE、RESOURCE_RETRIEVAL、TOOL_EXECUTION、UNITY_CONNECTION、CLIENT_CONNECTION见 telemetry.py。工具装饰器零侵入埋点为了让 44 个工具服务类位于 Server/src/services/tools与资源服务都获得遥测能力项目提供了telemetry_tool与telemetry_resource两个装饰器见 telemetry_decorator.py同步与异步包装器自动记录工具名、成功标志、耗时毫秒、错误信息通过inspect.signature().bind_partial()智能提取action参数作为sub_action如manage_scene的get_hierarchy、save使分析粒度细化到子操作在manage_script且action create时触发FIRST_SCRIPT_CREATION里程碑manage_scene*工具触发FIRST_SCENE_MODIFICATION里程碑任何工具首次成功执行触发FIRST_TOOL_USAGE里程碑。装饰器统一在注册入口应用telemetry_tool(tool_name)在 Server/src/services/tools/init.py 与 Server/src/services/custom_tool_service.py 中包装内置工具与自定义 Python 工具telemetry_resource在 Server/src/services/resources/init.py 中包装资源。测试 test_telemetry_subaction.py 验证了关键字参数与位置参数两种调用方式下sub_action的提取结果以及无action参数时优雅降级为None。Unity 编辑器侧TelemetryHelper 轻量桥Unity 侧不直接联网发送而是扮演轻量桥角色。 TelemetryHelper.cs 提供RecordBridgeStartup()记录 Bridge 启动事件附带包版本与自动连接模式RecordBridgeConnection(success, error)记录连接结果错误同样截断至 200 字符RecordToolExecution(toolName, success, durationMs, error)记录工具执行GetCustomerUUID()从 EditorPrefs键MCPForUnity.CustomerUUID读取或生成匿名 UUIDRegisterTelemetrySender()供传输层注册实际的发送委托未注册时仅输出 debug 日志兜底。这些事件在 StdioBridgeHost.cs 等传输宿主中触发最终经由 MCP Server 统一处理与传输印证了文档中Unity Bridge 负责本地采集、Python Server 负责传输的分工。本地数据存储遥测数据按平台存储在系统标准数据目录下Windows%APPDATA%\UnityMCP\macOS~/Library/Application Support/UnityMCP/Linux~/.local/share/UnityMCP/遵循XDG_DATA_HOME见 telemetry.py目录下生成两个文件customer_uuid.txt匿名标识符POSIX 系统下以0o600权限写入以保护隐私milestones.json一次性事件追踪器记录每个里程碑首次发生的时间戳与附加数据。源码还处理了持久化文件的健壮性即使milestones.json损坏如测试中写入{not-json}UUID 也会保持不变两者解耦加载见 test_telemetry_endpoint_validation.py。数据传输端点、超时与校验官方文档列出的传输规格为端点https://api-prod.coplay.dev/telemetry/events方法HTTPS POSTJSON 载荷重试后台线程优雅失败不重试超时10 秒超时失败不重试源码中的细节更丰富默认超时实际为1.5 秒可通过UNITY_MCP_TELEMETRY_TIMEOUT覆盖main.py 在 Server 启动时会自动将其提升为 5.0 秒除非用户显式设置端点可通过UNITY_MCP_TELEMETRY_ENDPOINT环境变量或 config.py 中的telemetry_endpoint配置覆盖配置优先级为config 优先、env 显式覆盖_validated_endpoint()会对端点做安全校验仅允许http/https协议、必须有 netloc、禁止 localhost/127.0.0.1/::1非法值回退到默认端点见 telemetry.py对应测试 test_telemetry_endpoint_validation.py 验证了file:///etc/passwd这类非 HTTP 端点会被拒绝发送时优先使用httpx不可用时回退到标准库urllib载荷会附加platform_detail如Linux 5.15.0 (x86_64)与python_version字段便于 BigQuery 分析端做细粒度聚合而无需改表结构。数据用途、保留策略与开发边界数据用于什么官方文档明确数据仅用于产品改进与开发决策产品改进了解工具使用分布、识别慢操作、跟踪错误率与连接问题、确保 Unity 版本兼容性开发优先级根据功能使用频率决定 Roadmap、按错误频率排序 Bug 修复、按平台使用率分配资源、针对问题高发区改进文档。明确不做的事❌ 向第三方出售数据❌ 用于广告/营销❌ 追踪单个开发者❌ 存储敏感项目信息保留策略聚合数据无限期保留用于产品洞察原始事件90 天后自动清除个人数据不采集故无需清除退出生效一旦退出立即停止上报后续不再发送任何数据。开发者扩展自定义遥测事件与状态查询官方文档提供了两个开发 API 示例注意原文档代码示例存在遗漏缺少from关键字此处给出修正后可直接运行的版本from core.telemetry import record_telemetry, RecordType record_telemetry(RecordType.USAGE, { custom_event: my_feature_used, metadata: optional_data })from core.telemetry import is_telemetry_enabled if is_telemetry_enabled(): print(Telemetry is active) else: print(Telemetry is disabled)更贴近业务的做法是直接使用语义化便捷函数工具执行用record_tool_usage(tool_name, success, duration_ms, error, sub_action)资源读取用record_resource_usage(...)性能监控用record_latency(operation, duration_ms, metadata)异常上报用record_failure(component, error, metadata)用户旅程里程碑用record_milestone(MilestoneType.FIRST_STARTUP, data)。MilestoneType枚举还预置了DAILY_ACTIVE_USER、WEEKLY_ACTIVE_USER、MULTIPLE_SESSIONS等活跃度指标见 telemetry.py便于长期留存分析。典型遥测事件示例与自检清单官方文档给出的标准事件载荷如下{ record: tool_execution, timestamp: 1704067200, customer_uuid: 550e8400-e29b-41d4-a716-446655440000, session_id: abc123-def456-ghi789, version: 3.0.2, platform: posix, data: { tool_name: manage_script, success: true, duration_ms: 42.5 } }对照源码可确认其字段构成见 telemetry.py顶层包含记录类型、Unix 时间戳、匿名 UUID、会话 UUID每次进程启动随机生成、MCP 包版本优先取安装元数据Git 方式安装则回退读取 pyproject.toml见 telemetry.py、平台与数据体若事件属于里程碑还会附加milestone字段。自检清单✅ 匿名 UUID随机生成与安装实例绑定✅ 工具性能指标duration_ms保留两位小数✅ 成功/失败追踪❌ 无代码内容❌ 无项目信息❌ 无个人数据隐私合规建议与延伸阅读结合本文与源码给使用者的隐私合规建议可归纳为三点其一若在团队或企业环境统一部署推荐在 MCP 客户端配置的env段写入DISABLE_TELEMETRYtrue从进程源头关闭其二若需审计三个退出环境变量与MCPForUnity.TelemetryDisabledEditorPrefs 键均可作为配置审计点其三遥测端点与超时可通过UNITY_MCP_TELEMETRY_ENDPOINT、UNITY_MCP_TELEMETRY_TIMEOUT按需调整而端点校验逻辑拒绝 localhost防止误配导致数据流向本地代理。如需继续深入可进一步阅读官方架构文档 website/docs/architecture/telemetry.md、Server 端实现 Server/src/core/telemetry.py 与装饰器 Server/src/core/telemetry_decorator.py、Unity 编辑器侧 MCPForUnity/Editor/Helpers/TelemetryHelper.cs以及验证遥测行为的测试用例 test_telemetry_endpoint_validation.py、test_telemetry_queue_worker.py 和 test_telemetry_subaction.py。整个遥测代码均在仓库内开源任何数据采集行为都可被追溯审查。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考