Metadata-Version: 2.4
Name: weird-unity-mcp
Version: 0.1.0
Summary: A custom MCP server for Unity with GameObject and Animation tools
Project-URL: Homepage, https://github.com/Ngocngok/A-weird-unity-mcp
Project-URL: Repository, https://github.com/Ngocngok/A-weird-unity-mcp
Project-URL: Documentation, https://github.com/Ngocngok/A-weird-unity-mcp#readme
Project-URL: Issues, https://github.com/Ngocngok/A-weird-unity-mcp/issues
Author-email: WeirdUnityMcp <long.nt184287@gmail.com>
License: MIT
License-File: LICENSE
Keywords: animation,gameobject,mcp,model-context-protocol,unity,unity-editor
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: watchdog>=6.0.0
Description-Content-Type: text/markdown

# Weird Unity MCP Server

A custom Model Context Protocol (MCP) server for Unity Editor that provides GameObject and Animation manipulation tools.

## Overview

This MCP server allows AI assistants (like Claude) to interact with Unity Editor through a file-based JSON-RPC protocol. It enables creating, modifying, and managing GameObjects and animations directly from an AI chat interface.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude/GPT)                │
└────────────────────────────┬────────────────────────────────┘
                             │ MCP over stdio
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              Python MCP Server (weird-unity-mcp)            │
│  • set_unity_project_root()                                  │
│  • list_unity_projects()                                     │
│  • GameObject tools (12 tools)                               │
│  • Animation tools (12 tools)                                │
└────────────────────────────┬────────────────────────────────┘
                             │ File-based JSON-RPC
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              Temp/WeirdUnityMcp/                             │
│         req_<uuid>.json  →  response_<uuid>.json            │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│            Unity Editor Plugin (C#)                         │
│  • GameObject handlers                                       │
│  • Animation handlers                                        │
└─────────────────────────────────────────────────────────────┘
```

## Requirements

- Python 3.11+
- Unity 2022.3+
- Operating System: Windows, macOS, or Linux

## Installation

### Python MCP Server

```bash
# Navigate to the project directory
cd E:\Haha\WeirdUnityMcpServer

# Install in development mode
pip install -e .
```

### Unity Plugin

1. Copy the `unity-plugin/Assets/WeirdUnityMcp` folder to your Unity project's `Assets/` folder
2. Unity will automatically compile the scripts
3. Open the server window: `Tools > Weird Unity MCP Server`

## Usage

### Starting the Server

**Python Side:**
```bash
weird-unity-mcp
```

**Unity Side:**
- Open Unity Editor with your project
- The server auto-initializes on startup
- Or open `Tools > Weird Unity MCP Server`

### MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) with:

```json
{
  "mcpServers": {
    "weird-unity": {
      "command": "weird-unity-mcp",
      "env": {
        "WEIRDMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Available Tools

#### Core Tools
| Tool | Description |
|------|-------------|
| `set_unity_project_root` | Set the Unity project path (call first) |
| `list_unity_projects` | List all running Unity Editor instances |

#### GameObject Tools (12 tools)
| Tool | Description |
|------|-------------|
| `create_gameobject` | Create a new GameObject |
| `delete_gameobject` | Delete a GameObject |
| `set_transform` | Set position, rotation, scale |
| `parent_gameobject` | Parent a GameObject to another |
| `add_component` | Add a component to a GameObject |
| `get_component_property` | Get a component property value |
| `set_component_property` | Set a component property value |
| `find_gameobject` | Find GameObjects by name |
| `duplicate_gameobject` | Duplicate a GameObject |
| `create_prefab` | Create a prefab from a GameObject |
| `instantiate_prefab` | Instantiate a prefab into the scene |
| `list_gameobjects` | List all GameObjects in the scene |
| `rename_gameobject` | Rename a GameObject |

#### Animation Tools (12 tools)
| Tool | Description |
|------|-------------|
| `create_animation_clip` | Create a new AnimationClip |
| `create_animator_controller` | Create a new AnimatorController |
| `add_keyframe` | Add a keyframe to an AnimationClip |
| `set_curve` | Set an animation curve with keyframes |
| `add_animation_state` | Add a state to an AnimatorController |
| `add_transition` | Add a transition between states |
| `set_transition_condition` | Add a condition to a transition |
| `add_animator_parameter` | Add a parameter to an AnimatorController |
| `set_animator_parameter` | Set a parameter value on an Animator |
| `get_animation_clips` | Get all AnimationClips from an Animator |
| `set_animation_speed` | Set animation playback speed |
| `play_animation` | Play an animation state |
| `set_animation_wrap_mode` | Set wrap mode for an AnimationClip |
| `get_animation_state_name` | Get current animation state |

### Example Usage

In your AI chat:

```
# Set the Unity project first
set_unity_project_root("C:/MyUnityProject")

# Create a GameObject
create_gameobject(name="Player", position="0,1,0")

# Add a Rigidbody component
add_component(gameobject_path="Player", component_type="Rigidbody")

# Create an animation
create_animation_clip(name="Walk", save_path="Assets/Animations")

# Add keyframes
add_keyframe(clip_path="Assets/Animations/Walk.anim", property_path="m_LocalPosition.x", time=0, value="0")
add_keyframe(clip_path="Assets/Animations/Walk.anim", property_path="m_LocalPosition.x", time=1, value="5")
```

## Project Structure

```
weird-unity-mcp/
├── weird_unity_mcp/           # Python package
│   ├── __init__.py
│   ├── __main__.py
│   ├── client.py              # Unity RPC client
│   ├── discovery.py           # Unity process discovery
│   ├── server.py              # MCP server entry point
│   └── tools/
│       ├── gameobject.py      # GameObject tools
│       └── animation.py       # Animation tools
├── unity-plugin/              # Unity C# plugin
│   └── Assets/WeirdUnityMcp/
│       └── Editor/
│           ├── Core/          # Core handler and models
│           └── Handlers/      # Request handlers
│               ├── GameObject/
│               └── Animation/
├── pyproject.toml
└── README.md
```

## Development

### Python Development

```bash
# Install with dev dependencies
pip install -e .

# Run with debug logging
WEIRDMCP_LOG_LEVEL=DEBUG weird-unity-mcp

# Run with file logging
WEIRDMCP_LOG_FILE=mcp.log WEIRDMCP_LOG_LEVEL=INFO weird-unity-mcp
```

### Unity Development

All Unity scripts are in `Assets/WeirdUnityMcp/Editor/`:

- `Core/McpModels.cs` - Request/response models
- `Core/McpRequestHandler.cs` - Main request router
- `Core/WeirdUnityMcpEditor.cs` - Editor window
- `Handlers/GameObject/` - GameObject operation handlers
- `Handlers/Animation/` - Animation operation handlers

## Adding New Tools

### Python Side (tools/*.py)

```python
@mcp.tool()
async def my_new_tool(param1: str, param2: float = 1.0) -> dict:
    """Description of what this tool does."""
    return await client.execute_request("my_new_tool", {
        "param1": param1,
        "param2": str(param2)
    })
```

### Unity Side (Handlers/*/*Handler.cs)

```csharp
public static Core.McpResponse MyNewHandler(Core.McpRequest request)
{
    try
    {
        string param1 = request.GetParam("param1", "");
        // ... do work ...

        return Core.McpResponse.Success(request.id,
            new Core.McpResult("Operation successful"));
    }
    catch (Exception e)
    {
        return Core.McpResponse.Error(request.id, e.Message);
    }
}
```

Then add routing in `McpRequestHandler.RouteToHandler()`:

```csharp
case "my_new_tool":
    return Handlers.MyCategory.MyNewHandler(request);
```

## Troubleshooting

### Server not responding
- Check Unity Editor is running with the project open
- Verify `set_unity_project_root()` was called
- Check the request directory exists: `{ProjectRoot}/Temp/WeirdUnityMcp/`

### Tools not available
- Restart the MCP server
- Verify Unity plugin compiled (check Console)
- Check for Python errors in logs

### Communication timeout
- Default timeout is 30 seconds
- Unity might be processing heavy operations
- Check Unity Console for errors

## License

MIT License

## Credits

Inspired by the Coplay MCP Server architecture.
