UVCS MCP

UVCS MCP - Unity Version Control / Plastic SCM MCP 服务

面向 Plastic SCM、Unity Version Control 和 Unity DevOps Version Control 源代码管理工作区的安全 MCP 服务（cm 10.0.16.6656+，包括 11.x）。

UVCS MCP 通过固定的已记录 SCM 命令允许列表，将 AI IDE 和编码 Agent 连接到本地 cm CLI。它可帮助 Agent 检查源代码管理工作区状态、准备更改、创建分支和标签、执行受保护的签入，以及进行合并，而无需提供任意 shell 访问权限。

当前版本：1.4.1。支持的 cm 客户端：10.0.16.6656 及更高版本，包括 Unity Version Control / Unity DevOps Version Control 11.x。

要求

• Node.js 22 或更高版本（已在 22、24 和 26 上测试）；
• 现有的 Plastic SCM / Unity Version Control 工作区；
• cm CLI。init 会在 PATH 或标准安装目录中查找它，并写入其绝对路径；否则请传入 --cm=<path>；
• 已登录且有权访问工作区服务端的 cm 客户端。

不是 Unity Editor MCP

UVCS MCP 不是 Unity Editor 自动化服务。它不会控制场景、GameObject、Play Mode、Unity 软件包、编辑器窗口、构建或运行时对象。

它使用 Plastic SCM / Unity Version Control cm CLI，专注于源代码管理工作流：状态、待处理更改、分支、标签、签入、锁定、差异和合并。

生产环境快速入门

对于单个工作区，请从 guarded 配置文件开始：

npx -y @proanima/[email protected] init \
  --client=cursor,codex \
  --workspace="D:/Repositories/YourWorkspace" \
  --safety=guarded \
  --print-config

预览仅显示 uvcs 条目、目标文件，以及每个文件将被创建、合并还是保持不变。.cursor/mcp.json 等项目文件会写入工作区文件夹；传入 --project-dir=<folder> 可将它们写入其他位置。移除 --print-config 以应用配置，然后验证结果：

npx -y @proanima/[email protected] doctor \
  --workspace="D:/Repositories/YourWorkspace"

重启 MCP 客户端，然后调用：

uvcs_setup_status
uvcs_workspace_status
uvcs_style_setup_check

如果只需检查，请使用 readonly。只有在可信或临时工作区中，且有意不要求固定仓库标识时，才使用 standard。

将 MCP 客户端配置为仅自动批准只读工具，并在每次调用 *_confirm 工具前向你询问。请参阅客户端。

AI 辅助安装

请 AI IDE 从 GitHub 仓库 URL 安装此 MCP 服务。

例如：

Install this MCP server from https://github.com/ProAnima/unity-version-control-mcp, configure it for my Plastic SCM / Unity Version Control source-control workspace, and run uvcs_doctor.

从克隆版本安装

仅当客户端配置需要运行该检出目录，而不是 npm 软件包时，才使用克隆版本：

git clone https://github.com/ProAnima/unity-version-control-mcp.git uvcs-mcp
cd uvcs-mcp
npm ci
node src/cli.js init-local --client=cursor --workspace="D:/Repositories/YourWorkspace"

请始终传入 --workspace（或 --project-dir）：项目文件会写入工作区文件夹，且 init 拒绝将文件写入 uvcs-mcp 文件夹本身。请先使用 --print-config 预览。

重启 MCP 客户端，然后让它运行：

uvcs_doctor
uvcs_workspace_status

按操作系统手动设置

Windows：

npx -y @proanima/[email protected] init --client=cursor --workspace="D:\Repositories\YourWorkspace"

macOS：

npx -y @proanima/[email protected] init --client=cursor --workspace="$HOME/Repositories/YourWorkspace"

Linux：

npx -y @proanima/[email protected] init --client=cursor --workspace="$HOME/Repositories/YourWorkspace"

将 cursor 替换为你的客户端，或使用逗号分隔列出多个客户端。如果找不到 cm，请添加 --cm=/path/to/cm。在 macOS 上，这对图形界面客户端尤为重要，因为它们不会继承 shell 的 PATH；因此，init 会将 cm 的绝对路径写入 UVCS_CM_PATH。

init 会在写入前验证每个目标。格式错误的配置或 JSONC 配置会中止运行，且不会写入任何内容；除非传入 --skip-invalid，此时会跳过该客户端，并打印需要手动添加的条目。更改过的文件会备份为 <file>.<YYYYMMDDHHmmss>.bak；未更改的文件不会重写。运行 uvcs-mcp init --help 查看所有选项。

