Contributing to Unity MCP Server

January 27, 2026 · View on GitHub

English | 日本語

Thank you for your interest in contributing to Unity MCP Server! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Development Setup

Prerequisites

  • Unity 2020.3 LTS or newer
  • Node.js 18.x / 20.x / 22.x LTS (23+ not supported)
  • Git

Quick Start

# Clone the repository
git clone https://github.com/akiojin/unity-mcp-server.git
cd unity-mcp-server

# Enable Corepack (recommended) or install pnpm manually
corepack enable
# corepack prepare pnpm@9.15.4 --activate

# Install dependencies (pnpm is required; see packageManager in package.json)
pnpm install --frozen-lockfile

# Run tests
pnpm -C mcp-server test

# Verify installation
node mcp-server/bin/unity-mcp-server --version

Developer Setup (C# LSP)

End users do not need .NET. The MCP server auto-provisions a self-contained C# LSP by tag. As a contributor, you can build it locally if needed:

# Requires .NET 9 SDK
dotnet publish csharp-lsp/Server.csproj -c Release -r <rid> --self-contained true -p:PublishSingleFile=true -o out/<rid>

# Copy to tools directory
cp out/<rid>/server ~/.unity/tools/csharp-lsp/<rid>/server

Git Workflow

This project follows a feature branch workflow with develop as the integration branch:

Branch Naming

PatternPurpose
feature/*New features
bugfix/*Bug fixes
hotfix/*Critical fixes

Workflow

  1. Create a feature branch from develop:

    git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

  2. Make changes following TDD (tests first)

  3. Commit using Conventional Commits format

  4. Push and create a Pull Request to develop

Commit Message Format

This project uses Conventional Commits for automated versioning and changelog generation:

Format

<type>(<scope>): <subject>

<body>

<footer>

Types and Version Impact

TypeDescriptionVersion Impact
featNew featureMinor (2.16.3 → 2.17.0)
fixBug fixPatch (2.16.3 → 2.16.4)
perfPerformance improvementPatch
docsDocumentation onlyNone
styleCode style (formatting)None
refactorCode refactoringNone
testTestsNone
choreBuild/toolingNone
ciCI configurationNone

Breaking Changes

Use either method:

# Method 1: Footer
git commit -m "feat: change API signature

BREAKING CHANGE: captureScreenshot now requires workspaceRoot parameter"

# Method 2: ! suffix
git commit -m "feat!: remove deprecated API"

Examples

# Good examples
git commit -m "feat(screenshot): add explorer mode capture"
git commit -m "fix(connection): resolve timeout issue"
git commit -m "docs: update installation instructions"
git commit -m "test(script): add refs_find tests"

# Bad examples
git commit -m "Update hooks"           # Missing type
git commit -m "feat: change files"     # Too vague
git commit -m "fix stuff"              # Non-descriptive

Git Hooks (Husky)

This project uses Husky to enforce code quality:

Active Hooks

HookAction
commit-msgValidates Conventional Commits format (commitlint)
pre-commitRuns ESLint, Prettier, markdownlint on staged files
pre-pushExecutes test suite before pushing
post-mergeNotifies when dependencies need updating

Configuration Files

FilePurpose
.commitlintrc.jsonConventional Commits rules
.eslintrc.jsonJavaScript code style
.prettierrc.jsonCode formatting
.markdownlint.jsonMarkdown rules

Bypassing Hooks (Emergency Only)

git commit --no-verify -m "emergency fix"
git push --no-verify

Warning: Use sparingly. Hooks prevent CI failures and maintain code quality.

Test-Driven Development (TDD)

This project strictly enforces TDD:

Red-Green-Refactor Cycle

  1. RED: Write a failing test first
  2. GREEN: Write minimal code to pass the test
  3. REFACTOR: Clean up while keeping tests green

Test Categories

CategoryCoverage Requirement
Unit tests80%+ coverage
Integration tests100% critical paths
E2E testsMajor user workflows

Running Tests

# All tests
npm test --workspace=mcp-server

# With coverage
npm run test:coverage --workspace=mcp-server

# Watch mode
npm run test:watch --workspace=mcp-server

# Specific file
npm test --workspace=mcp-server -- tests/unit/handlers/script/ScriptRefsFindToolHandler.test.js

Pull Request Process

Before Creating PR

  • All tests pass locally
  • Code follows style guidelines
  • Commit messages follow Conventional Commits
  • Documentation updated if needed

PR Requirements

  • Target: develop branch (never main directly)
  • Title: Clear description of changes
  • Description: What changed and why

Required CI Checks

CheckDescription
Test & CoverageAll tests pass
Markdown, ESLint & FormattingCode style validation
Commit Message LintConventional Commits format
Packagenpm package builds successfully

Review Process

  1. At least one approval required
  2. All CI checks must pass
  3. No merge conflicts

Code Guidelines

JavaScript/TypeScript

  • Use ES6+ features
  • Follow ESLint configuration
  • Format with Prettier
  • Add JSDoc comments for public APIs
  • No console.log in production code

Unity C#

  • Follow Unity's coding conventions
  • Add XML documentation for public methods
  • Use meaningful names
  • Handle exceptions appropriately

Markdown

  • Follow markdownlint rules
  • Use fenced code blocks with language
  • Keep line length reasonable

Reporting Issues

  • Use GitHub Issues for bugs and features
  • Include Unity version and OS
  • Provide reproduction steps for bugs
  • Include relevant error logs

Questions?

Feel free to open an issue for any questions!

日本語

Unity MCP Server への貢献

Unity MCP Server への貢献にご興味を持っていただきありがとうございます。

開発環境セットアップ

git clone https://github.com/akiojin/unity-mcp-server.git
cd unity-mcp-server
npm ci --workspace=mcp-server
npm test --workspace=mcp-server

コミットメッセージ形式

Conventional Commits を使用：

タイプ説明バージョン影響
feat新機能マイナー ↑
fixバグ修正パッチ ↑
docsドキュメントなし
testテストなし

Gitフック

フックアクション
commit-msgConventional Commits検証
pre-commitESLint/Prettier実行
pre-pushテスト実行

TDD（必須）

  1. RED: テストを先に書く（失敗を確認）
  2. GREEN: テストを通す最小限のコード
  3. REFACTOR: リファクタリング

PRプロセス

  • 対象: developブランチ
  • 全テスト通過必須
  • CIチェック通過必須

詳細は docs/development.md を参照してください。