Unity Code MCP Server v0.1.8-preview Release Notes

✨ What’s New for You?

The 0.1 release focuses on making the Unity Code MCP Server more reliable and easier to use. Here are the highlights of how your experience will improve:

• Zero-Config Connection: You no longer need to worry about matching port numbers between Unity and your AI agent configuration. The bridge now figures it out automatically from your Unity settings.
• Reliable Server Restarts: We’ve overhauled how TCP connections are handled. This means the server can now restart instantly during Unity domain reloads or manual clicks without hitting “Address already in use” errors—significantly improving day-to-day stability.
• Cleaner Project Structure: We’ve moved the settings and internal files out of your Assets/Resources folder into a dedicated Plugins directory, keeping your project organized.
• Smarter Scripting: When an AI agent modifies your scene via a script, the scene is now automatically marked as “dirty” (unsaved), so you won’t accidentally lose changes when closing Unity.
• Better Feedback from AI: Tool outputs now clearly state whether Unity is in Edit Mode or Play Mode, giving you and the AI agent better context for why certain operations might be unavailable.
• Safer Testing: Running tests through an agent is now safer. The server will automatically save your work before starting tests and restore your open scenes exactly how they were once the tests finish.

⚠️ Breaking Changes & Migration

1. Settings Asset Migration

The Unity settings asset has been moved to a developer-friendly location to avoid cluttering the Assets/Resources folder:

• Old Path: Assets/Resources/UnityCodeMcpServerSettings.asset
• New Path: Assets/Plugins/UnityCodeMcpServer/Editor/UnityCodeMcpServerSettings.asset
• Note: Users may need to re-configure custom ports or log levels in the new asset. Use Tools > UnityCodeMcpServer > Show or Create Settings to access it.

2. STDIO Bridge Configuration

The unity-code-mcp-stdio bridge now automatically discovers the Unity port from the project settings.

• Removed Parameters: --host and --port are no longer supported.
• Action: Update your MCP client (VS Code, Claude Desktop) configuration to remove these flags.
• Tip: Use Tools > UnityCodeMcpServer > STDIO > Print MCP configuration to console to view your ready-to-use configuration.

---

🚀 Key Improvements

🛠 Tools & Script Execution

• execute_csharp_script_in_unity_editor Enhancements:
  • Now uses ScriptExecutionService for more robust compilation and execution via Roslyn.
  • Automatically marks the active scene as dirty after execution in Edit Mode.
  • Improved output formatting with markdown sections for Result, Script, Logs, and Errors.
  • Added “Mode Indication” to tool outputs (e.g., “Unity Editor is in Edit Mode”).
• read_unity_console_logs Enhancements:
  • New parameter max_entries to limit context window bloat.
  • Improved reliability when fetching logs via reflection.
• run_unity_tests Enhancements:
  • Fixed a bug where Both mode only ran EditMode tests.
  • Added automatic saving of dirty scenes before running tests.
  • Implemented scene state restoration: original scenes are restored after tests finish.
  • Block EditMode tests while the Editor is in Play Mode to prevent instability.
• get_unity_info Tool (New):
  • Returns Unity Editor project path and current server settings.
  • Useful for verifying server configuration and troubleshooting connectivity issues.

📝 Logging & Diagnostics

• LoopLogger: Consolidated internal logging system with configurable levels (Info, Debug, Warn, Error).
• LogCapture: Implemented a thread-safe log capture mechanism to redirect Unity’s Debug.Log output back to the MCP tools during script execution.

🏗 Infrastructure & Testing

• Server Robustness:
  • Prevented automatic server startup when Unity is running in batch mode.
  • TCP Socket Management: Implemented the LingerState option (with LingerOption(true, 0)) to force the TCP socket to close immediately on shutdown. This prevents the socket from entering the TIME_WAIT state, ensuring the port is instantly available for a restart without “address already in use” errors—crucial for Unity domain reloads and developer iteration.
• Test Organization:
  • Moved EditMode tests to Assets/Tests/EditMode with updated namespaces.
  • Added initial PlayMode test infrastructure in Assets/Tests/PlayMode.
• Tool Descriptions: Greatly enhanced tool descriptions with “WHEN TO USE” and “CRITICAL DIRECTIVES” to guide AI agents better.

---

📦 Version History (Branch 0.1)

• 0.1.7-preview: Removed port/host parameters from bridge; finalized settings relocation.
• 0.1.6-preview: Refactored tool/resource paths; improved README instructions.
• 0.1.5-preview: Scene dirtying improvements; further tool description polish.
• 0.1.3-preview / 0.1.4-preview: Logging system refactor and LogCapture implementation.
• 0.1.2-preview: Initial ScriptExecutionService integration.
• 0.1.0-preview: Version bump and baseline for 0.1 features.