coplay-mcp-server 1.4.1__py3-none-any.whl

coplay_mcp_server/unity_client.py

@@ -0,0 +1,342 @@
+"""Unity RPC client for file-based communication with Unity Editor."""
+
+import asyncio
+import json
+import logging
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Optional
+import concurrent.futures
+
+import aiofiles
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+from mcp.server.fastmcp.utilities.types import Image
+
+logger = logging.getLogger(__name__)
+
+
+class UnityProjectRootError(Exception):
+    """Base exception for Unity project root related errors."""
+    pass
+
+
+class NoUnityInstancesError(UnityProjectRootError):
+    """Raised when no Unity Editor instances are found."""
+    pass
+
+
+class MultipleUnityInstancesError(UnityProjectRootError):
+    """Raised when multiple Unity Editor instances are found and auto-detection cannot proceed."""
+    
+    def __init__(self, message: str, project_roots: list[str]):
+        super().__init__(message)
+        self.project_roots = project_roots
+
+
+def discover_unity_project_roots():
+    """Import and call the discover_unity_project_roots function."""
+    from coplay_mcp_server.process_discovery import discover_unity_project_roots as _discover
+    return _discover()
+
+
+class UnityRpcClient:
+    """Client for communicating with Unity Editor via file-based RPC."""
+
+    def __init__(self) -> None:
+        self._unity_project_root: Optional[str] = None
+        self._pending_requests: Dict[str, concurrent.futures.Future[Any]] = {}
+        self._observer: Optional[Observer] = None
+        self._response_handler: Optional[ResponseFileHandler] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+
+    def set_unity_project_root(self, project_root: str) -> None:
+        """Set the Unity project root and start watching for responses."""
+        if self._unity_project_root == project_root:
+            return
+
+        # Stop existing watcher if any
+        self._stop_file_watcher()
+
+        self._unity_project_root = project_root
+        self._start_file_watcher()
+        logger.info(f"Unity project root set to: {project_root}")
+
+    def auto_detect_unity_project_root(self) -> bool:
+        """
+        Automatically detect and set Unity project root if exactly one Unity instance is running.
+        
+        Returns:
+            bool: True if successfully auto-detected and set, False otherwise.
+        """
+        try:
+            project_roots = discover_unity_project_roots()
+            
+            if len(project_roots) == 1:
+                # Exactly one Unity instance found - auto-set it
+                project_root = project_roots[0]
+                self.set_unity_project_root(project_root)
+                logger.info(f"Auto-detected Unity project root: {project_root}")
+                return True
+            elif len(project_roots) == 0:
+                logger.warning("No Unity instances found for auto-detection")
+                return False
+            else:
+                logger.warning(f"Multiple Unity instances found ({len(project_roots)}), cannot auto-detect. Available projects: {project_roots}")
+                return False
+                
+        except Exception as e:
+            logger.error(f"Failed to auto-detect Unity project root: {e}")
+            return False
+
+    def _start_file_watcher(self) -> None:
+        """Start watching for response files."""
+        if not self._unity_project_root:
+            return
+
+        requests_dir = (
+            Path(self._unity_project_root) / "Temp" / "Coplay" / "MCPRequests"
+        )
+        if not requests_dir.exists():
+            logger.warning(f"Unity requests directory does not exist: {requests_dir}")
+            return
+
+        # Store the current event loop for thread-safe communication
+        try:
+            self._loop = asyncio.get_running_loop()
+        except RuntimeError:
+            logger.warning(
+                "No running event loop found, file watching may not work properly"
+            )
+            return
+
+        self._response_handler = ResponseFileHandler(
+            self._handle_response_file_sync, self._loop
+        )
+        self._observer = Observer()
+        self._observer.schedule(
+            self._response_handler, str(requests_dir), recursive=False
+        )
+        self._observer.start()
+        logger.info(f"Started watching for responses in: {requests_dir}")
+
+    def _stop_file_watcher(self) -> None:
+        """Stop watching for response files."""
+        if self._observer:
+            self._observer.stop()
+            self._observer.join()
+            self._observer = None
+            self._response_handler = None
+
+    def _handle_response_file_sync(self, file_path: Path) -> None:
+        """Handle a response file from Unity (synchronous version for thread safety)."""
+        try:
+            logger.info(f"Handling file change: {file_path}")
+
+            if not file_path.name.startswith(
+                "response_"
+            ) or not file_path.name.endswith(".json"):
+                return
+
+            # Read response file synchronously
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    response_json = f.read()
+            except Exception as e:
+                logger.error(f"Failed to read response file {file_path}: {e}")
+                return
+
+            response_data = json.loads(response_json)
+            request_id = response_data.get("id")
+            if request_id not in self._pending_requests:
+                logger.warning(f"No pending request found for ID: {request_id}")
+                return
+
+            future = self._pending_requests.pop(request_id)
+
+            if "error" in response_data and response_data["error"]:
+                error_msg = response_data["error"]
+                if isinstance(error_msg, dict):
+                    error_msg = error_msg.get("message", str(error_msg))
+                future.set_exception(Exception(str(error_msg)))
+            else:
+                future.set_result(response_data.get("result"))
+
+            # Clean up response file
+            try:
+                file_path.unlink()
+                logger.debug(f"Deleted response file: {file_path}")
+            except Exception as e:
+                logger.warning(f"Failed to delete response file {file_path}: {e}")
+
+        except Exception as e:
+            logger.error(f"Error handling response file {file_path}: {e}")
+
+    def _is_image_function(self, method: str) -> bool:
+        """Check if this is a function that returns images."""
+        image_functions = {
+            "get_scene_view_screenshot",
+            "capture_ui_canvas",
+        }
+        return method in image_functions
+
+    def _process_image_response(self, response: Any) -> Any:
+        """Convert ImagePath to FastMCP Image object for proper MCP compatibility."""
+        if isinstance(response, dict) and "ImagePath" in response:
+            image_path = response["ImagePath"]
+            if image_path and isinstance(image_path, str):
+                logger.debug(f"Processing image response with path: {image_path}")
+                try:
+                    # Create FastMCP Image object from the file path
+                    return Image(path=image_path)
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to create FastMCP Image from path {image_path}: {e}"
+                    )
+        return response
+
+    async def execute_request(
+        self,
+        method: str,
+        params: Optional[Dict[str, Any]] = None,
+        timeout: float = 60.0,
+    ) -> Any:
+        """Execute an RPC request to Unity Editor."""
+        if not self._unity_project_root:
+            # Try to auto-detect Unity project root
+            if not self.auto_detect_unity_project_root():
+                # Auto-detection failed, provide helpful error message
+                try:
+                    project_roots = discover_unity_project_roots()
+                    if len(project_roots) == 0:
+                        raise NoUnityInstancesError(
+                            "No Unity Editor instances found. Please start Unity Editor and call set_unity_project_root with the project path."
+                        )
+                    else:
+                        project_list = "\n".join([f"  - {root}" for root in project_roots])
+                        raise MultipleUnityInstancesError(
+                            f"Multiple Unity Editor instances found. Please call set_unity_project_root with one of these project paths:\n{project_list}",
+                            project_roots
+                        )
+                except UnityProjectRootError:
+                    # Re-raise our custom exceptions as-is
+                    raise
+                except Exception as e:
+                    raise RuntimeError(
+                        "Unity project root is not set and auto-detection failed. Call set_unity_project_root first."
+                    ) from e
+
+        requests_dir = (
+            Path(self._unity_project_root) / "Temp" / "Coplay" / "MCPRequests"
+        )
+        if not requests_dir.exists():
+            raise RuntimeError(
+                "Unity Editor is not running at the specified project root"
+            )
+
+        request_id = str(uuid.uuid4())
+        request_file = requests_dir / f"req_{request_id}.json"
+
+        # Create request data
+        request_data = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+            "params": params or {},
+        }
+
+        # Create concurrent.futures.Future for thread-safe completion
+        future: concurrent.futures.Future[Any] = concurrent.futures.Future()
+        self._pending_requests[request_id] = future
+
+        try:
+            # Write request file
+            async with aiofiles.open(request_file, "w", encoding="utf-8") as f:
+                await f.write(json.dumps(request_data, indent=2))
+
+            logger.debug(f"Created request file: {request_file}")
+
+            # Wait for response with timeout using asyncio.wrap_future
+            try:
+                wrapped_future = asyncio.wrap_future(future)
+                result = await asyncio.wait_for(wrapped_future, timeout=timeout)
+
+                # Post-process response for image functions
+                if self._is_image_function(method):
+                    result = self._process_image_response(result)
+
+                return result
+            except asyncio.TimeoutError:
+                raise TimeoutError(
+                    f"Request {method} timed out after {timeout} seconds"
+                )
+
+        except Exception as e:
+            # Clean up on error
+            self._pending_requests.pop(request_id, None)
+            try:
+                if request_file.exists():
+                    request_file.unlink()
+            except Exception:
+                pass
+            raise e
+
+    def close(self) -> None:
+        """Close the Unity RPC client and clean up resources."""
+        self._stop_file_watcher()
+
+        # Cancel any pending requests
+        for future in self._pending_requests.values():
+            if not future.done():
+                future.cancel()
+        self._pending_requests.clear()
+
+
+class ResponseFileHandler(FileSystemEventHandler):
+    """File system event handler for Unity response files."""
+
+    def __init__(
+        self, callback, loop: Optional[asyncio.AbstractEventLoop] = None
+    ) -> None:
+        super().__init__()
+        self._callback = callback
+        self._loop = loop
+        self._processed_files: set[str] = set()
+        self._executor = concurrent.futures.ThreadPoolExecutor(max_workers=2)
+
+    def on_created(self, event) -> None:
+        """Handle file creation events."""
+        if event.is_directory:
+            return
+
+        file_path = Path(event.src_path)
+        if file_path.name.startswith("response_") and file_path.name.endswith(".json"):
+            self._process_file_threadsafe(file_path)
+
+    def on_modified(self, event) -> None:
+        """Handle file modification events."""
+        if event.is_directory:
+            return
+
+        file_path = Path(event.src_path)
+        if file_path.name.startswith("response_") and file_path.name.endswith(".json"):
+            # Avoid processing the same file multiple times
+            if str(file_path) not in self._processed_files:
+                self._processed_files.add(str(file_path))
+                self._process_file_threadsafe(file_path)
+
+    def _process_file_threadsafe(self, file_path: Path) -> None:
+        """Process a response file in a thread-safe manner."""
+
+        def process_with_delay():
+            # Small delay to ensure file is fully written
+            import time
+
+            time.sleep(0.1)
+
+            if file_path.exists():
+                self._callback(file_path)
+
+        # Submit to thread pool to avoid blocking the file watcher
+        self._executor.submit(process_with_delay)

