# AccelByte Unity MCP Server

An MCP (Model Context Protocol) server that gives AI assistants the tools to generate AccelByte AGS uGUI prefabs in Unity projects, look up AccelByte Unity SDK best practices, search Bytewars C# example components, and configure SDK credentials — all from a Claude Code or Cursor session.

## Prerequisites

- Python 3.10+
- Unity Hub with the Unity editor version matching your project (auto-detected from `ProjectSettings/ProjectVersion.txt`)
- `com.accelbyte.ui-tools` package installed in the target Unity project (see [Installing the Unity Package](#installing-the-unity-package))

## Installation

```bash
cd accelbyte-unity-mcp
pip install -r requirements.txt
python server.py
```

No cache generation step is needed. Unlike the Unreal MCP server, this server talks directly to the live Unity project and editor — there is no offline symbol database to build.

## MCP Configuration

Add the server to the `.mcp.json` at your Unity project root so Claude Code starts it automatically on session load:

```json
{
  "mcpServers": {
    "accelbyte-unity-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["<PathToRepo>\\accelbyte-unity-mcp\\server.py"]
    }
  }
}
```

## Installing the Unity Package

Copy the embedded package into your Unity project:

```powershell
Copy-Item -Path "<PathToRepo>\accelbyte-unity-mcp\data\com.accelbyte.ui-tools" `
          -Destination "<YourUnityProject>\Packages\com.accelbyte.ui-tools" `
          -Recurse -Force
```

Generated project prefabs are written to `Assets/AGS/UI/Generated/`. Reusable component prefabs go under `Assets/AGS/UI/Components/`.

## Tools

### Prefab Generation

| Tool | What it does |
|------|-------------|
| `unity_ui_select_recipe` | Pick the right AGS recipe for a feature (login, leaderboard, friends list, etc.) |
| `unity_ui_preflight` | One-shot readiness report: style approval, recipe selection, validation blockers, bridge status |
| `unity_ui_validate` | Validate a recipe spec file without opening Unity |
| `unity_ui_resolve` | Dry-run: resolve recipe → prefab spec without creating any assets |
| `unity_ui_generate` | Generate a project-owned uGUI prefab (bridge mode when editor is open, batch mode when closed) |
| `unity_ui_project_components_generate` | Generate reusable component prefabs under `Assets/AGS/UI/Components/` |
| `unity_ui_patch` | Patch an existing prefab with narrow property changes |
| `unity_ui_inspect_generated_layout` | Inspect generated prefab health (layout, backing class, components, collections) |

### Style

| Tool | What it does |
|------|-------------|
| `unity_ui_style_discover` | Discover uGUI/TMP style assets in the project and optionally approve the style fingerprint |

### AGS Core Kit

| Tool | What it does |
|------|-------------|
| `unity_ui_kit_inspect` | Inspect package-owned AGS kit prefabs against component specs (read-only) |
| `unity_ui_kit_build` | Rebuild all AGS core kit prefabs from scratch (bridge or batch mode) |

### Scene Setup

| Tool | What it does |
|------|-------------|
| `unity_ui_scene_preflight` | Check scene readiness: Canvas, EventSystem, input module compatibility, active panels, blockers |
| `unity_ui_scene_setup` | Set up Canvas/EventSystem, instantiate generated panels, attach MenuManager, and save the scene |

### Editor & Bridge

| Tool | What it does |
|------|-------------|
| `unity_editor_status` | Detect the expected Unity editor, whether it is running, and whether `com.accelbyte.ui-tools` is installed |
| `unity_ui_bridge_health` | Lightweight health check for the editor bridge at `http://127.0.0.1:48758` |
| `unity_trigger_recompile` | Refresh AssetDatabase and trigger C# script recompilation after writing a backing class |
| `unity_repair_package_cache` | Force a clean re-resolve of a stale UPM git-dependency package (hash mismatch or EPERM rename failure) |

### Backing Class & Entry Candidates

| Tool | What it does |
|------|-------------|
| `unity_ui_verify_backing_class` | Validate that `[SerializeField]` fields in a C# backing class match the spec's `cs_bindings` |
| `unity_ui_list_entry_candidates` | Report approved project prefab candidates for generated list or collection rows |

### SDK & Example Components

| Tool | What it does |
|------|-------------|
| `get_accelbyte_unity_how_to` | AccelByte Unity SDK best-practices guide with C# code templates for a feature topic |
| `search_unity_example_components` | Search Bytewars C# source for classes matching a feature; returns ranked metadata and URIs |
| `describe_unity_example_components` | Read the actual C# source files returned by `search_unity_example_components` |
| `unity_install_sdk` | Write AccelByte SDK credentials and config files into a Unity project |

## How the Bridge Works

When Unity is open with `com.accelbyte.ui-tools` loaded, generation and scene setup go through a localhost HTTP bridge:

```
http://127.0.0.1:48758
```

The bridge starts automatically when the editor loads the package. Prefabs generated through it appear in the open project immediately — no editor restart needed.

When Unity is closed, `unity_ui_generate` and `unity_ui_kit_build` fall back to Unity batch mode (`-batchmode -nographics`). The correct Unity executable is matched against `ProjectSettings/ProjectVersion.txt`. For non-standard installs or CI environments, set `UNITY_EDITOR_PATH`:

```powershell
$env:UNITY_EDITOR_PATH = "<PathToUnityHubEditor>\<YourUnityVersion>\Editor\Unity.exe"
```

If the editor is running but the bridge is not reachable (script compilation in progress, package not yet loaded), the MCP returns an actionable error — it will not launch a competing batch instance against an open project.

## Typical Workflow

1. **Check the editor** — `unity_editor_status` confirms Unity is running and the package is installed.
2. **Select a recipe** — `unity_ui_select_recipe` with a natural-language feature description returns a spec stub.
3. **Preflight** — `unity_ui_preflight` validates style approval, recipe fit, entry candidates, and bridge readiness in one call.
4. **Write a C# backing class** (if the recipe requires one) — use `get_accelbyte_unity_how_to` and `search_unity_example_components` / `describe_unity_example_components` for SDK patterns and reference implementations.
5. **Verify the backing class** — `unity_ui_verify_backing_class` confirms `[SerializeField]` fields match the spec.
6. **Trigger recompile** — `unity_trigger_recompile` imports the new file and starts compilation; poll `unity_ui_bridge_health` until `isCompiling` is false.
7. **Generate** — `unity_ui_generate` creates the prefab at `Assets/AGS/UI/Generated/`.
8. **Set up the scene** — `unity_ui_scene_preflight` + `unity_ui_scene_setup` wires the panel into a Canvas with the correct input module and saves the scene.

## Project Structure

```
.
├── server.py                        # MCP server entry point — registers all tools
├── requirements.txt                 # Python dependencies
├── pyproject.toml                   # Package metadata and entry point
├── generate_source_cache.py         # Optional: regenerate Bytewars C# source index
├── data/
│   └── com.accelbyte.ui-tools/      # Unity Editor package (copy into your project's Packages/)
│       ├── Tools/                   # Python UI tools library used by this server
│       ├── Prefabs/                 # Package-owned AGS core kit prefabs
│       └── Specs/                   # Component specs and recipes
└── tests/                           # Python tests
```

## Troubleshooting

**Bridge not reachable (`unity_ui_bridge_health` returns `ok: false`)**
Unity is open but the bridge is down. This usually means scripts are still compiling or the package failed to load. Wait for compilation to finish (check the editor status bar), or reimport `Packages/com.accelbyte.ui-tools` via the Package Manager.

**Editor not detected**
The server matches the Unity version in `ProjectSettings/ProjectVersion.txt` against known install roots. If your editor is in a non-standard location, set `UNITY_EDITOR_PATH` to the full path of `Unity.exe` before starting the server.

**Compile errors block generation**
`unity_ui_generate` refuses to proceed when the editor reports compile errors. Fix the errors shown in Unity's Console, then call `unity_trigger_recompile` and wait until `isCompiling` is false before retrying.

**Stale UPM git-package cache (hash mismatch / EPERM rename)**
A git-URL package dependency (e.g. `com.accelbyte.ui-tools` pinned via `#main` in `<YourUnityProject>/Packages/manifest.json`) can drift out of sync with what Unity has actually resolved, since `#main` is a moving ref rather than a fixed commit. Two symptoms point to the same root cause:

- *Hash mismatch* — `Packages/packages-lock.json` records one hash for `<package-name>`, but `Library/PackageCache/<package-name>@<hash>` on disk has a different hash. Package Manager's hash-keyed lookup then fails to find the package it just fetched.
- *EPERM rename failure* — a resolve or reimport attempt fails with `Failed to rename [...PackageCache\.tmp-<pid>-...\move] to [...PackageCache\<package-name>@<hash>] ... error code [EPERM]`. This happens when the Unity Editor is still open and its `UnityPackageManager` subprocess can't atomically swap in the freshly-cloned revision because the live editor still holds file handles on the package's current contents.

Fix: **fully close the Unity Editor first** (confirm no `Unity.exe` process remains — e.g. `Get-Process Unity` on Windows), then call `unity_repair_package_cache` with `projectPath` and `packageName` (e.g. `com.accelbyte.ui-tools`). It deletes the stale `Library/PackageCache/<package-name>@*` folder(s) and removes the package's entry from `packages-lock.json`, leaving every other dependency untouched. Reopen the Unity editor afterward so Package Manager re-resolves the package fresh from the manifest's git ref, then confirm via **Window → Package Manager** that it appears under **In Project** with no error icon.

The tool refuses to run while a matching Unity editor process is detected, unless you pass `force=true` (only do this if you've independently confirmed it's safe). If you'd rather do it by hand instead of through the MCP tool: close Unity, delete the `Library/PackageCache/<package-name>@*` folder, remove that package's entry from `Packages/packages-lock.json`, then reopen Unity.

## License

ISC