企业官网建设流程全解析

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。

它在项目中的角色可以从三点理解：

1. 独立于 Unity UPM 清单：Unity 侧真正的包描述文件是 MCPForUnity/package.json（包名为com.coplaydev.unity-mcp），两者互不隶属。manifest.json不参与 Unity 的导入、依赖解析流程。
2. 面向 MCP 生态：MCP 市场与聚合器通过它展示项目的展示名、版本、作者、仓库地址、图标，以及最关键的两块——服务器如何启动（server块）与暴露了哪些工具（tools数组）。
3. 与文档生成联动：文档明确提醒，新增 MCP 工具时应当同步更新 工具注册表（即@mcp_for_unity_tool装饰器体系），CI 的 drift 检查会让任何过期条目直接失败——生成器 tools/generate_docs_reference.py 负责保持参考文档与注册表同步。而manifest.json中的tools块则是独立、手工维护的一个表面（详见本文第四节）。

当前仓库根目录的manifest.json正是文档所述的"最新一份"，也是所有市场消费的权威入口。

二、顶层字段：一份市场清单的元数据骨架

manifest.json顶层字段覆盖了市场展示所需的全部基础信息，字段表如下：

对照当前仓库 manifest.json 的实际取值（manifest_version为0.3，version为10.2.0，name为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:main（Server/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(transport='http', host=host, port=port) else: mcp.run(transport='stdio')

这与文档"默认传输是http，传--transport stdio可切换"的表述一致——注意命令行层面的默认行为以 Server/src/main.py 中--transport的default="stdio"为准，同时它也接受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_GROUPS（core、docs、vfx、animation、ui、scripting_ext、testing、probuilder、profiling、asset_gen），装饰器通过tags={"group:<name>"}写入 FastMCP，DEFAULT_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，包名为mcpforunityserver（requires-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（详见下节）。

简化的对应关系如下：

六、分发：用generate_mcpb.py产出 MCPB 包

MCPB（Model 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()）：

1. 读取根目录manifest.json作为模板，用传入的VERSION覆盖version字段（create_manifest()）；
2. 在临时目录中建立mcpb-build，拷贝图标文件（默认取docs/images/coplay-logo.png，最终以coplay-logo.png之名进入包内，与icon字段对应）；
3. 将改写后的manifest.json写入构建目录，并把LICENSE、README.md一并拷贝；
4. 调用npx @anthropic-ai/mcpb pack . <output>完成打包（因此本机需要 Node.js/npm 环境，缺npx时脚本会明确报错提示安装）；
5. 校验产物存在后输出大小信息，例如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/Description，Python 装饰器持有最丰富的类型注解（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可参考如下清单：

1. 发布新版本：更新version（SemVer），与 MCPForUnity/package.json、Server/pyproject.toml 的版本保持一致（三处相互独立，需分别修改）。
2. 新增工具：先在 Server/src/services/tools/ 下按@mcp_for_unity_tool规范实现并归入合法分组，再向 manifest.json 的tools数组追加条目，并保证tools/generate_docs_reference.py --check通过。
3. 修改启动方式：改动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等启动期变量。
4. 制作分发包：发布流程中执行python3 tools/generate_mcpb.py <version>产出.mcpb作为 GitHub Release 工件。
5. 更换图标：更新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