coplay_mcp_server-1.4.1.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: coplay-mcp-server
+Version: 1.4.1
+Summary: A Model Context Protocol (MCP) server for Coplay, providing Unity integration capabilities
+Project-URL: Homepage, https://coplay.dev/
+Project-URL: Repository, https://github.com/CoplayDev/coplay-unity-plugin
+Project-URL: Documentation, https://docs.coplay.dev/
+Project-URL: Issues, https://github.com/CoplayDev/coplay-unity-plugin/issues
+Author-email: Coplay Dev <dev@coplay.com>
+Maintainer-email: Coplay Dev <dev@coplay.com>
+License: MIT
+License-File: LICENSE
+Keywords: coplay,mcp,model-context-protocol,unity,unity-editor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: anyio>=4.10.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: watchdog>=6.0.0
+Description-Content-Type: text/markdown
+
+# Coplay MCP Server
+
+A Model Context Protocol (MCP) server for Coplay, providing Unity Editor integration capabilities through MCP tools.
+
+## Features
+
+- **Schema-Based Tool Registration**: Dynamically registers tools from JSON schema files, ensuring compatibility with Backend's AssistantMode.NORMAL
+- **Unity Project Discovery**: Automatically discover running Unity Editor instances and their project roots
+- **Unity Editor State**: Retrieve current Unity Editor state and scene hierarchy information
+- **Script Execution**: Execute arbitrary C# scripts within the Unity Editor
+- **Log Management**: Access and filter Unity console logs
+- **GameObject Hierarchy**: List and filter GameObjects in the scene hierarchy
+- **Task Creation**: Create new Coplay tasks directly from MCP clients
+- **Parameter Validation**: Automatic parameter validation and type conversion based on tool schemas
+- **Version Compatibility**: Tools are locked to specific schema versions, ensuring compatibility with Unity plugin versions
+
+## Usage
+
+### As an MCP server
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "coplay-mcp": {
+      "autoApprove": [],
+      "disabled": false,
+      "timeout": 60,
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "coplay-mcp-server@latest"
+      ]
+    }
+  }
+}
+```
+
+

coplay_mcp_server-1.4.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+coplay_mcp_server/__init__.py,sha256=S7pbUyOcTUgBTjPhI-Nll37HXJaqgLcjf0rhlb1BrnE,92
+coplay_mcp_server/code_generator.py,sha256=eZhnehQFsE-kMkPVESyzKDLOuTmdnTyX_ZTSljmIj9M,13070
+coplay_mcp_server/image_utils.py,sha256=0IGwazKwkhS95S1LsFweuFOgXH0uHlZtlfqt0547Xbo,2800
+coplay_mcp_server/process_discovery.py,sha256=RnmVPNfYZsJoKGpaZYpxJLbco24_LZlr-oM-zQ3lXkg,5983
+coplay_mcp_server/server.py,sha256=lHG85J55bPu8Cdx_BojHvCdpi2udTB_UflOOpdFWz3M,7626
+coplay_mcp_server/unity_client.py,sha256=apjP7-icQFuMP8vNzAZdMFu-HNJbSNT0vXTthwX-vus,12959
+coplay_mcp_server/generated_tools/.gitignore,sha256=TlBJtSSzMbAK1WY8wWpckwcbQjWH1JpsI6-5dJ8ve_g,103
+coplay_mcp_server/generated_tools/__init__.py,sha256=WzV0HQqurRGPjGJi1bUboLIYafTd_QFqegcM-iL557k,159
+coplay_mcp_server/generated_tools/agent_tool_tools.py,sha256=coWVRszqrk2BrmjXhWsnYmwCMBvAEACUjhBGM6S7GP8,13161
+coplay_mcp_server/generated_tools/coplay_tool_tools.py,sha256=REyx3cLHJ1MzElhmM5JEsFZZRD0nV8dH1D7vDE9ADNM,2151
+coplay_mcp_server/generated_tools/image_tool_tools.py,sha256=WGbKcTqejJxPSJvKa3GzlGPsFnjrrBHF0HifmfFnDQU,6079
+coplay_mcp_server/generated_tools/input_action_tool_tools.py,sha256=zuDJjnVGqYSOLErZUMj0d3QM1-nQXLEomk7s3iOF4eU,22979
+coplay_mcp_server/generated_tools/package_tool_tools.py,sha256=7-rbM3yLgjbomHhSwLapPqWWhJJG62N7E3_Oc7n8PHA,7865
+coplay_mcp_server/generated_tools/profiler_functions_tools.py,sha256=lXW8-ms8VKcsRlkOmRfjmFouJvGAT9b57D8Y4eOhW48,2250
+coplay_mcp_server/generated_tools/scene_view_functions_tools.py,sha256=QOU0-BuU_Ey-rvuT-OspmDZywFnKA0P51LYAp4hFJVI,2103
+coplay_mcp_server/generated_tools/screenshot_tool_tools.py,sha256=IOc1pPTJheG40JqK-0AmGVdYTsMUNnoRSRSc_Fn9qA8,3582
+coplay_mcp_server/generated_tools/snapping_functions_tools.py,sha256=7iAz5C_CEQb5VON9TlbKK8NaKPNxgDA8LDndUrE4RhM,14956
+coplay_mcp_server/generated_tools/ui_functions_tools.py,sha256=wTEvi0xc2chk9Ta3hyWCwRyalksDpXaWIFuYzpigVPo,14454
+coplay_mcp_server/generated_tools/unity_functions_tools.py,sha256=QkQswrZQxDrnyLO-d4QMmGY6i8bY08C_P3Zd1Lipef8,59290
+coplay_mcp_server-1.4.1.dist-info/METADATA,sha256=6PtqXCH-wEaADDpmV9eu9CUTOZi7BZ4KqEyOTcerWT0,2571
+coplay_mcp_server-1.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+coplay_mcp_server-1.4.1.dist-info/entry_points.txt,sha256=SKRD69ycL3CtXfaBghc8QIicPFCvO5XzqDyUSn25Eqs,130
+coplay_mcp_server-1.4.1.dist-info/licenses/LICENSE,sha256=JOvqcPTq0pJwgFmq0GSYUZOvZu4rPfmiRG20bGTlx6o,1067
+coplay_mcp_server-1.4.1.dist-info/RECORD,,

coplay_mcp_server-1.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

coplay_mcp_server-1.4.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+coplay-generate-tools = coplay_mcp_server.code_generator:main
+coplay-mcp-server = coplay_mcp_server.server:main

coplay_mcp_server-1.4.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Coplay Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.