Skip to content

development-setup.md

Latest commit

 

History

History
128 lines (96 loc) · 3.64 KB

development-setup.md

File metadata and controls

128 lines (96 loc) · 3.64 KB
Raw

Development setup

Use a local checkout to work on the bridge, verify package, MCP server, Hub, or community packs. User installation paths live in Manual setup and Agent setup.

Requirements

  • Unity 2022.3 LTS or newer
  • Node.js 18 or newer
  • An MCP client that supports stdio servers

1. Install local Unity packages

Point the target Unity project's Packages/manifest.json at the checkout:

{
  "dependencies": {
    "com.alexeyperov.unity-open-mcp-bridge": "file:../../unity-open-mcp/packages/bridge",
    "com.alexeyperov.unity-open-mcp-verify": "file:../../unity-open-mcp/packages/verify"
  }
}

Adjust the relative path for your layout. A Unity project inside this monorepo can typically use:

{
  "dependencies": {
    "com.alexeyperov.unity-open-mcp-bridge": "file:../../packages/bridge",
    "com.alexeyperov.unity-open-mcp-verify": "file:../../packages/verify"
  }
}

Unity recompiles package source after refresh/focus. Package-local validation requirements are documented in each package's AGENTS.md and README.

2. Build and configure the MCP server

cd mcp-server
npm install
npm run build

Use the local-checkout command in MCP client configuration, preserving the config shape for your client:

{
  "command": "node",
  "args": ["/absolute/path/to/unity-open-mcp/mcp-server/dist/index.js"],
  "env": {
    "UNITY_PROJECT_PATH": "/absolute/path/to/project"
  }
}

Startup-dialog policy and macOS Accessibility requirements are owned by Dialog policy.

3. Optional embedded domains

Domain tools ship inside the bridge. Matching Unity dependencies make package-gated domains compile in; session activation controls whether most groups appear to an MCP client.

Use Extensions for the canonical dependency catalog, manifest examples, and activation table. Community pack authoring has a separate contract in Contributing — extensions.

4. Launch and verify

  1. Open the target Unity project.
  2. Wait for scripts to compile.
  3. Restart the MCP client so it reloads the local command.
  4. Call unity_open_mcp_ping or unity_open_mcp_capabilities.

For bridge, listener, compile, and test-worker recovery, use Contributor troubleshooting.

Community-pack workflow

packages/extensions/ is reserved for separate community domain packs. Shipped domains are embedded in the bridge and do not use standalone extension package entries.

A local community pack can be installed with its own UPM id:

{
  "dependencies": {
    "com.example.my-mcp-ext": "file:../../my-mcp-ext"
  }
}

Follow Contributing — extensions for compile gates, tool registration, tests, and documentation ownership.

Maintainer releases

The npm package is published from mcp-server/; bridge and verify are consumed through git tags. Unity Hub Pro releases independently.

Maintainer versioning and releases is the canonical owner for:

  • version sources and generated targets;
  • sync and CI drift checks;
  • shared-trio and Hub bump commands;
  • tag namespaces and release workflows;
  • GitHub Release ownership of release notes.

The Hub maintainer panel can run build/test, npm dry-run/publish, and the shared version-sync script. It uses the maintainer's existing npm authentication and does not create commits or tags.

Related docs