Unity MCP 仓库级manifest.json参考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导读manifest.json是 unity-mcp 仓库根目录下的一份包级描述文件它把 Unity MCP 作为一个独立于 Unity UPM 生态的软件包呈现给 MCP 市场Marketplace与各类聚合器Aggregator供其读取项目元数据、掌握 Python 服务器的启动方式、索引可用的工具目录。本文将逐字段拆解这份清单从顶层元数据、server启动块、tools工具数组到它与MCPForUnity/package.json、Server/pyproject.toml三份清单文件的职责边界再到基于它生成.mcpb分发包的打包脚本。读完本文你将能够读懂并维护一份可被 MCP 市场正确识别的manifest.json理解uvx启动链路的背后逻辑并清楚在新增 MCP 工具时哪些表面需要同步更新。说明本文所述字段、取值与行为均以当前仓库实际内容为准。仓库处于只读状态文中所有路径均为查看/参考用途。一、manifest.json的定位仓库级包描述而非 UPM 清单仓库根目录的 manifest.json 描述的是MCP for Unity 这个包本身——它服务的对象是 MCP 生态中的市场与聚合器而不是 Unity 的 Package Manager。它在项目中的角色可以从三点理解独立于 Unity UPM 清单Unity 侧真正的包描述文件是 MCPForUnity/package.json包名为com.coplaydev.unity-mcp两者互不隶属。manifest.json不参与 Unity 的导入、依赖解析流程。面向 MCP 生态MCP 市场与聚合器通过它展示项目的展示名、版本、作者、仓库地址、图标以及最关键的两块——服务器如何启动server块与暴露了哪些工具tools数组。与文档生成联动文档明确提醒新增 MCP 工具时应当同步更新 工具注册表即mcp_for_unity_tool装饰器体系CI 的 drift 检查会让任何过期条目直接失败——生成器 tools/generate_docs_reference.py 负责保持参考文档与注册表同步。而manifest.json中的tools块则是独立、手工维护的一个表面详见本文第四节。当前仓库根目录的manifest.json正是文档所述的最新一份也是所有市场消费的权威入口。二、顶层字段一份市场清单的元数据骨架manifest.json顶层字段覆盖了市场展示所需的全部基础信息字段表如下字段类型说明manifest_versionstring本清单的 schema 版本当前为0.3namestring聚合器展示用的名称versionstring当前发布版本的 SemVerdescriptionstring一句话产品描述author.namestring维护者展示名author.urlstring维护者网站repository.typestring固定为gitrepository.urlstring仓库规范 URLhomepagestring项目主页documentationstring文档落地页 URLsupportstring提交 issue 的入口iconstring方形图标路径相对于 manifest 所在目录对照当前仓库 manifest.json 的实际取值manifest_version为0.3version为10.2.0name为Unity MCP可以看到icon字段填的是coplay-logo.png——一个相对路径指向 manifest 同目录下的图标文件仓库中为coplay-logo.png打包时它会被单独拷贝进分发包见本文第六节。description字段值得注意它在仓库中写为 AI-powered Unity Editor automation via MCP - manage GameObjects, scripts, materials, scenes, prefabs, VFX, and run tests这既是市场搜索的关键词来源也与 MCPForUnity/package.json 中偏桥梁定位的描述A bridge that connects AI assistants to Unity via the MCP形成互补视角。三、server块告诉市场如何拉起 Python 服务器server块是manifest.json中最具操作性的部分它直接决定一个聚合器拿到清单后能否把服务跑起来。文档给出的标准形态如下server: { type: python, entry_point: Server/src/main.py, mcp_config: { command: uvx, args: [--from, mcpforunityserver, mcp-for-unity], env: {} } }各子字段语义type—— 运行时族当前恒为python。entry_point—— 若聚合器不借助uvx需要把 Python 解释器指向的入口文件即 Server/src/main.py。mcp_config.command—— 推荐的启动命令。选择uvx的意义在于依赖树由 uv 托管无需全局安装即可按需运行--from mcpforunityserver指定了 PyPI 上的发行包名。mcp_config.args—— 调用参数即实际执行mcp-for-unity命令默认走http传输如需切换到 stdio 则追加--transport stdio。mcp_config.env—— 启动前设置的环境变量遥测开关、日志级别等当前为{}。3.1 源码印证mcp-for-unity命令的真实形态args中的mcp-for-unity并非虚构命令它由 Server/pyproject.toml 的[project.scripts]段声明[project.scripts] mcp-for-unity main:main unity-mcp cli.main:main即mcp-for-unity指向main:mainServer/src/main.py 的main()这正是uvx --from mcpforunityserver mcp-for-unity最终执行的目标。进入main()后传输模式由--transport/UNITY_MCP_TRANSPORT决定源码中config.transport_mode args.transport or os.environ.get(UNITY_MCP_TRANSPORT, stdio) ... if config.transport_mode http: mcp.run(transporthttp, hosthost, portport) else: mcp.run(transportstdio)这与文档默认传输是http传--transport stdio可切换的表述一致——注意命令行层面的默认行为以 Server/src/main.py 中--transport的defaultstdio为准同时它也接受UNITY_MCP_TRANSPORT、UNITY_MCP_HTTP_URL、UNITY_MCP_HTTP_HOST、UNITY_MCP_HTTP_PORT、UNITY_MCP_DEFAULT_INSTANCE、UNITY_MCP_SKIP_STARTUP_CONNECT、UNITY_MCP_TELEMETRY_ENABLED等环境变量这些均可放入mcp_config.env中以注入启动上下文。从源码结构看main()还会依据传输模式做工具可见性预同步stdio 下通过get_tool_states向 Unity 查询工具开关状态这解释了为什么env中遥测与日志相关变量对启动行为有直接影响。四、tools块面向市场的扁平工具目录tools是一组扁平的{ name, description }条目数组逐一列出服务器暴露的 MCP 工具。聚合器用它构建搜索与分类界面无需内省实时注册表即可获得全量工具概览。当前 manifest.json 中共收录43 个工具覆盖场景/脚本/资源/物理/UI/VFX/Profiler 等模块例如tools: [ { name: apply_text_edits, description: Apply text edits to script content }, { name: batch_execute, description: Execute multiple Unity operations in a single batch }, { name: execute_code, description: Execute arbitrary C# code inside the Unity Editor with access to all Unity APIs }, { name: manage_gameobject, description: Create, modify, transform, and delete GameObjects }, { name: manage_scene, description: Load, save, query hierarchy, multi-scene editing, templates, validation, and manage Unity scenes }, { name: manage_physics, description: Manage 3D and 2D physics: settings, collision matrix, materials, joints, queries (raycast, shapecast, linecast, overlap), forces, rigidbody configuration, validation, and simulation }, { name: run_tests, description: Run Unity Test Framework tests }, { name: unity_reflect, description: Inspect Unity C# APIs via live reflection } ]4.1 手工维护表面 vs 权威注册表文档特别强调这份列表目前是手工维护的。工具的数量与元数据的权威来源在 Python 工具注册表——即 Server/src/services/registry/tool_registry.py 中的mcp_for_unity_tool装饰器体系。该装饰器在导入时把{ func, name, description, unity_target, group, kwargs }追加进全局_tool_registry随后 Server/src/services/tools/init.py 的register_all_tools()通过discover_modules()自动发现tools/目录下所有模块并完成注册配合telemetry_tool/log_execution装饰器栈后交给mcp.tool()。因此manifest.json的tools数组与注册表之间是摘要 vs 详情的关系工具是否存在以 Server/src/services/registry/tool_registry.py 的注册结果为准当前tools/目录含 44 个.py文件其中 43 个注册为工具另有utils.py为公共工具函数完整参数文档由生成器输出到 website/docs/reference/tools/ 下的分类目录group/tool-name.md包含Annotated[...]承载的逐参数说明manifest.json中的条目只承载名称与一句话描述供市场做检索与分类。4.2 分组与可见性为什么市场看不到全部工具从源码看工具还带有分组元数据。tool_registry.py定义了TOOL_GROUPScore、docs、vfx、animation、ui、scripting_ext、testing、probuilder、profiling、asset_gen装饰器通过tags{group:name}写入 FastMCPDEFAULT_ENABLED_GROUPS {core}意味着默认会话只暴露核心组其他组由manage_tools元工具按需激活HTTP 模式下服务启动时会mcp.disable(tags...)关闭非默认组。manifest.json的tools数组不受分组可见性影响它列的是完整目录这一点在维护时需要注意与运行时会话中实际可见工具集合的差异。五、Notes三份清单文件的职责边界文档用一组 Notes 厘清了最容易混淆的三个元数据表面这是维护者必读的部分manifest.json不是 Unity UPM 清单。UPM 清单是 MCPForUnity/package.json其name为com.coplaydev.unity-mcp同时声明unity: 2021.3、Newtonsoft JSON 与 test-framework 等运行时依赖供 Unity Package Manager 导入使用。Python PyPI 包元数据在 Server/pyproject.toml包名为mcpforunityserverrequires-python 3.10依赖fastmcp、mcp、pydantic、httpx、fastapi、uvicorn、click等。三者相互独立但字段重叠name、version、description、author在三份文件中都有但取值语境不同Unity MCP/com.coplaydev.unity-mcp/mcpforunityserver。一次重命名要同时改三处——例如包名变更必须同步 UPM 包名、PyPI 发行名与uvx --from参数。MCPB 包从manifest.json生成工具脚本为 tools/generate_mcpb.py详见下节。简化的对应关系如下表面文件路径服务对象包名仓库级清单manifest.jsonMCP 市场/聚合器Unity MCPUPM 包清单MCPForUnity/package.jsonUnity Package Managercom.coplaydev.unity-mcpPyPI 发行元数据Server/pyproject.tomlpip / uv / PyPImcpforunityserver六、分发用generate_mcpb.py产出 MCPB 包MCPBModel Context Protocol Bundle是便于市场下载分发的打包形态其唯一输入模板就是根目录的manifest.json。脚本 tools/generate_mcpb.py 的用法为python3 tools/generate_mcpb.py VERSION [--output FILE] [--icon PATH]典型示例python3 tools/generate_mcpb.py 10.2.0 python3 tools/generate_mcpb.py 10.2.0 --output unity-mcp-10.2.0.mcpb python3 tools/generate_mcpb.py 10.2.0 --icon docs/images/coplay-logo.png脚本执行流程对应 tools/generate_mcpb.py 的generate_mcpb()读取根目录manifest.json作为模板用传入的VERSION覆盖version字段create_manifest()在临时目录中建立mcpb-build拷贝图标文件默认取docs/images/coplay-logo.png最终以coplay-logo.png之名进入包内与icon字段对应将改写后的manifest.json写入构建目录并把LICENSE、README.md一并拷贝调用npx anthropic-ai/mcpb pack . output完成打包因此本机需要 Node.js/npm 环境缺npx时脚本会明确报错提示安装校验产物存在后输出大小信息例如Generated: unity-mcp-10.2.0.mcpb (x,xxx bytes)。默认输出名为unity-mcp-VERSION.mcpb。若打包失败如图标缺失、npx不可用脚本以非零退出码返回方便 CI 捕获。七、同步机制文档生成与 drift 检查文档首段提到的CI drift check由 tools/generate_docs_reference.py 承担。该生成器的设计要点是单一事实来源Python 侧mcp_for_unity_tool/mcp_for_unity_resource注册表是唯一权威C# 属性只携带 Name/Group/DescriptionPython 装饰器持有最丰富的类型注解Annotated[...]参数文档即 MCP 客户端在线路上真正看到的内容。输出website/docs/reference/tools/group/tool-name.md每个工具一页、组落地页与目录页以及website/docs/reference/resources/index.md资源目录。两种模式--write原地重生成--check先输出到临时目录再与已提交文件 diff存在差异即以非零退出码失败——这正是 CI / pre-commit 中拦截新增工具但文档过期的机制。示例保护手写的示例块!-- examples:start --/!-- examples:end --之间在重生成时会被保留避免自动覆盖破坏人工补充的用例。对应地manifest.json的tools数组走的是另一条手工维护的路径新增工具后需要同时a注册 Python 装饰器、b让generate_docs_reference.py --check通过、c手工在manifest.json的tools数组补一条{ name, description }三者缺一不可。八、常见操作与维护清单结合全文日常维护manifest.json可参考如下清单发布新版本更新versionSemVer与 MCPForUnity/package.json、Server/pyproject.toml 的版本保持一致三处相互独立需分别修改。新增工具先在 Server/src/services/tools/ 下按mcp_for_unity_tool规范实现并归入合法分组再向 manifest.json 的tools数组追加条目并保证tools/generate_docs_reference.py --check通过。修改启动方式改动server.mcp_config命令/参数/环境变量前先在本地验证uvx --from mcpforunityserver mcp-for-unity与 Server/src/main.py 的参数约定一致env字段可放入UNITY_MCP_TRANSPORT、UNITY_MCP_HTTP_URL、UNITY_MCP_TELEMETRY_ENABLED等启动期变量。制作分发包发布流程中执行python3 tools/generate_mcpb.py version产出.mcpb作为 GitHub Release 工件。更换图标更新icon字段为相对路径字符串并确保打包脚本能访问到该文件默认指向 docs/images/coplay-logo.png。结语manifest.json是 Unity MCP 在 MCP 生态中的门面它用 12 个顶层字段承载市场展示所需元数据用server块定义经uvx拉起 Python 服务器的启动链路用 43 条工具摘要构成可检索的工具目录并由 tools/generate_mcpb.py 支撑.mcpb分发包的产出。理解它与 UPM 清单、PyPI 元数据之间的三份清单协作关系以及注册表权威、manifest 摘要、文档同步的维护三角是任何想为该项目贡献新工具、新版本或新发行渠道的开发者必须具备的基础认知。【免费下载链接】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），仅供参考