unity-test-runner-mcp

cairns-games/unity-test-runner-mcp

3.1

If you are the rightful owner of unity-test-runner-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Unity Test Runner MCP Bridge is a Unity package that integrates a Model Context Protocol (MCP) server with Unity's Test Runner, allowing for programmatic test execution and result retrieval via HTTP/JSON-RPC.

Tools
6
Resources
0
Prompts
0

Unity Test Runner MCP Bridge

A Unity package that provides a Model Context Protocol (MCP) server bridge for Unity's Test Runner, enabling programmatic test execution and result retrieval through HTTP/JSON-RPC.

Features

  • 🚀 MCP Server Integration - HTTP server running on configurable port (default: 7850)
  • 🧪 Full Test Runner Control - List, run, and manage Unity tests programmatically
  • 📊 Real-time Test Results - Get detailed test results and execution status
  • 🔧 Script Compilation Control - Trigger Unity script recompilation on demand
  • 🎯 EditMode & PlayMode Support - Run tests in both Unity test modes
  • 📝 MVVM Architecture - Clean separation of concerns with data binding
  • 🔄 Unity Runtime Data Binding - Reactive UI updates using Unity's binding system

Installation

Via Unity Package Manager (Git URL)

  1. Open Unity Package Manager (Window > Package Manager)
  2. Click the "+" button and select "Add package from git URL..."
  3. Enter: https://github.com/cairnsgames/unity-test-runner-mcp.git

Via manifest.json

Add this line to your Packages/manifest.json:

{
  "dependencies": {
    "com.cairnsgames.unitytestmcp": "https://github.com/cairnsgames/unity-test-runner-mcp.git"
  }
}

Local Installation

  1. Clone this repository
  2. Copy the package folder to your Unity project's Packages directory

Requirements

  • Unity 2021.3 or later (Unity 6000 recommended)
  • Unity Test Framework package 1.5.1+
  • Newtonsoft.Json 3.0.0+
  • .NET Standard 2.1

Usage

Opening the MCP Bridge Window

  1. In Unity Editor, go to Window > Test Runner MCP Bridge
  2. The window will show the server status and test results
  3. Server starts automatically (configurable)

MCP Tools Available

The bridge provides the following MCP tools through JSON-RPC:

unity_list_tests

List all available Unity tests.

Parameters:

  • testMode (string, optional): "EditMode", "PlayMode", or "All"
  • category (string, optional): Filter tests by category
unity_run_tests

Run specific Unity tests.

Parameters:

  • testMode (string, optional): "EditMode" or "PlayMode" (default: "EditMode")
  • testNames (array, optional): Specific test names to run (empty for all)
  • category (string, optional): Run tests in specific category
unity_get_test_results

Get the results of the last test run.

Parameters:

  • includeDetails (boolean, optional): Include detailed test information (default: true)
unity_clear_test_results

Clear all test results.

Parameters: None

unity_get_test_status

Get the current test execution status.

Parameters: None

unity_request_script_compilation

Request Unity to recompile all scripts.

Parameters: None

Example HTTP Requests

List Tests
curl -X POST http://localhost:7850/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
Run Tests
curl -X POST http://localhost:7850/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "unity_run_tests",
      "arguments": {
        "testMode": "EditMode"
      }
    }
  }'

Architecture

The package follows MVVM (Model-View-ViewModel) architecture:

Core Components

  • McpServer - HTTP server handling JSON-RPC 2.0 requests
  • McpTools - MCP tool definitions and execution logic
  • McpProtocol - MCP protocol implementation and types
  • TestRunnerDataSource - ViewModel with INotifyPropertyChanged for data binding
  • TestRunnerMCPWindow - Unity Editor window with reactive UI
  • McpSettings - Persistent settings using ScriptableObject

Data Flow

Unity Test Runner API
        ↓
TestRunnerDataSource (ViewModel)
        ↓
    McpServer
        ↓
HTTP/JSON-RPC Interface
        ↓
    MCP Client

Configuration

Settings

Settings are persisted in Assets/Editor/TestRunnerMCPSettings.asset:

  • Port - Server port (default: 7850)
  • Auto-Start Server - Start server when window opens
  • Enable Logging - Show server activity logs
  • Max Log Entries - Maximum log entries to keep (default: 100)

Changing Settings

  1. Open the Test Runner MCP Bridge window
  2. Modify settings in the UI
  3. Changes are saved automatically

Development

Running Tests

The package includes comprehensive unit and integration tests:

# In Unity
1. Window > General > Test Runner
2. Select EditMode tests
3. Run CairnsGames.UnityTestRunner.Editor.Tests

Current test coverage: 100% (69/69 tests passing)

Project Structure

com.cairnsgames.unitytestmcp/
├── Editor/
│   ├── Mcp/
│   │   ├── McpProtocol.cs      # Protocol definitions
│   │   ├── McpServer.cs        # HTTP server
│   │   └── McpTools.cs         # Tool implementations
│   ├── TestRunnerDataSource.cs # ViewModel
│   ├── TestRunnerMCPWindow.cs  # Editor window
│   └── McpSettings.cs          # Settings management
├── Tests/
│   └── Editor/
│       ├── MCPBridgeIntegrationTests.cs
│       ├── McpProtocolTests.cs
│       ├── MCPServerTests.cs
│       ├── McpToolsTests.cs
│       └── TestRunnerDataSourceTests.cs
├── package.json
├── README.md
├── LICENSE
└── CHANGELOG.md

API Reference

MCP Protocol

The server implements MCP protocol version 2024-11-05 with JSON-RPC 2.0.

Supported Methods

  • initialize - Initialize MCP session
  • initialized - Confirm initialization
  • tools/list - List available tools
  • tools/call - Execute a tool
  • ping - Health check

Error Codes

  • -32700 - Parse error
  • -32600 - Invalid request
  • -32601 - Method not found
  • -32602 - Invalid params
  • -32603 - Internal error

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow Unity C# coding conventions
  • Add tests for new features
  • Update documentation as needed
  • Ensure all tests pass before submitting PR

Troubleshooting

Server Won't Start

  • Check if port 7850 is already in use
  • Verify Unity Editor permissions for network access
  • Try a different port in settings

Tests Not Being Discovered

  • Ensure Unity has compiled all scripts
  • Use the "Request Script Compilation" tool
  • Check test assembly definitions

Connection Refused

  • Verify the server is running (check window status)
  • Confirm correct port number
  • Check firewall settings for localhost

License

MIT License - see file for details

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Acknowledgments

Changelog

See for version history and release notes.