Contributing

Contributing to Unity-MCP

We welcome contributions from the community. Whether you have ideas for new tools, bug fixes, or documentation improvements, your help is appreciated.

Ways to Contribute

• Bug reports with reproduction steps
• Feature requests for new AI tools or integration improvements
• Code contributions: bug fixes, new tool implementations, performance work, test coverage
• Documentation: tutorials, API docs, translations
• Community support: answering questions, reviewing pull requests

Getting Started

Prerequisites

• Unity 2022.3 LTS or newer
• .NET 9.0 SDK for server development
• Git for version control
• GitHub account for collaboration

Setting Up the Development Environment

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/Unity-MCP.git
cd Unity-MCP
git remote add upstream https://github.com/IvanMurzak/Unity-MCP.git

2. Unity Plugin Development

1. Open Unity Hub.
2. Click "Open" and select the Unity-MCP-Plugin folder.
3. Let Unity import all assets and compile scripts.
4. Verify no compilation errors in the Console window.

Unity handles C# compilation automatically -- there is no separate build command for the plugin.

3. MCP Server Development

cd Unity-MCP-Server

# Build
dotnet build com.IvanMurzak.Unity.MCP.Server.csproj

# Run with stdio transport
dotnet run --project com.IvanMurzak.Unity.MCP.Server.csproj -- --client-transport stdio --port 8080

# Run with HTTP transport
dotnet run --project com.IvanMurzak.Unity.MCP.Server.csproj -- --client-transport streamableHttp --port 8080

Cross-platform publish (creates executables in publish/ for win-x64, win-x86, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64):

# Linux/macOS
./build-all.sh

# Windows PowerShell
.\build-all.ps1

4. MCP Inspector (Debugging)

Requires Node.js:

Commands/start_mcp_inspector.bat

Running Tests

Tests run inside the Unity Editor via Window > General > Test Runner.

Mode	Path
EditMode	Assets/root/Tests/Editor
PlayMode	Assets/root/Tests/Runtime

Testing patterns:

• Extend BaseTest -- provides [UnitySetUp] (initializes singleton, creates logger) and [UnityTearDown] (destroys all GameObjects).
• Use [UnityTest] with IEnumerator return type.
• BaseTest.RunTool(string toolName, string json) helper executes a tool and asserts success.
• Temp files via Path.GetTempFileName(), cleaned up in [UnityTearDown].

Development Workflow

1. Create a Feature Branch

git fetch upstream
git checkout main
git merge upstream/main

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Your Changes

Follow the coding conventions described below.

3. Test Your Changes

• Build successfully without warnings.
• Test in Unity Editor with various scenarios.
• Verify server compatibility if you changed server code.
• Run existing tests via the Unity Test Runner.

4. Commit and Push

git add .
git commit -m "feat: add new tool for procedural terrain generation"
git push origin feature/your-feature-name

5. Create a Pull Request

1. Open your fork on GitHub.
2. Click "Pull Request" and select your feature branch.
3. Fill out the PR description with details of your changes.
4. Link related issues using keywords like "Fixes #123".

Important: PRs from untrusted contributors (outside collaborators) require a maintainer to add the ci-ok label before CI workflows will run.

Coding Conventions

