6.0 KiB

Raw Blame History

MCP for Unity Development Tools

Welcome to the MCP for Unity development environment! This directory contains tools and utilities to streamline MCP for Unity core development.

🚀 Available Development Features

✅ Development Deployment Scripts

Quick deployment and testing tools for MCP for Unity core changes.

🔄 Coming Soon

Development Mode Toggle: Built-in Unity editor development features
Hot Reload System: Real-time code updates without Unity restarts
Plugin Development Kit: Tools for creating custom MCP for Unity extensions
Automated Testing Suite: Comprehensive testing framework for contributions
Debug Dashboard: Advanced debugging and monitoring tools

Development Deployment Scripts

These deployment scripts help you quickly test changes to MCP for Unity core code.

Scripts

`deploy-dev.bat`

Deploys your development code to the actual installation locations for testing.

What it does:

Backs up original files to a timestamped folder
Copies Unity Bridge code to Unity's package cache
Copies Python Server code to the MCP installation folder

Usage:

Run deploy-dev.bat
Enter Unity package cache path (example provided)
Enter server path (or use default: %LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src)
Enter backup location (or use default: %USERPROFILE%\Desktop\unity-mcp-backup)

Note: Dev deploy skips .venv, __pycache__, .pytest_cache, .mypy_cache, .git; reduces churn and avoids copying virtualenvs.

`restore-dev.bat`

Restores original files from backup.

What it does:

Lists available backups with timestamps
Allows you to select which backup to restore
Restores both Unity Bridge and Python Server files

Finding Unity Package Cache Path

Unity stores Git packages under a version-or-hash folder. Expect something like:

X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@<version-or-hash>

Example (hash):

X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@272123cfd97e

To find it reliably:

Open Unity Package Manager
Select "MCP for Unity" package
Right click the package and choose "Show in Explorer"
That opens the exact cache folder Unity is using for your project

Note: In recent builds, the Python server sources are also bundled inside the package under UnityMcpServer~/src. This is handy for local testing or pointing MCP clients directly at the packaged server.

CI Test Workflow (GitHub Actions)

We provide a CI job to run a Natural Language Editing mini-suite against the Unity test project. It spins up a headless Unity container and connects via the MCP bridge.

Trigger: Workflow dispatch (Claude NL suite (Unity live)).
Image: UNITY_IMAGE (UnityCI) pulled by tag; the job resolves a digest at runtime. Logs are sanitized.
Reports: JUnit at reports/junit-nl-suite.xml, Markdown at reports/junit-nl-suite.md.
Publishing: JUnit is normalized to reports/junit-for-actions.xml and published; artifacts upload all files under reports/.

Test target script

The repo includes a long, standalone C# script used to exercise larger edits and windows:
- TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs Use this file locally and in CI to validate multi-edit batches, anchor inserts, and windowed reads on a sizable script.

Add a new NL test

Edit .claude/prompts/nl-unity-claude-tests-mini.md (or nl-unity-suite-full.md for the larger suite).
Follow the conventions: single <testsuite> root, one <testcase> per sub-test, end system-out with VERDICT: PASS|FAIL.
Keep edits minimal and reversible; include evidence windows and compact diffs.

Run the suite

Push your branch, then manually run the workflow from the Actions tab.
The job writes reports into reports/ and uploads artifacts.
The “JUnit Test Report” check summarizes results; open the Job Summary for full markdown.

View results

Job Summary: inline markdown summary of the run on the Actions tab in GitHub
Check: “JUnit Test Report” on the PR/commit.
Artifacts: claude-nl-suite-artifacts includes XML and MD.

MCP Connection Debugging

Enable debug logs in the Unity MCP window (inside the Editor) to view connection status, auto-setup results, and MCP client paths. It shows:
- bridge startup/port, client connections, strict framing negotiation, and parsed frames
- auto-config path detection (Windows/macOS/Linux), uv/claude resolution, and surfaced errors
In CI, the job tails Unity logs (redacted for serial/license/password/token) and prints socket/status JSON diagnostics if startup fails.

Workflow

Make changes to your source code in this directory
Deploy using deploy-dev.bat
Test in Unity (restart Unity Editor first)
Iterate - repeat steps 1-3 as needed
Restore original files when done using restore-dev.bat

Switching MCP package sources quickly

Use mcp_source.py to quickly switch between different MCP for Unity package sources: