Skip to content

README_STDIO.md

Latest commit

 

History

History
186 lines (129 loc) · 5.31 KB

README_STDIO.md

File metadata and controls

186 lines (129 loc) · 5.31 KB

Unity Code MCP STDIO Bridge

A Python package that bridges MCP (Model Context Protocol) over STDIO to a Unity TCP Server.

Overview

This bridge enables MCP client to communicate with the UnityCodeMcpServer running inside Unity Editor via TCP. The bridge:

  1. Receives MCP messages via STDIO
  2. Forwards them to the Unity TCP Server
  3. Returns responses back via STDIO

Prerequisites

  • Python 3.10+ - Required for the bridge
  • uv - Fast Python package manager (install uv)
  • Unity Editor - With UnityCodeMcpServer running (auto-starts when Unity opens)

Installing uv

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Using uv (Recommended)

No installation needed! uv runs the package directly:

uv run --directory /path/to/STDIO~ unity-code-mcp-stdio

Using pip (Alternative)

pip install -e /path/to/STDIO~
unity-code-mcp-stdio

Usage

Command Line Arguments

Argument Default Description
--retry-time 2 Seconds between connection retries
--retry-count 5 Maximum number of connection retries

Note: The host is hardcoded to localhost and the port is read automatically from UnityCodeMcpServerSettings.asset inside the Unity project.

Examples

# Basic usage (from STDIO directory)
uv run unity-code-mcp-stdio

# Run from any directory using --directory
uv run --directory "C:/path/to/STDIO~" unity-code-mcp-stdio

# With retry configuration
uv run --directory "C:/path/to/STDIO~" unity-code-mcp-stdio --retry-time 3 --retry-count 10

MCP Configuration

{
  "mcpServers": {
    "unity": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/YOUR_USERNAME/path/to/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
        "unity-code-mcp-stdio"
      ]
    }
  }
}

Note: Replace C:/Users/YOUR_USERNAME/path/to/... with the actual path to your Unity project's STDIO folder. The port is read automatically from UnityCodeMcpServerSettings.asset inside the Unity project.

Architecture

┌─────────────────┐      TCP       ┌─────────────────┐     STDIO      ┌─────────────────┐
│                 │                │                 │                │                 │
│  Unity Editor   │ ◄────────────► │  STDIO Bridge   │ ◄────────────► │  MCP Client     │
│                 │                │                 │                │                 │
└─────────────────┘                └─────────────────┘                └─────────────────┘

Communication Flow

  1. MCP Client → Bridge (STDIO): MCP Client sends JSON-RPC 2.0 messages via stdin
  2. Bridge → Unity (TCP): Bridge forwards messages to Unity Tcp Server
  3. Unity → Bridge (TCP): Unity Tcp Server responds back to Bridge
  4. Bridge → MCP Client (STDIO): Bridge writes response to stdout

Development

Running Tests

cd /path/to/STDIO

uv run --extra dev pytest tests/

Windows Note: If you encounter "Failed to canonicalize script path" errors with uv run, use the venv Python directly as shown below.

# Use the venv Python directly (avoids uv script canonicalization issues):
.\.venv\Scripts\python.exe -m pytest tests/ -v

Development Install

# Sync dependencies including dev extras
uv sync --extra dev

# Alternative: pip install
uv pip install -e ".[dev]"

Testing with Postman

Postman supports MCP (Model Context Protocol) natively, including STDIO transport. You can use Postman to test and debug the STDIO Bridge.

Prerequisites

  • Postman Desktop App (v11.35+) - Download here
  • Unity Editor running with UnityCodeMcpServer active

Step-by-Step Guide

  1. Open Postman and create or select a workspace

  2. Create a new MCP request:

    • Click New → MCP
    • Select STDIO as the transport type

  3. Configure the STDIO command:

    uv run --directory "C:/Users/YOUR_USERNAME/path/to/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO" unity-code-mcp-stdio

    Tip: You can also paste JSON configuration directly:

    {
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "C:/Users/YOUR_USERNAME/path/to/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
    "unity-code-mcp-stdio"
  ]
}

  4. Click "Connect" - Postman will connect and discover available tools, prompts, and resources

Reference

For more details, see the official Postman documentation:

License

MIT
⚡