These conventions apply across both the Plugin (C#/Unity) and Server (C#/.NET) sub-projects.

File Header

Every file must start with #nullable enable and include the standard copyright box comment:

/*
------------------------------------------------------------------
  Author: Ivan Murzak (https://github.com/IvanMurzak)
  Repository: GitHub (https://github.com/IvanMurzak/Unity-MCP)
  Copyright (c) 2025 Ivan Murzak
  Licensed under the Apache License, Version 2.0.
  See the LICENSE file in the project root for more information.
------------------------------------------------------------------
*/

#nullable enable

Naming and Structure

• Namespace pattern: com.IvanMurzak.Unity.MCP.[Tier].[Component] (e.g., com.IvanMurzak.Unity.MCP.Editor.API, com.IvanMurzak.Unity.MCP.Runtime.Utils)
• Tool/prompt names: kebab-case with category prefix (e.g., gameobject-create, assets-find, scene-open)
• Tool classes: partial -- one operation per file (e.g., Tool_GameObject is the class, with GameObject.Create.cs, GameObject.Find.cs, GameObject.Destroy.cs as separate files)
• C# naming: PascalCase for public members, standard C# conventions

Thread Safety

All Unity API calls must use MainThread.Instance.Run(() => ...) (synchronous) or MainThread.Instance.RunAsync() (asynchronous). Unity APIs are not thread-safe.

Return Format

Tool methods that return plain strings should prefix with [Success] or [Error] for structured AI feedback:

return "[Success] Created 'Player' at (0, 0, 0)";
return "[Error] GameObject name cannot be null or empty";

MCP Attributes

Attribute	Target	Purpose
[McpPluginToolType]	Class	Marks a class as containing MCP tools
[McpPluginTool]	Method	Marks a method as a callable MCP tool
[McpPluginPromptType]	Class	Marks a class as containing MCP prompts
[McpPluginPrompt]	Method	Marks a method as an MCP prompt
[McpPluginResourceType]	Class	Marks a class as containing MCP resources
[McpPluginResource]	Method	Marks a method as an MCP resource

Plugin Architecture

The plugin uses a three-class hierarchy:

• UnityMcpPlugin -- abstract base (partial, multiple files): Version, HasAnyInstance, IsLogEnabled, GenerateToken, GeneratePortFromDirectory, shared build/config methods
• UnityMcpPluginEditor -- Editor-only singleton: owns the editor MCP connection, static props for Instance, Host, Token, ConnectionState
• UnityMcpPluginRuntime -- Runtime singleton: game-build entry point via UnityMcpPluginRuntime.Initialize().Build()

CI/CD

Workflow Files

Located in .github/workflows/:

Workflow	Trigger	Purpose
release.yml	Push to main	Full release pipeline (18-combination test matrix: 3 Unity versions x 3 test modes x 2 OS)
test_pull_request.yml	PR to main/dev	Validates all test matrix combinations
deploy.yml	Release published / manual	NuGet + Docker Hub deploy
deploy_server_executables.yml	Release published	Cross-platform binary upload to GitHub Releases
bump_version.yml	Manual	Version bump automation
test_pull_request_manual.yml	Manual	Manual test trigger
test_unity_plugin.yml	Called by other workflows	Reusable Unity test workflow

PRs from untrusted contributors require the ci-ok label from a maintainer before CI runs.

Version Bumping

Version is sourced from Unity-MCP-Plugin/Assets/root/package.json. To update all version references across the repo:

.\bump-version.ps1 <version>

Project Structure Overview

Unity-MCP/
├── Unity-MCP-Server/          # C# ASP.NET Core MCP server
│   ├── src/                   # Server source code
│   ├── com.IvanMurzak.Unity.MCP.Server.csproj
│   ├── build-all.sh           # Cross-platform build (Linux/macOS)
│   └── build-all.ps1          # Cross-platform build (Windows)
├── Unity-MCP-Plugin/          # Unity Editor/Runtime plugin
│   └── Assets/root/
│       ├── Runtime/           # Core runtime code
│       ├── Editor/Scripts/
│       │   ├── API/
│       │   │   ├── Tool/      # MCP tools (partial classes, one operation per file)
│       │   │   ├── Prompt/    # MCP prompts
│       │   │   └── Resource/  # MCP resources
│       │   ├── UI/            # Editor windows and AI agent configurators
│       │   └── Utils/         # Editor utilities
│       └── Tests/
│           ├── Editor/        # EditMode tests
│           └── Runtime/       # PlayMode tests
├── Installer/                 # Unity package installer
└── .github/workflows/         # CI/CD pipeline definitions

Pull Request Guidelines

PR Description Template

## Description
Brief description of what this PR accomplishes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- List specific changes
- Include any new files or modified functionality

## Testing
- [ ] Tested locally in Unity Editor
- [ ] Added unit tests for new functionality
- [ ] All existing tests pass

## Related Issues
Fixes #(issue number)

Review Process

Reviewers look for:

1. Code quality: Clean, readable, follows the conventions above
2. Functionality: Works correctly and handles edge cases
3. Thread safety: Unity API calls wrapped in MainThread.Instance.Run()
4. Naming: kebab-case tool names, correct namespace pattern
5. File headers: #nullable enable and copyright box present
6. Testing: Appropriate test coverage

Getting Help

• GitHub Discussions: General questions and community support
• GitHub Issues: Bug reports and feature requests
• Search existing issues and discussions before opening new ones

---

Questions about contributing? Open a discussion on GitHub Discussions.