unity-mcp-server 1.0.0__tar.gz

unity_mcp_server-1.0.0/.dockerignore

@@ -0,0 +1,5 @@
+__pycache__
+*.pyc
+.venv
+.git
+*.egg-info

unity_mcp_server-1.0.0/.gitignore

@@ -0,0 +1,111 @@
+# This .gitignore file should be placed at the root of your Unity project directory
+#
+# Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore
+#
+.utmp/
+/[Ll]ibrary/
+/[Tt]emp/
+/[Oo]bj/
+/[Bb]uild/
+/[Bb]uilds/
+/[Ll]ogs/
+/[Uu]ser[Ss]ettings/
+*.log
+
+# By default unity supports Blender asset imports, *.blend1 blender files do not need to be commited to version control.
+*.blend1
+*.blend1.meta
+
+# MemoryCaptures can get excessive in size.
+# They also could contain extremely sensitive data
+/[Mm]emoryCaptures/
+
+# Recordings can get excessive in size
+/[Rr]ecordings/
+
+# Uncomment this line if you wish to ignore the asset store tools plugin
+# /[Aa]ssets/AssetStoreTools*
+
+# Autogenerated Jetbrains Rider plugin
+/[Aa]ssets/Plugins/Editor/JetBrains*
+# Jetbrains Rider personal-layer settings
+*.DotSettings.user
+
+# Visual Studio cache directory
+.vs/
+
+# Gradle cache directory
+.gradle/
+
+# Autogenerated VS/MD/Consulo solution and project files
+ExportedObj/
+.consulo/
+*.csproj
+*.unityproj
+*.sln
+*.suo
+*.tmp
+*.user
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.pdb
+*.mdb
+*.opendb
+*.VC.db
+
+# Unity3D generated meta files
+*.pidb.meta
+*.pdb.meta
+*.mdb.meta
+
+# Unity3D generated file on crash reports
+sysinfo.txt
+
+# Mono auto generated files
+mono_crash.*
+
+# Builds
+*.apk
+*.aab
+*.unitypackage
+*.unitypackage.meta
+*.app
+
+# Crashlytics generated file
+crashlytics-build.properties
+
+# TestRunner generated files
+InitTestScene*.unity*
+
+# Addressables default ignores, before user customizations
+/ServerData
+/[Aa]ssets/StreamingAssets/aa*
+/[Aa]ssets/AddressableAssetsData/link.xml*
+/[Aa]ssets/Addressables_Temp*
+# By default, Addressables content builds will generate addressables_content_state.bin
+# files in platform-specific subfolders, for example:
+# /Assets/AddressableAssetsData/OSX/addressables_content_state.bin
+/[Aa]ssets/AddressableAssetsData/*/*.bin*
+
+# Visual Scripting auto-generated files
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db.meta
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers
+/[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers.meta
+
+# Auto-generated scenes by play mode tests
+/[Aa]ssets/[Ii]nit[Tt]est[Ss]cene*.unity*
+
+McpProjects/*
+
+# Bridge build artifacts (use build_bridge.sh to rebuild)
+unity-bridge/bin/
+unity-bridge/obj/
+
+unity-server/dist/
+
+# NOTE: unity-mcp/Bridge~/ is NOT ignored — it contains bundled bridge
+# binaries that must be committed for git URL installs to work.
+# Run ./scripts/build_bridge.sh to populate it before publishing.

unity_mcp_server-1.0.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install dependencies first (cache layer)
+COPY pyproject.toml .
+RUN pip install --no-cache-dir "mcp>=1.0.0"
+
+# Copy source code and install package
+COPY unity_mcp_server/ unity_mcp_server/
+RUN pip install --no-cache-dir --no-deps .
+
+# Default environment
+ENV UNITY_MCP_HOST=host.docker.internal
+ENV UNITY_MCP_PORT=52345
+ENV UNITY_MCP_TIMEOUT=60
+
+ENTRYPOINT ["unity-mcp-server"]

unity_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: unity-mcp-server
+Version: 1.0.0
+Summary: Python MCP server for Unity Editor — enables AI assistants to control Unity via the Model Context Protocol
+Project-URL: Homepage, https://github.com/mzbswh/unity-mcp
+Project-URL: Repository, https://github.com/mzbswh/unity-mcp
+Project-URL: Issues, https://github.com/mzbswh/unity-mcp/issues
+Author: mzbswh
+License: MIT
+Keywords: ai,game-development,llm,mcp,unity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# unity-mcp-server
+
+Python MCP server for [Unity MCP](https://github.com/mzbswh/unity-mcp) — enables AI assistants (Claude, Cursor, VS Code Copilot, Windsurf) to control the Unity Editor via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Quick Start
+
+### 1. Install the Unity package
+
+In Unity: `Window > Package Manager > + > Add package from git URL`:
+
+```
+https://github.com/mzbswh/unity-mcp.git?path=unity-mcp
+```
+
+### 2. Configure your MCP client
+
+Add to your MCP client config (e.g. `.cursor/mcp.json`, `.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "unity": {
+      "command": "uvx",
+      "args": ["unity-mcp-server"],
+      "env": {
+        "UNITY_MCP_PORT": "52345"
+      }
+    }
+  }
+}
+```
+
+Or use **Window > Unity MCP > Clients** tab in Unity for one-click configuration.
+
+### 3. Verify
+
+Ask your AI assistant: *"List all GameObjects in my Unity scene"*
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `UNITY_MCP_HOST` | `127.0.0.1` | Unity Editor host address |
+| `UNITY_MCP_PORT` | `52345` | Unity Editor TCP port |
+| `UNITY_MCP_TIMEOUT` | `60` | Request timeout (seconds) |
+
+## Extra Tools
+
+In addition to all Unity Editor tools (60+), this server provides:
+
+- `analyze_script` — C# script static analysis
+- `validate_assets` — Asset naming and directory validation
+
+## License
+
+[MIT](https://github.com/mzbswh/unity-mcp/blob/main/LICENSE)

unity_mcp_server-1.0.0/README.md

@@ -0,0 +1,56 @@
+# unity-mcp-server
+
+Python MCP server for [Unity MCP](https://github.com/mzbswh/unity-mcp) — enables AI assistants (Claude, Cursor, VS Code Copilot, Windsurf) to control the Unity Editor via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Quick Start
+
+### 1. Install the Unity package
+
+In Unity: `Window > Package Manager > + > Add package from git URL`:
+
+```
+https://github.com/mzbswh/unity-mcp.git?path=unity-mcp
+```
+
+### 2. Configure your MCP client
+
+Add to your MCP client config (e.g. `.cursor/mcp.json`, `.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "unity": {
+      "command": "uvx",
+      "args": ["unity-mcp-server"],
+      "env": {
+        "UNITY_MCP_PORT": "52345"
+      }
+    }
+  }
+}
+```
+
+Or use **Window > Unity MCP > Clients** tab in Unity for one-click configuration.
+
+### 3. Verify
+
+Ask your AI assistant: *"List all GameObjects in my Unity scene"*
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `UNITY_MCP_HOST` | `127.0.0.1` | Unity Editor host address |
+| `UNITY_MCP_PORT` | `52345` | Unity Editor TCP port |
+| `UNITY_MCP_TIMEOUT` | `60` | Request timeout (seconds) |
+
+## Extra Tools
+
+In addition to all Unity Editor tools (60+), this server provides:
+
+- `analyze_script` — C# script static analysis
+- `validate_assets` — Asset naming and directory validation
+
+## License
+
+[MIT](https://github.com/mzbswh/unity-mcp/blob/main/LICENSE)

unity_mcp_server-1.0.0/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  unity-mcp-server:
+    build: .
+    environment:
+      # host.docker.internal lets the container reach Unity on the host machine
+      - UNITY_MCP_HOST=host.docker.internal
+      - UNITY_MCP_PORT=${UNITY_MCP_PORT:-52345}
+      - UNITY_MCP_TIMEOUT=${UNITY_MCP_TIMEOUT:-60}
+    # stdio mode: MCP client connects via stdin/stdout
+    stdin_open: true
+    # For Streamable HTTP mode, uncomment:
+    # ports:
+    #   - "8000:8000"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"

unity_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "unity-mcp-server"
+version = "1.0.0"
+description = "Python MCP server for Unity Editor — enables AI assistants to control Unity via the Model Context Protocol"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+readme = "README.md"
+authors = [
+    { name = "mzbswh" }
+]
+keywords = ["mcp", "unity", "ai", "llm", "game-development"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mzbswh/unity-mcp"
+Repository = "https://github.com/mzbswh/unity-mcp"
+Issues = "https://github.com/mzbswh/unity-mcp/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+unity-mcp-server = "unity_mcp_server.server:main"

unity_mcp_server-1.0.0/unity_mcp_server/__init__.py

@@ -0,0 +1,2 @@
+"""Unity MCP Server - Python FastMCP bridge to Unity Editor."""
+__version__ = "1.0.0"

unity_mcp_server-1.0.0/unity_mcp_server/config.py

@@ -0,0 +1,23 @@
+"""Configuration for Unity MCP Server.
+
+The UNITY_MCP_PORT environment variable is set automatically by the Unity Editor
+when launching this server (see ServerProcessManager.CreatePythonStartInfo).
+If not set, falls back to 0 which will cause an explicit connection error rather
+than silently connecting to the wrong port.
+"""
+import os
+import logging
+
+UNITY_HOST = os.environ.get("UNITY_MCP_HOST", "127.0.0.1")
+
+_port_str = os.environ.get("UNITY_MCP_PORT", "")
+if _port_str:
+    UNITY_PORT = int(_port_str)
+else:
+    logging.warning(
+        "UNITY_MCP_PORT not set. The Unity Editor should set this automatically. "
+        "Set it manually or check your MCP client configuration (env field)."
+    )
+    UNITY_PORT = 0
+
+REQUEST_TIMEOUT = float(os.environ.get("UNITY_MCP_TIMEOUT", "60.0"))

unity_mcp_server-1.0.0/unity_mcp_server/server.py

@@ -0,0 +1,400 @@
+"""Unity MCP Server - FastMCP entry point.
+
+This Python server acts as a dynamic bridge between MCP clients (Claude, etc.)
+and the Unity Editor. It discovers tools/resources/prompts from Unity via TCP
+and forwards all calls dynamically.
+"""
+import asyncio
+import json
+import logging
+from contextlib import asynccontextmanager
+from mcp.server.fastmcp import FastMCP
+from .unity_connection import UnityConnection
+from . import __version__
+from .config import UNITY_HOST, UNITY_PORT
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class UnityToolError(Exception):
+    """Raised when a Unity tool reports isError=true. Propagates to FastMCP as an MCP error."""
+    pass
+
+# Track registered names to avoid duplicates on reconnect
+_registered_tools: set[str] = set()
+_registered_resources: set[str] = set()
+_registered_prompts: set[str] = set()
+
+# Global connection instance (initialized in lifespan)
+unity: UnityConnection | None = None
+
+
+@asynccontextmanager
+async def lifespan(server: FastMCP):
+    """Startup/shutdown lifecycle for the MCP server."""
+    global unity
+    unity = UnityConnection(UNITY_HOST, UNITY_PORT)
+    try:
+        await _discover_and_register(server)
+    except ConnectionRefusedError:
+        logger.warning(
+            "Unity not available at startup. "
+            "Tools will fail until Unity is running with MCP enabled."
+        )
+    except Exception as e:
+        logger.error(f"Failed to discover tools during startup: {e}")
+    yield
+    # Shutdown
+    try:
+        if unity and unity.connected:
+            await unity.disconnect()
+    except Exception as e:
+        logger.error(f"Error during shutdown: {e}")
+    finally:
+        unity = None
+
+
+mcp = FastMCP("Unity MCP", version=__version__, lifespan=lifespan)
+
+
+async def _ensure_connected():
+    """Ensure connection to Unity, reconnecting if needed."""
+    if unity is None:
+        raise ConnectionError("Server not initialized")
+    await unity.ensure_connected()
+
+
+async def _try_rediscover(server: FastMCP):
+    """Attempt to re-discover tools/resources/prompts from Unity if none are registered."""
+    if _registered_tools and _registered_resources and _registered_prompts:
+        return  # Already discovered
+    try:
+        await _discover_and_register(server)
+        if _registered_tools:
+            logger.info(f"Re-discovery successful: {len(_registered_tools)} tools registered")
+    except Exception as e:
+        logger.debug(f"Re-discovery attempt failed: {e}")
+
+
+async def _forward_tool(tool_name: str, **kwargs) -> str:
+    """Forward a tool call to Unity and return the result as JSON string."""
+    try:
+        await _ensure_connected()
+        # If no tools have been registered yet (Unity was offline at startup),
+        # attempt re-discovery now that we have a connection
+        if not _registered_tools:
+            await _try_rediscover(mcp)
+        # Filter out None values (optional params not provided by client)
+        filtered_args = {k: v for k, v in kwargs.items() if v is not None}
+        result = await unity.send_request("tools/call", {
+            "name": tool_name,
+            "arguments": filtered_args
+        })
+        if "error" in result:
+            error = result["error"]
+            msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+            raise UnityToolError(msg)
+        # Unity returns MCP content structure: {"content":[{"type":"text","text":"..."}], "isError":...}
+        # Extract the inner text to avoid double-wrapping by FastMCP
+        mcp_result = result.get("result", {})
+        is_error = mcp_result.get("isError", False)
+        content_list = mcp_result.get("content", [])
+        if content_list and isinstance(content_list, list):
+            first = content_list[0]
+            if isinstance(first, dict) and first.get("type") == "text":
+                text = first.get("text", "")
+                if is_error:
+                    raise UnityToolError(text)
+                return text
+        return json.dumps(mcp_result, indent=2)
+    except UnityToolError:
+        raise  # Let FastMCP handle this as an MCP error response
+    except asyncio.TimeoutError:
+        logger.error(f"Tool call timeout: {tool_name}")
+        raise UnityToolError(f"Tool execution timeout: {tool_name}")
+    except ConnectionError as e:
+        logger.error(f"Tool connection error [{tool_name}]: {e}")
+        raise UnityToolError(f"Unity connection error: {e}")
+    except Exception as e:
+        logger.error(f"Tool forwarding error [{tool_name}]: {e}")
+        raise UnityToolError(f"Tool forwarding error: {e}")
+
+
+async def _forward_resource(uri: str) -> str:
+    """Forward a resource read to Unity and return the result as JSON string."""
+    try:
+        await _ensure_connected()
+        if not _registered_resources:
+            await _try_rediscover(mcp)
+        result = await unity.send_request("resources/read", {"uri": uri})
+        if "error" in result:
+            error = result["error"]
+            msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+            raise UnityToolError(f"Resource error: {msg}")
+        # Unity returns MCP contents structure: {"contents":[{"uri":"...","mimeType":"...","text":"..."}]}
+        # Extract the inner text to avoid double-wrapping by FastMCP
+        mcp_result = result.get("result", {})
+        contents = mcp_result.get("contents", [])
+        if contents and isinstance(contents, list):
+            first = contents[0]
+            if isinstance(first, dict) and "text" in first:
+                return first["text"]
+        return json.dumps(mcp_result, indent=2)
+    except UnityToolError:
+        raise
+    except asyncio.TimeoutError:
+        logger.error(f"Resource read timeout: {uri}")
+        raise UnityToolError(f"Resource read timeout: {uri}")
+    except ConnectionError as e:
+        logger.error(f"Resource connection error [{uri}]: {e}")
+        raise UnityToolError(f"Unity connection error: {e}")
+    except Exception as e:
+        logger.error(f"Resource forwarding error [{uri}]: {e}")
+        raise UnityToolError(f"Resource forwarding error: {e}")
+
+
+async def _discover_and_register(server: FastMCP):
+    """Discover tools and resources from Unity and register them with FastMCP."""
+    try:
+        await _ensure_connected()
+    except Exception as e:
+        logger.warning(f"Cannot connect to Unity for discovery: {e}")
+        return
+
+    # Discover tools
+    try:
+        tools_response = await unity.send_request("tools/list", {})
+        tools = tools_response.get("result", {}).get("tools", [])
+        for tool_def in tools:
+            name = tool_def.get("name", "")
+            if not name or name in _registered_tools:
+                continue
+            _register_dynamic_tool(server, name, tool_def)
+            _registered_tools.add(name)
+        logger.info(f"Registered {len(_registered_tools)} tools from Unity")
+    except Exception as e:
+        logger.error(f"Failed to discover tools: {e}")
+
+    # Discover resources
+    try:
+        res_response = await unity.send_request("resources/list", {})
+        resources = res_response.get("result", {}).get("resources", [])
+        for res_def in resources:
+            uri = res_def.get("uri", "")
+            if not uri or uri in _registered_resources:
+                continue
+            _register_dynamic_resource(server, uri, res_def)
+            _registered_resources.add(uri)
+        logger.info(f"Registered {len(_registered_resources)} resources from Unity")
+    except Exception as e:
+        logger.error(f"Failed to discover resources: {e}")
+
+    # Discover prompts
+    try:
+        prompts_response = await unity.send_request("prompts/list", {})
+        prompts = prompts_response.get("result", {}).get("prompts", [])
+        for prompt_def in prompts:
+            name = prompt_def.get("name", "")
+            if not name or name in _registered_prompts:
+                continue
+            _register_dynamic_prompt(server, name, prompt_def)
+            _registered_prompts.add(name)
+        logger.info(f"Registered {len(_registered_prompts)} prompts from Unity")
+    except Exception as e:
+        logger.error(f"Failed to discover prompts: {e}")
+
+
+def _register_dynamic_tool(server: FastMCP, name: str, tool_def: dict):
+    """Register a single tool as a FastMCP tool that forwards to Unity."""
+    import inspect
+    from typing import Optional
+
+    description = tool_def.get("description", f"Unity tool: {name}")
+    schema = tool_def.get("inputSchema", {})
+    properties = schema.get("properties", {})
+    required_set = set(schema.get("required", []))
+
+    type_map = {
+        "string": str, "integer": int, "number": float,
+        "boolean": bool, "object": dict, "array": list,
+    }
+
+    # Build inspect.Parameter list so FastMCP sees a proper signature.
+    # We also build a param_descriptions dict to preserve Unity's original
+    # parameter descriptions, which inspect.Signature cannot carry.
+    params = []
+    param_descriptions = {}
+    for param_name, param_def in properties.items():
+        py_type = type_map.get(param_def.get("type", "string"), str)
+        if param_name in required_set:
+            params.append(inspect.Parameter(
+                param_name,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                annotation=py_type,
+            ))
+        else:
+            params.append(inspect.Parameter(
+                param_name,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                default=None,
+                annotation=Optional[py_type],
+            ))
+        # Preserve original description from Unity's schema
+        if "description" in param_def:
+            param_descriptions[param_name] = param_def["description"]
+
+    # Create forwarding function with captured tool name
+    async def tool_handler(**kwargs) -> str:
+        return await _forward_tool(name, **kwargs)
+
+    tool_handler.__name__ = name
+    tool_handler.__qualname__ = name
+    tool_handler.__doc__ = description
+    tool_handler.__signature__ = inspect.Signature(params, return_annotation=str)
+
+    # Register with FastMCP
+    server.tool(name=name, description=description)(tool_handler)
+
+    # After registration, patch the tool's inputSchema to restore Unity's
+    # original parameter descriptions, enums, and constraints that
+    # inspect.Signature cannot carry.
+    try:
+        tool_manager = server._tool_manager
+        if hasattr(tool_manager, '_tools') and name in tool_manager._tools:
+            tool_obj = tool_manager._tools[name]
+            if hasattr(tool_obj, 'parameters') and tool_obj.parameters:
+                tool_schema = tool_obj.parameters
+                schema_props = tool_schema.get("properties", {})
+                for pname, pdef in properties.items():
+                    if pname in schema_props:
+                        # Restore description
+                        if "description" in pdef:
+                            schema_props[pname]["description"] = pdef["description"]
+                        # Restore enum values
+                        if "enum" in pdef:
+                            schema_props[pname]["enum"] = pdef["enum"]
+                        # Restore numeric constraints
+                        for constraint in ("minimum", "maximum", "default"):
+                            if constraint in pdef:
+                                schema_props[pname][constraint] = pdef[constraint]
+    except Exception as e:
+        logger.warning(f"Could not patch schema for tool '{name}': {e}. "
+                       f"Parameter descriptions may be missing.")
+
+
+def _register_dynamic_resource(server: FastMCP, uri: str, res_def: dict):
+    """Register a single resource as a FastMCP resource that forwards to Unity."""
+    description = res_def.get("description", f"Unity resource: {uri}")
+    res_name = res_def.get("name", uri)
+
+    # Handle parameterized URI templates (e.g. "unity://gameobject/{id}")
+    # FastMCP extracts template params and passes them as kwargs
+    async def resource_handler(_uri_template=uri, **kwargs) -> str:
+        actual_uri = _uri_template
+        for k, v in kwargs.items():
+            actual_uri = actual_uri.replace(f"{{{k}}}", str(v))
+        return await _forward_resource(actual_uri)
+
+    resource_handler.__name__ = res_name.replace("/", "_").replace(":", "_")
+    resource_handler.__doc__ = description
+
+    server.resource(uri)(resource_handler)
+
+
+async def _forward_prompt(name: str, arguments: dict | None = None) -> str:
+    """Forward a prompt get to Unity and return the result."""
+    try:
+        await _ensure_connected()
+        result = await unity.send_request("prompts/get", {
+            "name": name,
+            "arguments": arguments or {}
+        })
+        if "error" in result:
+            error = result["error"]
+            msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+            raise UnityToolError(f"Prompt error: {msg}")
+        # Unity returns: {"description":"...","messages":[{"role":"user","content":{"type":"text","text":"..."}}]}
+        mcp_result = result.get("result", {})
+        messages = mcp_result.get("messages", [])
+        if messages and isinstance(messages, list):
+            first = messages[0]
+            content = first.get("content", {})
+            if isinstance(content, dict) and content.get("type") == "text":
+                return content.get("text", "")
+        return json.dumps(mcp_result, indent=2)
+    except UnityToolError:
+        raise
+    except asyncio.TimeoutError:
+        logger.error(f"Prompt get timeout: {name}")
+        raise UnityToolError(f"Prompt execution timeout: {name}")
+    except ConnectionError as e:
+        logger.error(f"Prompt connection error [{name}]: {e}")
+        raise UnityToolError(f"Unity connection error: {e}")
+    except Exception as e:
+        logger.error(f"Prompt forwarding error [{name}]: {e}")
+        raise UnityToolError(f"Prompt forwarding error: {e}")
+
+
+def _register_dynamic_prompt(server: FastMCP, name: str, prompt_def: dict):
+    """Register a single prompt as a FastMCP prompt that forwards to Unity."""
+    import inspect
+    from typing import Optional
+
+    description = prompt_def.get("description", f"Unity prompt: {name}")
+    arguments = prompt_def.get("arguments", [])
+
+    # Build inspect.Parameter list from prompt arguments
+    params = []
+    for arg_def in arguments:
+        arg_name = arg_def.get("name", "")
+        if not arg_name:
+            continue
+        required = arg_def.get("required", False)
+        if required:
+            params.append(inspect.Parameter(
+                arg_name,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                annotation=str,
+            ))
+        else:
+            params.append(inspect.Parameter(
+                arg_name,
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                default=None,
+                annotation=Optional[str],
+            ))
+
+    async def prompt_handler(**kwargs) -> str:
+        filtered = {k: v for k, v in kwargs.items() if v is not None}
+        return await _forward_prompt(name, filtered)
+
+    prompt_handler.__name__ = name
+    prompt_handler.__qualname__ = name
+    prompt_handler.__doc__ = description
+    prompt_handler.__signature__ = inspect.Signature(params, return_annotation=str)
+
+    server.prompt(name=name, description=description)(prompt_handler)
+
+
+# --- Python-side tools (no Unity connection needed) ---
+
+@mcp.tool(name="analyze_script", description="Analyze a C# script for common issues and patterns (runs locally, no Unity needed)")
+def analyze_script(file_path: str) -> str:
+    from .tools.script_analyzer import analyze_script as _analyze
+    return json.dumps(_analyze(file_path), indent=2)
+
+
+@mcp.tool(name="validate_assets", description="Validate asset naming conventions and folder structure (runs locally, no Unity needed)")
+def validate_assets(project_path: str) -> str:
+    from .tools.asset_validator import validate_assets as _validate
+    return json.dumps(_validate(project_path), indent=2)
+
+
+def main():
+    """Entry point for the Unity MCP Python server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

unity_mcp_server-1.0.0/unity_mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""Python-side enhanced tools for Unity MCP."""

unity_mcp_server-1.0.0/unity_mcp_server/tools/asset_validator.py

@@ -0,0 +1,77 @@
+"""Asset naming and structure validation tool (Python-side)."""
+import os
+import re
+from typing import Optional
+
+
+# Default naming conventions
+NAMING_RULES = {
+    ".cs": r"^[A-Z][a-zA-Z0-9]+\.cs$",        # PascalCase
+    ".prefab": r"^[A-Z][a-zA-Z0-9_]+\.prefab$", # PascalCase with underscores
+    ".mat": r"^[A-Z][a-zA-Z0-9_]+\.mat$",       # PascalCase with underscores
+    ".asset": r"^[A-Z][a-zA-Z0-9_]+\.asset$",
+    ".png": r"^[a-z][a-z0-9_]+\.png$",           # snake_case for textures
+    ".jpg": r"^[a-z][a-z0-9_]+\.jpg$",
+}
+
+# Expected folder structure under Assets/
+EXPECTED_FOLDERS = [
+    "Scripts", "Prefabs", "Materials", "Textures",
+    "Scenes", "Audio", "Animations", "Fonts",
+]
+
+
+def validate_assets(project_path: str, custom_rules: Optional[dict] = None) -> dict:
+    """Validate asset naming conventions and folder structure.
+
+    Args:
+        project_path: Path to the Unity project root (contains Assets/)
+        custom_rules: Optional dict of {extension: regex_pattern} to override defaults
+
+    Returns:
+        Validation report with violations and suggestions.
+    """
+    assets_path = os.path.join(project_path, "Assets")
+    if not os.path.isdir(assets_path):
+        return {"error": f"Assets folder not found at {assets_path}"}
+
+    rules = {**NAMING_RULES, **(custom_rules or {})}
+    violations = []
+    file_count = 0
+    folder_count = 0
+
+    for root, dirs, files in os.walk(assets_path):
+        folder_count += len(dirs)
+        for filename in files:
+            if filename.startswith("."):
+                continue
+            file_count += 1
+            ext = os.path.splitext(filename)[1].lower()
+            if ext in rules:
+                pattern = rules[ext]
+                if not re.match(pattern, filename):
+                    rel_path = os.path.relpath(
+                        os.path.join(root, filename), assets_path
+                    )
+                    violations.append({
+                        "file": rel_path,
+                        "rule": f"Expected pattern: {pattern}",
+                        "suggestion": f"Rename to match convention for {ext} files"
+                    })
+
+    # Check expected folders
+    missing_folders = []
+    for folder in EXPECTED_FOLDERS:
+        if not os.path.isdir(os.path.join(assets_path, folder)):
+            missing_folders.append(folder)
+
+    return {
+        "projectPath": project_path,
+        "stats": {
+            "totalFiles": file_count,
+            "totalFolders": folder_count,
+        },
+        "namingViolations": violations,
+        "violationCount": len(violations),
+        "missingFolders": missing_folders,
+    }

unity_mcp_server-1.0.0/unity_mcp_server/tools/script_analyzer.py

@@ -0,0 +1,56 @@
+"""C# script analysis tool (Python-side, no Unity needed)."""
+import os
+import re
+
+
+def analyze_script(file_path: str) -> dict:
+    """Analyze a C# script for common issues and patterns.
+
+    Returns analysis results including:
+    - Class/method counts
+    - Potential issues (empty catch, magic numbers, etc.)
+    - Suggestions for improvement
+    """
+    # Validate file extension
+    if not file_path.endswith(".cs"):
+        return {"error": "Only C# (.cs) files are supported"}
+
+    # Resolve to absolute path and check for path traversal
+    resolved = os.path.realpath(file_path)
+    if ".." in os.path.relpath(resolved, os.path.dirname(resolved)):
+        return {"error": "Invalid file path"}
+
+    if not os.path.isfile(resolved):
+        return {"error": f"File not found: {file_path}"}
+
+    with open(resolved, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    lines = content.split("\n")
+    issues = []
+
+    # Check for empty catch blocks
+    for i, line in enumerate(lines):
+        if re.search(r"catch\s*\([^)]*\)\s*\{\s*\}", line):
+            issues.append({
+                "line": i + 1,
+                "type": "empty_catch",
+                "message": "Empty catch block - consider logging the exception"
+            })
+
+    # Check for Update() without null checks on referenced objects
+    class_count = len(re.findall(r"\bclass\s+\w+", content))
+    method_count = len(re.findall(r"(public|private|protected|internal)\s+\w+\s+\w+\s*\(", content))
+    using_count = len(re.findall(r"^using\s+", content, re.MULTILINE))
+
+    return {
+        "file": file_path,
+        "stats": {
+            "lines": len(lines),
+            "classes": class_count,
+            "methods": method_count,
+            "usings": using_count,
+        },
+        "issues": issues,
+        "issueCount": len(issues),
+    }

unity_mcp_server-1.0.0/unity_mcp_server/unity_connection.py

@@ -0,0 +1,143 @@
+"""Unity TCP connection manager using the custom frame protocol."""
+import asyncio
+import struct
+import json
+import logging
+from .config import UNITY_HOST, UNITY_PORT, REQUEST_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+# Frame protocol constants (must match C# TcpTransport)
+MSG_TYPE_REQUEST = 0x01
+MSG_TYPE_RESPONSE = 0x02
+MSG_TYPE_NOTIFICATION = 0x03
+
+
+class UnityConnection:
+    """Manages TCP connection to Unity Editor's MCP server."""
+
+    def __init__(self, host: str = None, port: int = None):
+        self.host = host or UNITY_HOST
+        self.port = port or UNITY_PORT
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._request_id = 0
+        self._pending: dict[int, asyncio.Future] = {}
+        self._lock = asyncio.Lock()
+        self._connected = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    async def connect(self):
+        """Connect to Unity Editor TCP server."""
+        try:
+            self._reader, self._writer = await asyncio.open_connection(
+                self.host, self.port
+            )
+            self._connected = True
+            asyncio.create_task(self._read_loop())
+            logger.info(f"Connected to Unity at {self.host}:{self.port}")
+        except ConnectionRefusedError:
+            logger.error(
+                f"Cannot connect to Unity at {self.host}:{self.port}. "
+                "Is Unity running with MCP enabled?"
+            )
+            raise
+
+    async def disconnect(self):
+        """Close the connection."""
+        self._connected = False
+        if self._writer:
+            self._writer.close()
+            await self._writer.wait_closed()
+            self._writer = None
+            self._reader = None
+
+    async def send_request(self, method: str, params: dict = None) -> dict:
+        """Send a JSON-RPC request and wait for response."""
+        if not self._connected:
+            raise ConnectionError("Not connected to Unity")
+
+        async with self._lock:
+            self._request_id += 1
+            req_id = self._request_id
+
+        msg = json.dumps({
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": method,
+            "params": params or {}
+        }).encode("utf-8")
+
+        # Frame: 4-byte length (BE) + 1-byte type (0x01=Request) + JSON payload
+        frame_len = 1 + len(msg)
+        self._writer.write(struct.pack(">IB", frame_len, MSG_TYPE_REQUEST) + msg)
+        await self._writer.drain()
+
+        future = asyncio.get_running_loop().create_future()
+        self._pending[req_id] = future
+        return await asyncio.wait_for(future, timeout=REQUEST_TIMEOUT)
+
+    async def _read_loop(self):
+        """Read frames from Unity and resolve pending futures."""
+        try:
+            while self._connected:
+                # Read 4-byte length + 1-byte type
+                header = await self._reader.readexactly(5)
+                frame_len = struct.unpack(">I", header[:4])[0]
+                msg_type = header[4]
+                payload_len = frame_len - 1
+
+                if payload_len <= 0 or payload_len > 10 * 1024 * 1024:
+                    logger.error(f"Invalid payload length: {payload_len}")
+                    break
+
+                data = await self._reader.readexactly(payload_len)
+
+                try:
+                    msg = json.loads(data.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError) as e:
+                    logger.error(f"Failed to decode message: {e}")
+                    continue
+
+                req_id = msg.get("id")
+                if req_id and req_id in self._pending:
+                    self._pending.pop(req_id).set_result(msg)
+                else:
+                    logger.debug(f"Received unmatched message: {msg}")
+        except asyncio.IncompleteReadError:
+            logger.info("Unity connection closed")
+        except Exception as e:
+            logger.error(f"Read loop error: {e}")
+        finally:
+            self._connected = False
+            self._fail_pending("Connection closed")
+
+    def _fail_pending(self, reason: str):
+        """Fail all pending requests when connection is lost."""
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(ConnectionError(reason))
+        self._pending.clear()
+
+    async def ensure_connected(self):
+        """Reconnect to Unity if disconnected, with exponential backoff."""
+        if self._connected:
+            return
+
+        delays = [0, 500, 1000, 2000, 3000, 5000, 8000, 10000]
+        for attempt, delay in enumerate(delays):
+            if delay > 0:
+                logger.info(f"Reconnecting to Unity in {delay}ms (attempt {attempt + 1})")
+                await asyncio.sleep(delay / 1000)
+            try:
+                await self.connect()
+                return
+            except (ConnectionRefusedError, OSError) as e:
+                logger.warning(f"Reconnect attempt {attempt + 1} failed: {e}")
+
+        raise ConnectionError(
+            f"Cannot reconnect to Unity at {self.host}:{self.port} after {len(delays)} attempts"
+        )