Skip to main content

開発環境

feature / fixはbetaからbranchを作り、beta向けPRにします。mainはstable release用です。

大きな変更は、既存Issue・Discussion・PRと重複していないか確認してから進めます。bug fixではUnity version、package source、Git URLの場合のresolved commit、実行したtestをPRへ残します。

repository構造​

  • MCPForUnity/ — Unity package。Editor UI、C# tool / resource、compatibility helper、package metadata
  • Server/ — Python MCP server、CLI、FastMCP registry、transport、server test
  • TestProjects/UnityMCPTests/ — Unity EditMode / PlayMode test project
  • website/ — Docusaurus documentation
  • tools/ — build、release、docs generation、stress / test helper
  • CustomTools/ — project-defined custom toolのexample

Python serverを準備する​

CIと同じ基本pathを使います。

cd Server
uv sync
uv pip install -e ".[dev]"
uv run pytest tests/ -v --tb=short

多くのPython unit testはUnityを起動せずに実行できます。Editor integration testはbridge接続済みUnity instanceが必要です。

local serverをUnityから使う​

  1. Window → MCP for Unity を開く
  2. Settings → Advanced Settings を開く
  3. Server Source Overrideへlocal Server/ pathを指定する
  4. 必要なら**Dev Mode (Force fresh server install)**を有効化する

server code変更を毎回確実に読み直したい場合に使います。

Unity package sourceを切り替える​

python mcp_source.py

用途に応じてstable upstream、beta upstream、remote branch、local workspaceを選びます。Unity package codeを開発する場合はlocal workspaceが最短です。

Git URLのbranch名だけを見ると実際にresolveされたcommitが分からないため、debug時はPackages/manifest.jsonとPackages/packages-lock.jsonの両方を確認します。

Library/PackageCache/を直接開発対象として編集しません。Unityのresolveで上書きされます。

tool / resourceを追加する​

built-in toolは通常2層あります。

MCPForUnity/Editor/Tools/       # C# handler
Server/src/services/tools/      # Python MCP tool

resourceも同様です。

MCPForUnity/Editor/Resources/
Server/src/services/resources/

Unity側は[McpForUnityTool] / [McpForUnityResource]、Python側は@mcp_for_unity_tool / @mcp_for_unity_resourceを使用します。

長時間処理はbridgeをblockingせず、既存のPendingResponse / polling patternを使います。

tool visibility​

一般toolはgroupへ所属し、既定ではcoreを中心に表示します。session単位の切り替えはmanage_toolsを使います。詳しくはツールグループを参照してください。

HTTPではtool list changeをconnected clientへ通知できます。stdioではmanage_tools(action="sync")またはsession再起動で同期します。

test​

Python:

cd Server
uv run pytest tests/ -v

Unity側:

TestProjects/UnityMCPTests/Assets/Tests/

headless harness:

python tools/local_harness.py

Unity version compatibility:

tools/check-unity-versions.sh
tools/check-unity-versions.sh --full

詳細はテストを参照してください。

generated docs​

tool / resource registryを変更した場合:

cd Server
uv run python ../tools/generate_docs_reference.py

website/docs/reference/のgenerated領域を手動で独立変更しません。

開発時によくある問題​

  • 古いGit packageを読む — packages-lock.jsonのresolved hashを確認し、Unityを閉じてから必要最小限のcacheだけを整理する
  • Safe Modeになる — package compile errorを先に修正する。MCP serverはcompile前のfailureを回復できない
  • server code変更が反映されない — Server Source OverrideとDev Modeを確認する
  • stdioのtool visibilityが古い — manage_tools(action="sync")またはsession再起動
  • 複数Editorを開いている — mcpforunity://instancesとset_active_instanceで対象を明示する

現在のworkflow、Unity version matrix、tool group一覧など時間とともに変わる情報は、docsへ複製しすぎずcode / .github/workflows/ / tools/unity-versions.jsonを正本として確認します。