@akiojin/unity-mcp-server 2.14.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ozan Kasıkçı
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Unity Editor MCP Server
+
+MCP (Model Context Protocol) server for Unity Editor integration. Enables AI assistants like Claude and Cursor to interact directly with Unity Editor for automated game development.
+
+## Features
+
+- **70 comprehensive tools** across 13 categories for Unity Editor automation
+- **GameObject management** - Create, find, modify, delete GameObjects with full hierarchy control
+- **Component system** - Add, remove, modify components with property control
+- **Scene management** - Create, load, save, list scenes with build settings integration
+- **Scene analysis** - Deep inspection, component analysis, and performance metrics
+- **Asset management** - Create and modify prefabs, materials, scripts with full control
+- **UI automation** - Find, click, and interact with UI elements programmatically
+- **Input simulation** - Simulate keyboard, mouse, gamepad, and touch input
+- **Play mode controls** - Start, pause, stop Unity play mode for testing
+- **Project settings** - Read and update Unity project settings safely
+- **Editor operations** - Console logs, screenshots, compilation monitoring
+- **Editor control** - Manage tags, layers, selection, windows, and tools
+
+## Quick Start
+
+### Using npx (Recommended)
+
+```bash
+npx @akiojin/unity-mcp-server@latest
+```
+
+### Global Installation
+
+```bash
+npm install -g @akiojin/unity-mcp-server
+unity-mcp-server
+```
+
+### Local Installation
+
+```bash
+npm install @akiojin/unity-mcp-server
+npx unity-mcp-server
+```
+
+## Unity Setup
+
+1. Install the Unity package from: `https://github.com/akiojin/unity-mcp-server.git?path=UnityMCPServer/Packages/unity-mcp-server`
+2. Open Unity Package Manager → Add package from git URL
+3. The package will automatically start a TCP server on port 6400
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "unity-mcp-server": {
+      "command": "npx",
+      "args": ["@akiojin/unity-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### Alternative (if globally installed)
+
+```json
+{
+  "mcpServers": {
+    "unity-mcp-server": {
+      "command": "unity-mcp-server"
+    }
+  }
+}
+```
+
+## Available Tools (70 Tools)
+
+### System & Core Tools (2 tools)
+- `ping` - Test connection to Unity Editor and verify server status
+- `refresh_assets` - Refresh Unity assets and trigger recompilation
+
+### GameObject Management (5 tools)
+- `create_gameobject` - Create GameObjects with primitives, transforms, tags, and layers
+- `find_gameobject` - Find GameObjects by name, tag, layer with pattern matching
+- `modify_gameobject` - Modify GameObject properties (transform, name, active state, parent)
+- `delete_gameobject` - Delete single or multiple GameObjects with child handling
+- `get_hierarchy` - Get scene hierarchy with components and depth control
+
+### Component System (5 tools)
+- `add_component` - Add Unity components to GameObjects with initial properties
+- `remove_component` - Remove components from GameObjects with safety checks
+- `modify_component` - Modify component properties with nested property support
+- `list_components` - List all components on a GameObject with type information
+- `get_component_types` - Discover available component types with filtering
+
+### Scene Management (5 tools)
+- `create_scene` - Create new scenes with build settings integration
+- `load_scene` - Load scenes in Single or Additive mode
+- `save_scene` - Save current scene with Save As functionality
+- `list_scenes` - List all scenes in project with filtering options
+- `get_scene_info` - Get detailed scene information including GameObject counts
+
+### Scene Analysis (7 tools)
+- `get_gameobject_details` - Deep inspection of GameObjects with component details
+- `analyze_scene_contents` - Comprehensive scene statistics and performance metrics
+- `get_component_values` - Get all properties and values of specific components
+- `find_by_component` - Find GameObjects by component type with scope filtering
+- `get_object_references` - Analyze references between objects and assets
+- `get_animator_state` - Get current Animator state, parameters, and transitions
+- `get_animator_runtime_info` - Get runtime Animator info (Play mode only)
+
+### Asset Management (11 tools)
+- `create_prefab` - Create prefabs from GameObjects or templates
+- `modify_prefab` - Modify existing prefabs with property changes
+- `instantiate_prefab` - Instantiate prefabs in scenes with transform options
+- `open_prefab` - Open prefabs in Unity's prefab mode for editing
+- `exit_prefab_mode` - Exit prefab mode with save/discard options
+- `save_prefab` - Save prefab changes or apply instance overrides
+- `create_material` - Create new materials with shader and properties
+- `modify_material` - Modify material properties and shaders
+- `manage_asset_import_settings` - Manage asset import settings and presets
+- `manage_asset_database` - Asset database operations (find, move, copy, delete)
+- `analyze_asset_dependencies` - Analyze asset dependencies and find unused assets
+
+### Script Management (6 tools)
+- `create_script` - Create new C# scripts with templates (MonoBehaviour, ScriptableObject, etc.)
+- `read_script` - Read script file contents with syntax highlighting
+- `update_script` - Modify existing scripts with validation
+- `delete_script` - Delete script files with dependency checking
+- `list_scripts` - List all scripts in project with filtering and metadata
+- `validate_script` - Validate script syntax and Unity compatibility
+
+### Play Mode Controls (4 tools)
+- `play_game` - Start Unity play mode for testing
+- `pause_game` - Pause or resume Unity play mode
+- `stop_game` - Stop Unity play mode and return to edit mode
+- `get_editor_state` - Get current editor state and compilation status
+
+### UI Automation (5 tools)
+- `find_ui_elements` - Locate UI elements by type, tag, or name
+- `click_ui_element` - Simulate clicking on UI elements (buttons, toggles)
+- `get_ui_element_state` - Get UI element properties and interaction state
+- `set_ui_element_value` - Set values for input fields, sliders, dropdowns
+- `simulate_ui_input` - Execute complex UI interaction sequences
+
+### Input System Simulation (5 tools)
+- `simulate_keyboard` - Simulate keyboard input with key combos and text typing
+- `simulate_mouse` - Simulate mouse movement, clicks, drags, and scrolling
+- `simulate_gamepad` - Simulate gamepad buttons, sticks, triggers, and d-pad
+- `simulate_touch` - Simulate touch gestures (tap, swipe, pinch, multi-touch)
+- `get_current_input_state` - Get current state of all input devices
+
+### Editor Operations (5 tools)
+- `execute_menu_item` - Execute Unity menu items programmatically
+- `clear_console` - Clear Unity console logs with filtering options
+- `read_console` - Read console logs with advanced filtering and search
+- `capture_screenshot` - Take screenshots of Game View or Scene View
+- `analyze_screenshot` - Analyze screenshot content with image analysis
+
+### Editor Control & Automation (6 tools)
+- `manage_tags` - Manage Unity project tags (add, remove, list)
+- `manage_layers` - Manage Unity project layers with index conversion
+- `manage_selection` - Manage Editor selection (get, set, clear)
+- `manage_windows` - Manage Editor windows (list, focus, get state)
+- `manage_tools` - Manage Editor tools and plugins
+- `get_compilation_state` - Get current compilation state and errors
+
+### Project Settings Management (2 tools)
+- `get_project_settings` - Read Unity project settings with granular control
+  - Player, Graphics, Quality, Physics, Audio, Time settings
+  - Build settings, Tags and layers configuration
+- `update_project_settings` - Safely update project settings
+  - Requires explicit confirmation for safety
+  - Supports partial updates to specific categories
+
+## Requirements
+
+- **Unity**: 2020.3 LTS or newer (Unity 6 supported)
+- **Node.js**: 18.0.0 or newer
+- **MCP Client**: Claude Desktop, Cursor, or compatible client
+
+## Troubleshooting
+
+### Connection Issues
+1. Ensure Unity Editor is running with the Unity package installed
+2. Check Unity console for connection messages
+3. Verify port 6400 is not blocked by firewall
+
+### Installation Issues
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall
+npm uninstall -g @akiojin/unity-mcp-server
+npm install -g @akiojin/unity-mcp-server
+```
+
+## Repository
+
+Full source code and documentation: https://github.com/akiojin/unity-mcp-server
+
+## License
+
+MIT License - see LICENSE file for details.

package/bin/unity-mcp-server

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/core/server.js';

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@akiojin/unity-mcp-server",
+  "version": "2.14.14",
+  "description": "MCP server and Unity Editor bridge — enables AI assistants to control Unity for AI-assisted workflows",
+  "type": "module",
+  "main": "src/core/server.js",
+  "bin": {
+    "unity-mcp-server": "./bin/unity-mcp-server"
+  },
+  "scripts": {
+    "start": "node src/core/server.js",
+    "dev": "node --watch src/core/server.js",
+    "build:index": "node src/tools/buildCodeIndex.js",
+    "test": "node --test tests/unit/**/*.test.js tests/integration/*.test.js",
+    "test:unit": "NODE_ENV=test node --test tests/unit/**/*.test.js",
+    "test:integration": "NODE_ENV=test node --test tests/integration/*.test.js",
+    "test:e2e": "NODE_ENV=test node --test tests/e2e/*.test.js",
+    "test:coverage": "c8 --reporter=lcov --reporter=text --reporter=html node --test tests/unit/**/*.test.js tests/integration/*.test.js",
+    "test:coverage:full": "c8 --reporter=lcov --reporter=text --reporter=html node --test tests/**/*.test.js",
+    "test:watch": "node --watch --test tests/unit/**/*.test.js",
+    "test:watch:all": "node --watch --test tests/**/*.test.js",
+    "test:performance": "node --test tests/performance/*.test.js",
+    "test:ci": "c8 --reporter=lcov --check-coverage=false node --test tests/unit/core/config.test.js tests/unit/handlers/PingToolHandler.test.js tests/unit/handlers/CreateGameObjectToolHandler.test.js",
+    "test:ci:all": "c8 --reporter=lcov node --test tests/unit/**/*.test.js",
+    "test:verbose": "VERBOSE_TEST=true node --test tests/**/*.test.js",
+    "prepublishOnly": "npm run test:ci",
+    "postinstall": "chmod +x bin/unity-mcp-server || true"
+  },
+  "keywords": [
+    "mcp",
+    "unity",
+    "unity-editor",
+    "model-context-protocol",
+    "ai",
+    "automation",
+    "claude",
+    "cursor",
+    "gamedev",
+    "unity3d"
+  ],
+  "author": "Akio Jinsenji <akio-jinsenji@cloud-creative-studios.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.1",
+    "better-sqlite3": "^9.4.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akiojin/unity-mcp-server.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/akiojin/unity-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/akiojin/unity-mcp-server/issues"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "preferGlobal": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "nodemon": "^3.1.7"
+  }
+}

package/src/core/codeIndex.js

@@ -0,0 +1,163 @@
+import fs from 'fs';
+import path from 'path';
+import { ProjectInfoProvider } from './projectInfo.js';
+
+export class CodeIndex {
+  constructor(unityConnection) {
+    this.unityConnection = unityConnection;
+    this.projectInfo = new ProjectInfoProvider(unityConnection);
+    this.db = null;
+    this.dbPath = null;
+    this.disabled = false; // set true if better-sqlite3 is unavailable
+    this._Database = null;
+  }
+
+  async _ensureDriver() {
+    if (this.disabled) return false;
+    if (this._Database) return true;
+    try {
+      // Dynamic import to avoid hard failure when native binding is missing
+      const mod = await import('better-sqlite3');
+      this._Database = mod.default || mod;
+      return true;
+    } catch (e) {
+      // Mark as disabled and operate in fallback (index unavailable)
+      this.disabled = true;
+      return false;
+    }
+  }
+
+  async open() {
+    if (this.db) return this.db;
+    const ok = await this._ensureDriver();
+    if (!ok) return null; // index disabled
+    const info = await this.projectInfo.get();
+    const dir = info.codeIndexRoot;
+    fs.mkdirSync(dir, { recursive: true });
+    const dbPath = path.join(dir, 'code-index.db');
+    this.dbPath = dbPath;
+    this.db = new this._Database(dbPath);
+    this._initSchema();
+    return this.db;
+  }
+
+  _initSchema() {
+    if (!this.db) return;
+    const db = this.db;
+    db.exec(`
+      PRAGMA journal_mode=WAL;
+      CREATE TABLE IF NOT EXISTS meta (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      );
+      CREATE TABLE IF NOT EXISTS files (
+        path TEXT PRIMARY KEY,
+        sig TEXT,
+        updatedAt TEXT
+      );
+      CREATE TABLE IF NOT EXISTS symbols (
+        path TEXT NOT NULL,
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        container TEXT,
+        namespace TEXT,
+        line INTEGER,
+        column INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+      CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
+      CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path);
+    `);
+  }
+
+  async isReady() {
+    const db = await this.open();
+    if (!db) return false;
+    const row = db.prepare('SELECT COUNT(*) AS c FROM symbols').get();
+    return (row?.c || 0) > 0;
+  }
+
+  async clearAndLoad(symbols) {
+    const db = await this.open();
+    if (!db) throw new Error('CodeIndex is unavailable (better-sqlite3 not installed)');
+    const insert = db.prepare('INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)');
+    const tx = db.transaction((rows) => {
+      db.exec('DELETE FROM symbols');
+      db.exec('DELETE FROM files');
+      for (const r of rows) {
+        insert.run(r.path, r.name, r.kind, r.container || null, r.ns || r.namespace || null, r.line || null, r.column || null);
+      }
+      db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)').run('lastIndexedAt', new Date().toISOString());
+    });
+    tx(symbols || []);
+    return { total: symbols?.length || 0 };
+  }
+
+  // Incremental APIs
+  async getFiles() {
+    const db = await this.open();
+    if (!db) return new Map();
+    const rows = db.prepare('SELECT path, sig FROM files').all();
+    const map = new Map();
+    for (const r of rows) map.set(String(r.path), String(r.sig || ''));
+    return map;
+  }
+
+  async upsertFile(pathStr, sig) {
+    const db = await this.open();
+    if (!db) return;
+    db.prepare('REPLACE INTO files(path,sig,updatedAt) VALUES (?,?,?)').run(pathStr, sig || '', new Date().toISOString());
+  }
+
+  async removeFile(pathStr) {
+    const db = await this.open();
+    if (!db) return;
+    const tx = db.transaction((p) => {
+      db.prepare('DELETE FROM symbols WHERE path = ?').run(p);
+      db.prepare('DELETE FROM files WHERE path = ?').run(p);
+    });
+    tx(pathStr);
+  }
+
+  async replaceSymbolsForPath(pathStr, rows) {
+    const db = await this.open();
+    if (!db) return;
+    const tx = db.transaction((p, list) => {
+      db.prepare('DELETE FROM symbols WHERE path = ?').run(p);
+      const insert = db.prepare('INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)');
+      for (const r of list) insert.run(p, r.name, r.kind, r.container || null, r.ns || r.namespace || null, r.line || null, r.column || null);
+      db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)').run('lastIndexedAt', new Date().toISOString());
+    });
+    tx(pathStr, rows || []);
+  }
+
+  async querySymbols({ name, kind, scope = 'all', exact = false }) {
+    const db = await this.open();
+    if (!db) return [];
+    let sql = 'SELECT path,name,kind,container,namespace,line,column FROM symbols WHERE 1=1';
+    const params = {};
+    if (name) {
+      if (exact) { sql += ' AND name = @name'; params.name = name; }
+      else { sql += ' AND name LIKE @name'; params.name = `%${name}%`; }
+    }
+    if (kind) { sql += ' AND kind = @kind'; params.kind = kind; }
+    const rows = db.prepare(sql).all(params);
+    // Apply path-based scope filter in JS (simpler than CASE in SQL)
+    const filtered = rows.filter(r => {
+      const p = String(r.path || '').replace(/\\\\/g, '/');
+      if (scope === 'assets') return p.startsWith('Assets/');
+      if (scope === 'packages') return p.startsWith('Packages/') || p.includes('Library/PackageCache/');
+      if (scope === 'embedded') return p.startsWith('Packages/');
+      return true;
+    });
+    return filtered.map(r => ({ path: r.path, name: r.name, kind: r.kind, container: r.container, ns: r.namespace, line: r.line, column: r.column }));
+  }
+
+  async getStats() {
+    const db = await this.open();
+    if (!db) return { total: 0, lastIndexedAt: null };
+    const total = db.prepare('SELECT COUNT(*) AS c FROM symbols').get().c || 0;
+    const last = db.prepare("SELECT value AS v FROM meta WHERE key = 'lastIndexedAt'").get()?.v || null;
+    return { total, lastIndexedAt: last };
+  }
+}

package/src/core/codeIndexDb.js

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { logger } from './config.js';
+
+let dbCache = new Map();
+
+function getDbPath(projectRoot) {
+  const dir = path.join(projectRoot, 'Library', 'UnityMCP', 'CodeIndex');
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, 'index.db');
+}
+
+export function openDb(projectRoot) {
+  const key = path.resolve(projectRoot);
+  if (dbCache.has(key)) return dbCache.get(key);
+  const dbPath = getDbPath(projectRoot);
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS files (
+      path TEXT PRIMARY KEY,
+      mtime INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS symbols (
+      path TEXT NOT NULL,
+      name TEXT NOT NULL,
+      kind TEXT,
+      container TEXT,
+      ns TEXT,
+      line INTEGER,
+      column INTEGER,
+      FOREIGN KEY(path) REFERENCES files(path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+    CREATE TABLE IF NOT EXISTS refs (
+      path TEXT NOT NULL,
+      name TEXT NOT NULL,
+      line INTEGER,
+      snippet TEXT,
+      FOREIGN KEY(path) REFERENCES files(path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_refs_name ON refs(name);
+  `);
+  dbCache.set(key, db);
+  return db;
+}
+
+export function upsertFile(db, filePath, mtimeMs) {
+  const stmt = db.prepare('INSERT INTO files(path, mtime) VALUES(?, ?) ON CONFLICT(path) DO UPDATE SET mtime=excluded.mtime');
+  stmt.run(filePath, Math.floor(mtimeMs));
+}
+
+export function replaceSymbols(db, filePath, symbols) {
+  const del = db.prepare('DELETE FROM symbols WHERE path = ?');
+  del.run(filePath);
+  const ins = db.prepare('INSERT INTO symbols(path, name, kind, container, ns, line, column) VALUES(?,?,?,?,?,?,?)');
+  const tr = db.transaction((rows) => {
+    for (const s of rows) ins.run(filePath, s.name || '', s.kind || '', s.container || null, s.ns || null, s.line || 0, s.column || 0);
+  });
+  tr(symbols || []);
+}
+
+export function replaceReferences(db, filePath, refs) {
+  const del = db.prepare('DELETE FROM refs WHERE path = ?');
+  del.run(filePath);
+  const ins = db.prepare('INSERT INTO refs(path, name, line, snippet) VALUES(?,?,?,?)');
+  const tr = db.transaction((rows) => {
+    for (const r of rows) ins.run(filePath, r.name || '', r.line || 0, r.snippet || null);
+  });
+  tr(refs || []);
+}
+
+export function querySymbolsByName(db, name, kind = null) {
+  if (kind) {
+    return db.prepare('SELECT path,name,kind,container,ns,line,column FROM symbols WHERE name = ? AND kind = ? LIMIT 500').all(name, kind);
+  }
+  return db.prepare('SELECT path,name,kind,container,ns,line,column FROM symbols WHERE name = ? LIMIT 500').all(name);
+}
+
+export function queryRefsByName(db, name) {
+  return db.prepare('SELECT path,name,line,snippet FROM refs WHERE name = ? LIMIT 1000').all(name);
+}
+
+export function isFresh(projectRoot, filePath, db) {
+  try {
+    const row = db.prepare('SELECT mtime FROM files WHERE path = ?').get(filePath);
+    if (!row) return false;
+    const abs = path.join(projectRoot, filePath);
+    const st = fs.statSync(abs);
+    return Math.floor(st.mtimeMs) === row.mtime;
+  } catch {
+    return false;
+  }
+}
+