手动配置 MCP 区块

{
  "command": "npx",
  "args": ["-y", "@proanima/[email protected]"],
  "env": {
    "UVCS_WORKSPACE": "D:/Repositories/YourWorkspace",
    "UVCS_MCP_MODE": "readonly"
  }
}

在原生 Windows 上，npx 是 npx.cmd 启动器。Claude Code、Claude Desktop、Cursor、Codex 0.59+、Kiro 和 OpenCode 会自行解析它。对于 Antigravity 和 Windsurf / Devin Desktop，或者客户端报告 spawn npx ENOENT 时，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@proanima/[email protected]"]。请参阅客户端。

配置中介绍了每个环境变量。

MCP Registry

该服务已作为 io.github.ProAnima/uvcs-mcp 收录在官方 MCP Registry 中。读取该注册表的客户端和目录可以从中安装；不过，它仍需要本地的 cm CLI 和工作区路径（UVCS_WORKSPACE）。

支持的客户端

• Cursor（项目级和全局）
• Codex
• Claude Desktop
• Claude Code（项目 .mcp.json；init 也会输出等效的 claude mcp add --scope user 命令）
• OpenCode（项目级和全局）
• Antigravity（项目级和全局）
• Kiro（项目级和全局）
• Windsurf / Devin Desktop
• Zed（仅提供模板）

文件位置请参阅 客户端。

安全模型

• 默认模式为 readonly；无法识别的 UVCS_MCP_MODE 也会采用 readonly。
• 协议处理由官方 MCP TypeScript SDK 提供。
• 工具输入由服务端使用严格的架构进行验证。
• 写入工具需要设置 UVCS_MCP_MODE=standard。
• 每次写入都必须先调用 *_prepare，再调用对应的 *_confirm；工具带有 MCP 注解，客户端可据此自动批准读取操作，并要求批准写入操作。
• Checkin 会提交所有已跟踪的待处理更改，或仅提交指定的 paths；指定路径的 checkin 会为每个选定的 Unity 资源添加对应的 .meta 文件，并拒绝 .meta 仍为私有状态的资源。
• 如果合并存在冲突，prepare 和 confirm 阶段都会拒绝操作，因此 uvcs_merge 不会启动预览显示有冲突的合并。
• cm 会将以 - 开头的项目路径、分支名称和标签名称视为选项；此类输入会被拒绝。项目路径也不能包含通配符 * 或 ?。
• 写入确认会在每个工作区内及不同 MCP 进程之间依次执行；switch、merge、update、undo、checkout、release checkout 和 checkin 会在 prepare 后重新验证工作区状态。
• cm 在不使用 shell 且关闭 stdin 的情况下运行，并分别设置读取和写入超时及输出限制。
• 不提供删除存储库、重命名存储库、任意 cm 命令、任意 shell 执行以及原始 cm api 启动功能。
• 可通过 UVCS_AUDIT_LOG=/path/to/uvcs-mcp-audit.jsonl 启用可选的 JSONL 审计日志。

工具

• uvcs_doctor
• uvcs_policy_status
• uvcs_setup_status
• uvcs_workspace_status
• uvcs_pending_changes
• uvcs_branch_info
• uvcs_locks
• uvcs_checkout_prepare / uvcs_checkout_confirm
• uvcs_release_checkout_prepare / uvcs_release_checkout_confirm
• uvcs_unity_meta_diagnostics
• uvcs_style_rules
• uvcs_style_setup_check
• uvcs_style_init_prepare / uvcs_style_init_confirm
• uvcs_name_preview
• uvcs_release_plan
• uvcs_diff_file
• uvcs_changeset_diff
• uvcs_revision_diff
• uvcs_file_history
• uvcs_annotate
• uvcs_branch_list
• uvcs_label_list
• uvcs_merge_preview
• uvcs_cleanup_candidates
• uvcs_branch_safety_report
• uvcs_update_workspace_prepare / uvcs_update_workspace_confirm
• uvcs_changeset_analytics
• uvcs_add_prepare / uvcs_add_confirm
• uvcs_undo_prepare / uvcs_undo_confirm
• uvcs_branch_create_prepare / uvcs_branch_create_confirm
• uvcs_label_create_prepare / uvcs_label_create_confirm
• uvcs_switch_workspace_prepare / uvcs_switch_workspace_confirm
• uvcs_merge_prepare / uvcs_merge_confirm
• uvcs_checkin_prepare / uvcs_checkin_confirm

