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 とコーディングエージェントをローカルの cm CLI に接続します。エージェントがソース管理ワークスペースの状態を確認し、変更を準備し、ブランチやラベルを作成し、ガード付きチェックインを実行し、任意のシェルアクセスを使わずにマージを行えるよう支援します。

現在のリリース：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 を使用し、ステータス、保留中の変更、ブランチ、ラベル、チェックイン、ロック、差分、マージなどのソース管理ワークフローに重点を置いています。

本番環境向けクイックスタート

1 つのワークスペースでは、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 支援によるインストール

GitHub リポジトリの URL からこの MCP サーバーをインストールするよう、AI IDE に依頼してください。

例：

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

OS 別の手動セットアップ

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 では、GUI クライアントがシェルの PATH を継承しないため、これは重要です。そのため init は絶対パスを UVCS_CM_PATH として書き込みます。

init は書き込み前にすべての対象を検証します。不正な形式の設定ファイルまたは JSONC 設定ファイルがある場合、--skip-invalid を渡さない限り、何も書き込まずに実行を中止します。--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 レジストリ

このサーバーは、公式の MCP Registry に io.github.ProAnima/uvcs-mcp として登録されています。レジストリを読み取るクライアントやディレクトリからインストールできますが、ローカルの 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 アノテーションが付与されているため、クライアントは読み取りを自動承認し、書き込みには承認を求めることができます。
• チェックインでは、追跡対象の保留中の変更をすべて対象にするか、指定した paths のみを対象にします。パスを指定したチェックインでは、選択された各 Unity アセットの .meta ファイルも追加され、その .meta ファイルがまだプライベートなアセットは拒否されます。
• 競合のあるマージは、準備時と確認時の両方で拒否されます。そのため、プレビューで競合が報告された場合に uvcs_merge がマージを開始することはありません。
• cm がオプションとして解釈する項目パス、ブランチ名、ラベル名（先頭が - のもの）は拒否されます。また、項目パスにワイルドカード * または ? は使用できません。
• 書き込みの確認はワークスペースごと、および MCP プロセス間で直列化されます。また、switch、merge、update、undo、checkout、release checkout、checkin では、準備後にワークスペースの状態が再検証されます。
• cm はシェルを使わず、標準入力を閉じた状態で、読み取りと書き込みそれぞれに個別のタイムアウトと出力上限を設定して実行されます。
• リポジトリの削除、リポジトリ名の変更、任意の cm コマンド、任意のシェル実行、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）、シェルブ、または2つのチェンジセットやラベル間で追加、変更、移動、削除された項目を一覧表示し、対応する .meta がないまま追加、移動、削除された Unity アセット（およびその逆）を通知します。
• uvcs_revision_diff は、チェンジセットのファイル1つ、2つのリビジョン間、またはワークスペースのコピーとの統合形式の行差分を返します。
• 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）を受け付けます。

エージェントスキル

このパッケージには、Claude Code、Codex、Cursor、OpenCode、Gemini CLI、その他の SKILL.md 対応エージェントに、準備／確認のワークフローや Unity の .meta ルールを含め、これらのツールをいつ、どのように使うかを教えるエージェントスキル（SKILL.md）が含まれています。

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

すべてのエージェント、プロジェクト単位のインストール、マーケットプレイス ZIP については、エージェントスキルを参照してください。

複数のワークスペース

フリートマニフェストを使って、最大50個の名前付きワークスペースに対応する1つの MCP サーバーを設定できます。

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

templates/fleet/workspaces.example.json をひな形として使用してください。安全性プロファイルと、推奨される「すべて準備してから個別に確認する」ワークフローについては、マルチワークスペースとフリート運用を参照してください。

フリートモードでは、すべてのツール呼び出しに明示的な workspace セレクターが必要です。ワークスペースごとに1つの MCP プロセスを使う場合に限り、--fleet-layout=isolated を使用してください。

クライアントを再起動する前に、設定した各ワークスペースを検証してください。

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

大規模な作業では、まず対象をすべて調査し、すべての書き込みを準備して、統合プランを1つ提示してから、各ワークスペースを個別に確認してください。リポジトリをまたぐ操作はアトミックではありません。

開発

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
• 自動化のスタイル
• 本番環境への準備
• トラブルシューティング
• エージェント向けルール
• エージェントスキル
• 貢献
• サポート
• Wiki ソース
• 変更履歴

メンテナー

Ian Panaev、ProAnimaStudio、2026年。連絡先：[email protected].