diff --git a/README-DEV.md b/README-DEV.md new file mode 100644 index 0000000..954348b --- /dev/null +++ b/README-DEV.md @@ -0,0 +1,84 @@ +# Unity MCP Development Tools + +Welcome to the Unity MCP development environment! This directory contains tools and utilities to streamline Unity MCP core development. + +## 🚀 Available Development Features + +### ✅ Development Deployment Scripts +Quick deployment and testing tools for Unity MCP 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 Unity MCP 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 Unity MCP core code. + +## Scripts + +### `deploy-dev.bat` +Deploys your development code to the actual installation locations for testing. + +**What it does:** +1. Backs up original files to a timestamped folder +2. Copies Unity Bridge code to Unity's package cache +3. Copies Python Server code to the MCP installation folder + +**Usage:** +1. Run `deploy-dev.bat` +2. Enter Unity package cache path (example provided) +3. Enter server path (or use default: `%LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src`) +4. Enter backup location (or use default: `%USERPROFILE%\Desktop\unity-mcp-backup`) + +### `restore-dev.bat` +Restores original files from backup. + +**What it does:** +1. Lists available backups with timestamps +2. Allows you to select which backup to restore +3. Restores both Unity Bridge and Python Server files + +## Finding Unity Package Cache Path + +Unity package cache is typically located at: +``` +X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0 +``` + +To find it: +1. Open Unity Package Manager +2. Select "Unity MCP" package +3. Right click on the package and "Show in Explorer" +4. Navigate to the path above with your username and version + +## Workflow + +1. **Make changes** to your source code in this directory +2. **Deploy** using `deploy-dev.bat` +3. **Test** in Unity (restart Unity Editor first) +4. **Iterate** - repeat steps 1-3 as needed +5. **Restore** original files when done using `restore-dev.bat` + + +## Troubleshooting + +### "Path not found" errors running the .bat file +- Verify Unity package cache path is correct +- Check that Unity MCP package is actually installed +- Ensure server is installed via MCP client + +### "Permission denied" errors +- Run cmd as Administrator +- Close Unity Editor before deploying +- Close any MCP clients before deploying + +### "Backup not found" errors +- Run `deploy-dev.bat` first to create initial backup +- Check backup directory permissions +- Verify backup directory path is correct \ No newline at end of file diff --git a/README.md b/README.md index 19e81d4..fd097f1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # Unity MCP ✨ - [![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=blue 'Unity')](https://unity.com/releases/editor/archive) [![python](https://img.shields.io/badge/Python-3.12-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org) [![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction) @@ -8,13 +7,17 @@ ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/justinpbarnett/unity-mcp) [![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT) - - - **Create your Unity apps with LLMs!** Unity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local **MCP (Model Context Protocol) Client**. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity. +## 💬 Join Our Community + +### [Discord](https://discord.gg/vhTUxXaqYr) + +**Get help, share ideas, and collaborate with other Unity MCP developers!** + + --- @@ -194,9 +197,9 @@ If Auto-Configure fails or you use a different client: (Replace YOUR_USERNAME) - -**Option C: Claude Code Registration** + +**For Claude Code** If you're using Claude Code, you can register the MCP server using these commands: @@ -209,6 +212,7 @@ claude mcp add UnityMCP -- uv --directory /[PATH_TO]/UnityMCP/UnityMcpServer/src ```bash claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/Programs/UnityMCP/UnityMcpServer/src" run server.py ``` + --- @@ -258,7 +262,20 @@ claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/S --- -## Contributing 🤝 +## For Developers 🛠️ + +### Development Tools + +If you're contributing to Unity MCP or want to test core changes, we have development tools to streamline your workflow: + +- **Development Deployment Scripts**: Quickly deploy and test your changes to Unity MCP Bridge and Python Server +- **Automatic Backup System**: Safe testing with easy rollback capabilities +- **Hot Reload Workflow**: Fast iteration cycle for core development +- **More coming!** + +📖 **See [README-DEV.md](README-DEV.md)** for complete development setup and workflow documentation. + +### Contributing 🤝 Help make Unity MCP better! diff --git a/deploy-dev.bat b/deploy-dev.bat new file mode 100644 index 0000000..4cc61de --- /dev/null +++ b/deploy-dev.bat @@ -0,0 +1,148 @@ +@echo off +setlocal enabledelayedexpansion + +echo =============================================== +echo Unity MCP Development Deployment Script +echo =============================================== +echo. + +:: Configuration +set "SCRIPT_DIR=%~dp0" +set "BRIDGE_SOURCE=%SCRIPT_DIR%UnityMcpBridge" +set "SERVER_SOURCE=%SCRIPT_DIR%UnityMcpServer\src" +set "DEFAULT_BACKUP_DIR=%USERPROFILE%\Desktop\unity-mcp-backup" +set "DEFAULT_SERVER_PATH=%LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src" + +:: Get user inputs +echo Please provide the following paths: +echo. + +:: Package cache location +echo Unity Package Cache Location: +echo Example: X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0 +set /p "PACKAGE_CACHE_PATH=Enter Unity package cache path: " + +if "%PACKAGE_CACHE_PATH%"=="" ( + echo Error: Package cache path cannot be empty! + pause + exit /b 1 +) + +:: Server installation path (with default) +echo. +echo Server Installation Path: +echo Default: %DEFAULT_SERVER_PATH% +set /p "SERVER_PATH=Enter server path (or press Enter for default): " +if "%SERVER_PATH%"=="" set "SERVER_PATH=%DEFAULT_SERVER_PATH%" + +:: Backup location (with default) +echo. +echo Backup Location: +echo Default: %DEFAULT_BACKUP_DIR% +set /p "BACKUP_DIR=Enter backup directory (or press Enter for default): " +if "%BACKUP_DIR%"=="" set "BACKUP_DIR=%DEFAULT_BACKUP_DIR%" + +:: Validation +echo. +echo =============================================== +echo Validating paths... +echo =============================================== + +if not exist "%BRIDGE_SOURCE%" ( + echo Error: Bridge source not found: %BRIDGE_SOURCE% + pause + exit /b 1 +) + +if not exist "%SERVER_SOURCE%" ( + echo Error: Server source not found: %SERVER_SOURCE% + pause + exit /b 1 +) + +if not exist "%PACKAGE_CACHE_PATH%" ( + echo Error: Package cache path not found: %PACKAGE_CACHE_PATH% + pause + exit /b 1 +) + +if not exist "%SERVER_PATH%" ( + echo Error: Server installation path not found: %SERVER_PATH% + pause + exit /b 1 +) + +:: Create backup directory +if not exist "%BACKUP_DIR%" ( + echo Creating backup directory: %BACKUP_DIR% + mkdir "%BACKUP_DIR%" +) + +:: Create timestamped backup subdirectory +set "TIMESTAMP=%date:~-4,4%%date:~-10,2%%date:~-7,2%_%time:~0,2%%time:~3,2%%time:~6,2%" +set "TIMESTAMP=%TIMESTAMP: =0%" +set "TIMESTAMP=%TIMESTAMP::=-%" +set "TIMESTAMP=%TIMESTAMP:/=-%" +set "BACKUP_SUBDIR=%BACKUP_DIR%\backup_%TIMESTAMP%" +mkdir "%BACKUP_SUBDIR%" + +echo. +echo =============================================== +echo Starting deployment... +echo =============================================== + +:: Backup original files +echo Creating backup of original files... +if exist "%PACKAGE_CACHE_PATH%\Editor" ( + echo Backing up Unity Bridge files... + xcopy "%PACKAGE_CACHE_PATH%\Editor" "%BACKUP_SUBDIR%\UnityBridge\Editor\" /E /I /Y > nul + if !errorlevel! neq 0 ( + echo Error: Failed to backup Unity Bridge files + pause + exit /b 1 + ) +) + +if exist "%SERVER_PATH%" ( + echo Backing up Python Server files... + xcopy "%SERVER_PATH%\*" "%BACKUP_SUBDIR%\PythonServer\" /E /I /Y > nul + if !errorlevel! neq 0 ( + echo Error: Failed to backup Python Server files + pause + exit /b 1 + ) +) + +:: Deploy Unity Bridge +echo. +echo Deploying Unity Bridge code... +xcopy "%BRIDGE_SOURCE%\Editor\*" "%PACKAGE_CACHE_PATH%\Editor\" /E /Y > nul +if !errorlevel! neq 0 ( + echo Error: Failed to deploy Unity Bridge code + pause + exit /b 1 +) + +:: Deploy Python Server +echo Deploying Python Server code... +xcopy "%SERVER_SOURCE%\*" "%SERVER_PATH%\" /E /Y > nul +if !errorlevel! neq 0 ( + echo Error: Failed to deploy Python Server code + pause + exit /b 1 +) + +:: Success +echo. +echo =============================================== +echo Deployment completed successfully! +echo =============================================== +echo. +echo Backup created at: %BACKUP_SUBDIR% +echo. +echo Next steps: +echo 1. Restart Unity Editor to load new Bridge code +echo 2. Restart any MCP clients to use new Server code +echo 3. Use restore-dev.bat to rollback if needed +echo. +pause \ No newline at end of file diff --git a/restore-dev.bat b/restore-dev.bat new file mode 100644 index 0000000..a8e327a --- /dev/null +++ b/restore-dev.bat @@ -0,0 +1,162 @@ +@echo off +setlocal enabledelayedexpansion + +echo =============================================== +echo Unity MCP Development Restore Script +echo =============================================== +echo. + +:: Configuration +set "DEFAULT_BACKUP_DIR=%USERPROFILE%\Desktop\unity-mcp-backup" +set "DEFAULT_SERVER_PATH=%LOCALAPPDATA%\Programs\UnityMCP\UnityMcpServer\src" + +:: Get user inputs +echo Please provide the following paths: +echo. + +:: Package cache location +echo Unity Package Cache Location: +echo Example: X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0 +set /p "PACKAGE_CACHE_PATH=Enter Unity package cache path: " + +if "%PACKAGE_CACHE_PATH%"=="" ( + echo Error: Package cache path cannot be empty! + pause + exit /b 1 +) + +:: Server installation path (with default) +echo. +echo Server Installation Path: +echo Default: %DEFAULT_SERVER_PATH% +set /p "SERVER_PATH=Enter server path (or press Enter for default): " +if "%SERVER_PATH%"=="" set "SERVER_PATH=%DEFAULT_SERVER_PATH%" + +:: Backup location (with default) +echo. +echo Backup Location: +echo Default: %DEFAULT_BACKUP_DIR% +set /p "BACKUP_DIR=Enter backup directory (or press Enter for default): " +if "%BACKUP_DIR%"=="" set "BACKUP_DIR=%DEFAULT_BACKUP_DIR%" + +:: List available backups +echo. +echo =============================================== +echo Available backups: +echo =============================================== +set "counter=0" +for /d %%d in ("%BACKUP_DIR%\backup_*") do ( + set /a counter+=1 + set "backup!counter!=%%d" + echo !counter!. %%~nxd +) + +if %counter%==0 ( + echo No backups found in %BACKUP_DIR% + pause + exit /b 1 +) + +echo. +set /p "choice=Select backup to restore (1-%counter%): " + +:: Validate choice +if "%choice%"=="" goto :invalid_choice +if %choice% lss 1 goto :invalid_choice +if %choice% gtr %counter% goto :invalid_choice + +set "SELECTED_BACKUP=!backup%choice%!" +echo. +echo Selected backup: %SELECTED_BACKUP% + +:: Validation +echo. +echo =============================================== +echo Validating paths... +echo =============================================== + +if not exist "%SELECTED_BACKUP%" ( + echo Error: Selected backup not found: %SELECTED_BACKUP% + pause + exit /b 1 +) + +if not exist "%PACKAGE_CACHE_PATH%" ( + echo Error: Package cache path not found: %PACKAGE_CACHE_PATH% + pause + exit /b 1 +) + +if not exist "%SERVER_PATH%" ( + echo Error: Server installation path not found: %SERVER_PATH% + pause + exit /b 1 +) + +:: Confirm restore +echo. +echo =============================================== +echo WARNING: This will overwrite current files! +echo =============================================== +echo Restoring from: %SELECTED_BACKUP% +echo Unity Bridge target: %PACKAGE_CACHE_PATH%\Editor +echo Python Server target: %SERVER_PATH% +echo. +set /p "confirm=Continue with restore? (y/N): " +if /i not "%confirm%"=="y" ( + echo Restore cancelled. + pause + exit /b 0 +) + +echo. +echo =============================================== +echo Starting restore... +echo =============================================== + +:: Restore Unity Bridge +if exist "%SELECTED_BACKUP%\UnityBridge\Editor" ( + echo Restoring Unity Bridge files... + rd /s /q "%PACKAGE_CACHE_PATH%\Editor" 2>nul + xcopy "%SELECTED_BACKUP%\UnityBridge\Editor\*" "%PACKAGE_CACHE_PATH%\Editor\" /E /I /Y > nul + if !errorlevel! neq 0 ( + echo Error: Failed to restore Unity Bridge files + pause + exit /b 1 + ) +) else ( + echo Warning: No Unity Bridge backup found, skipping... +) + +:: Restore Python Server +if exist "%SELECTED_BACKUP%\PythonServer" ( + echo Restoring Python Server files... + rd /s /q "%SERVER_PATH%" 2>nul + mkdir "%SERVER_PATH%" + xcopy "%SELECTED_BACKUP%\PythonServer\*" "%SERVER_PATH%\" /E /I /Y > nul + if !errorlevel! neq 0 ( + echo Error: Failed to restore Python Server files + pause + exit /b 1 + ) +) else ( + echo Warning: No Python Server backup found, skipping... +) + +:: Success +echo. +echo =============================================== +echo Restore completed successfully! +echo =============================================== +echo. +echo Next steps: +echo 1. Restart Unity Editor to load restored Bridge code +echo 2. Restart any MCP clients to use restored Server code +echo. +pause +exit /b 0 + +:invalid_choice +echo Invalid choice. Please enter a number between 1 and %counter%. +pause +exit /b 1 \ No newline at end of file