历史记录、审查和合并预览

只读工具可回答所有安全配置中的“变更了什么”问题：

• uvcs_changeset_diff 会列出变更集（cs:123）、分支（/main/task）、搁置集中的新增、变更、移动或删除项，或比较两个变更集或标签之间的差异；还会标记新增、移动或删除但缺少 .meta 的 Unity 资源（以及反向情况）。
• uvcs_revision_diff 会返回某个变更集中的单个文件、两个修订版本之间，或与工作区副本比较的统一行差异。
• uvcs_file_history 和 uvcs_annotate 会显示文件或代码行的修改者及修改时间。
• uvcs_branch_list 和 uvcs_label_list 可按名称、所有者、日期、父级或分支查找分支和标签。
• uvcs_merge_preview 会报告合并将带来哪些内容，以及哪些项存在冲突；可预览合并到工作区的结果，也可通过 destination 预览合并到服务端上的任意分支，而不会实际执行合并。

按路径检入和独占签出

• uvcs_checkin_prepare 接受 paths，可仅检入用户自己的文件或文件夹。每个选定的 Unity 资源都会连同其 .meta 文件一起处理；变更所需的新父文件夹会列为 dependencies；如果在确认前再次编辑选定文件，令牌将失效。
• uvcs_checkout_prepare 会在编辑前签出文件。如果服务端为这些文件设置了锁定规则（lock.conf），此操作会获取独占锁，以保护场景、预制件和其他二进制资源；已被他人锁定的文件将无法签出。
• uvcs_release_checkout_prepare 会释放内容未变更文件的签出状态。已修改的文件会保留签出状态及其编辑内容，直到检入为止。
• uvcs_locks 接受 paths 和 scope（all、user、workspace）。

Agent 技能

此软件包附带一项 Agent 技能（SKILL.md），用于指导 Claude Code、Codex、Cursor、OpenCode、Gemini CLI 和其他 SKILL.md Agent 何时以及如何使用这些工具，包括 prepare/confirm 工作流和 Unity .meta 规则：

npx -y @proanima/[email protected] skill install --agent=claude,agents

请参阅 Agent 技能，了解适用于所有 Agent 的说明、项目范围内的安装方式以及 marketplace ZIP。

多个工作区

使用 fleet 清单为最多 50 个具名工作区配置一个 MCP 服务：

npx -y @proanima/[email protected] init --manifest=workspaces.json --client=cursor,codex --print-config

请从 templates/fleet/workspaces.example.json 开始。请参阅多工作区和 Fleet 工作，了解安全配置和推荐的“全部 prepare、逐个 confirm”工作流。

在 fleet 模式下，每次工具调用都必须显式指定 workspace。仅当你希望每个工作区运行一个 MCP 进程时，才使用 --fleet-layout=isolated。

重启客户端前，请验证每个已配置的工作区：

npx -y @proanima/[email protected] doctor --manifest=workspaces.json

进行批量操作时，先检查每个目标，再准备所有写入操作，展示一份合并后的计划，并分别确认每个工作区。跨仓库操作不是原子操作。

开发

npm ci
npm test
npm run lint
npm run check
npm run audit:prod
npm run release:check
npm run smoke:fake
npm run smoke:fleet
npm run smoke:pack
npm run pack:skill

针对一次性或安全的工作区运行真实的 Plastic SCM 冒烟测试：

npm run smoke:plastic -- "D:/Repositories/YourWorkspace"

冒烟测试会通过 MCP 工具创建临时分支、标签、检入项并执行合并。

项目支持

• 对于可复现的错误、客户端设置问题和兼容性报告，请使用 GitHub Issues。
• 对于新的 SCM 工作流或 MCP 工具，请提交功能请求。
• 请勿在公开 Issue 中包含机密、访问令牌、私有服务端凭据或完整的专有日志。
• 如需提交安全问题报告，请参阅安全策略。

文档

• 安装
• 客户端
• 配置
• 多工作区和舰队工作
• 安全
• 安全审查
• 兼容性
• 发布
• 发布说明：1.4.1
• 发布说明：1.4.0
• 发布说明：1.3.0
• 自动化风格
• 生产就绪情况
• 故障排除
• Agent 规则
• Agent 技能
• 贡献指南
• 支持
• Wiki 源文件
• 更新日志

维护者

Ian Panaev，ProAnimaStudio，2026。联系方式：[email protected]。