@akiojin/unity-mcp-server 2.14.14

package/src/handlers/script/BuildCodeIndexToolHandler.js

@@ -0,0 +1,163 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { CodeIndex } from '../../core/codeIndex.js';
+import fs from 'fs';
+import path from 'path';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { LspRpcClient } from '../../lsp/LspRpcClient.js';
+import { logger } from '../../core/config.js';
+
+export class BuildCodeIndexToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'build_code_index',
+      'Build a persistent SQLite symbol index by scanning document symbols via the C# LSP. Stores DB under Library/UnityMCP/CodeIndex/code-index.db.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+    this.index = new CodeIndex(unityConnection);
+    this.projectInfo = new ProjectInfoProvider(unityConnection);
+    this.lsp = null; // lazy init with projectRoot
+  }
+
+  async execute(params = {}) {
+    try {
+      const info = await this.projectInfo.get();
+      const roots = [
+        path.resolve(info.projectRoot, 'Assets'),
+        path.resolve(info.projectRoot, 'Packages'),
+        path.resolve(info.projectRoot, 'Library/PackageCache'),
+      ];
+      const files = [];
+      const seen = new Set();
+      for (const r of roots) this.walkCs(r, files, seen);
+
+      if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
+      const lsp = this.lsp;
+
+      // Incremental detection based on size-mtime signature
+      const makeSig = (abs) => {
+        try { const st = fs.statSync(abs); return `${st.size}-${Math.floor(st.mtimeMs)}`; } catch { return '0-0'; }
+      };
+      const wanted = new Map(files.map(abs => [this.toRel(abs, info.projectRoot), makeSig(abs)]));
+      const current = await this.index.getFiles();
+      const changed = [];
+      const removed = [];
+      for (const [rel, sig] of wanted) {
+        if (current.get(rel) !== sig) changed.push(rel);
+      }
+      for (const [rel] of current) if (!wanted.has(rel)) removed.push(rel);
+      const toRows = (uri, symbols) => {
+        const rel = this.toRel(uri.replace('file://', ''), info.projectRoot);
+        const rows = [];
+        const visit = (s, container) => {
+          const kind = this.kindFromLsp(s.kind);
+          const name = s.name || '';
+          const start = s.range?.start || s.selectionRange?.start || {};
+          rows.push({ path: rel, name, kind, container: container || null, ns: null, line: (start.line ?? 0) + 1, column: (start.character ?? 0) + 1 });
+          if (Array.isArray(s.children)) for (const c of s.children) visit(c, name || container);
+        };
+        if (Array.isArray(symbols)) for (const s of symbols) visit(s, null);
+        return rows;
+      };
+
+      // Remove vanished files
+      for (const rel of removed) await this.index.removeFile(rel);
+
+      // Update changed files
+      const absList = changed.map(rel => path.resolve(info.projectRoot, rel));
+      const concurrency = Math.max(1, Math.min(64, Number(params?.concurrency ?? 8)));
+      const reportEvery = Math.max(1, Number(params?.reportEvery ?? 100));
+      const startAt = Date.now();
+      let i = 0; let updated = 0; let processed = 0;
+
+      // LSP request with small retry/backoff
+      const requestWithRetry = async (uri, maxRetries = Math.max(0, Math.min(5, Number(params?.retry ?? 2)))) => {
+        let lastErr = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+          try {
+            const res = await lsp.request('textDocument/documentSymbol', { textDocument: { uri } });
+            return res?.result ?? res;
+          } catch (err) {
+            lastErr = err;
+            await new Promise(r => setTimeout(r, 200 * (attempt + 1)));
+          }
+        }
+        throw lastErr || new Error('documentSymbol failed');
+      };
+      const worker = async () => {
+        while (true) {
+          const idx = i++;
+          if (idx >= absList.length) break;
+          const abs = absList[idx];
+          try {
+            const uri = 'file://' + abs.replace(/\\/g, '/');
+            const docSymbols = await requestWithRetry(uri, 2);
+            const rows = toRows(uri, docSymbols);
+            const rel = this.toRel(abs, info.projectRoot);
+            await this.index.replaceSymbolsForPath(rel, rows);
+            await this.index.upsertFile(rel, wanted.get(rel));
+            updated += 1;
+          } catch {}
+          finally {
+            processed += 1;
+            if (processed % reportEvery === 0 || processed === absList.length) {
+              const elapsed = Math.max(1, Date.now() - startAt);
+              const rate = (processed * 1000 / elapsed).toFixed(1);
+              logger.info(`[index] progress ${processed}/${absList.length} (removed:${removed.length}) rate:${rate} f/s`);
+            }
+          }
+        }
+      };
+      const workers = Array.from({ length: Math.min(concurrency, absList.length) }, () => worker());
+      await Promise.all(workers);
+
+      const stats = await this.index.getStats();
+      return { success: true, updatedFiles: updated, removedFiles: removed.length, totalIndexedSymbols: stats.total, lastIndexedAt: stats.lastIndexedAt };
+    } catch (e) {
+      return {
+        success: false,
+        error: 'build_index_failed',
+        message: e.message,
+        hint: 'C# LSP not ready. Ensure manifest/auto-download and workspace paths are valid.'
+      };
+    }
+  }
+
+  walkCs(root, files, seen) {
+    try {
+      if (!fs.existsSync(root)) return;
+      const st = fs.statSync(root);
+      if (st.isFile()) {
+        if (root.endsWith('.cs') && !seen.has(root)) { files.push(root); seen.add(root); }
+        return;
+      }
+      const entries = fs.readdirSync(root, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.name === 'obj' || e.name === 'bin' || e.name.startsWith('.')) continue;
+        this.walkCs(path.join(root, e.name), files, seen);
+      }
+    } catch {}
+  }
+
+  toRel(full, projectRoot) {
+    const normFull = String(full).replace(/\\/g, '/');
+    const normRoot = String(projectRoot).replace(/\\/g, '/').replace(/\/$/, '');
+    return normFull.startsWith(normRoot) ? normFull.substring(normRoot.length + 1) : normFull;
+  }
+
+  kindFromLsp(k) {
+    switch (k) {
+      case 5: return 'class';
+      case 23: return 'struct';
+      case 11: return 'interface';
+      case 10: return 'enum';
+      case 6: return 'method';
+      case 7: return 'property';
+      case 8: return 'field';
+      case 3: return 'namespace';    }
+  }
+}

package/src/handlers/script/ScriptCreateClassFileToolHandler.js

@@ -0,0 +1,60 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import fs from 'fs';
+import path from 'path';
+
+// script_*系に名称統一: 新規C#クラスを新規ファイルで生成
+export class ScriptCreateClassFileToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'script_create_class_file',
+      'Create a new C# class file. Required: path under Assets/ or Packages/ (".cs" appended if missing), className. Optional: namespace, baseType (adds using UnityEngine if MonoBehaviour), usings (CSV), partial. Roslyn preflight (no Unity comms). Responses summarized for LLMs (errors≤30, message≤200 chars, preview≤1000 chars).',
+      {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Project-relative C# file path (e.g., Assets/Scripts/MyClass.cs)' },
+          className: { type: 'string', description: 'Class name' },
+          namespace: { type: 'string', description: 'Optional namespace' },
+          baseType: { type: 'string', description: 'Optional base type (e.g., MonoBehaviour)' },
+          usings: { type: 'string', description: 'Comma-separated using directives (e.g., System,Newtonsoft.Json)' },
+          partial: { type: 'boolean', description: 'Create as partial class (default: false)' },
+          apply: { type: 'boolean', description: 'Apply immediately (default: false)' }
+        },
+        required: ['path','className']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  async execute(params) {
+    const { path: rel, className, namespace: ns, baseType, usings, partial = false, apply = false } = params;
+    const relative = String(rel).replace(/\\\\/g, '/').endsWith('.cs') ? String(rel).replace(/\\\\/g, '/') : String(rel).replace(/\\\\/g, '/') + '.cs';
+    const code = this._buildSource({ className: String(className), ns: ns ? String(ns) : null, baseType: baseType ? String(baseType) : null, usings: usings ? String(usings) : null, partial: !!partial });
+    if (!apply) {
+      return { success: true, applied: false, preview: code.slice(0, 1000), previewTruncated: code.length > 1000, relative: relative };
+    }
+    const full = this._resolveFullPath(relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, code, 'utf8');
+    return { success: true, applied: true, relative };
+  }
+
+  _resolveFullPath(relative) {
+    // Project root resolution via ProjectInfoProvider would be heavier; reconstruct by walking up
+    const cwd = process.cwd();
+    return path.resolve(cwd, relative);
+  }
+
+  _buildSource({ className, ns, baseType, usings, partial }) {
+    const useList = [];
+    if (usings) useList.push(...usings.split(',').map(s => s.trim()).filter(Boolean));
+    if (baseType === 'MonoBehaviour' && !useList.includes('UnityEngine')) useList.push('UnityEngine');
+    const header = useList.length ? useList.map(u => `using ${u};`).join('\n') + '\n\n' : '';
+    const partialKw = partial ? ' partial' : '';
+    const baseClause = baseType ? ` : ${baseType}` : '';
+    const classBlock = `public${partialKw} class ${className}${baseClause}\n{\n}\n`;
+    if (ns) {
+      return `${header}namespace ${ns}\n{\n${classBlock}\n}`;
+    }
+    return `${header}${classBlock}`;
+  }
+}

package/src/handlers/script/ScriptEditStructuredToolHandler.js

@@ -0,0 +1,173 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { LspRpcClient } from '../../lsp/LspRpcClient.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+
+export class ScriptEditStructuredToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_edit_structured',
+            'PRIORITY: Use this for ALL code changes. Perform structured edits (insert_before/insert_after/replace_body) on a known symbol. Required params: path (file under Assets/ or Packages/), symbolName (prefer container path e.g. MyType/Nested/Foo). Guidance: (1) Locate targets with script_symbols_get first, (2) insert_* must target a class/namespace (never a method), (3) replace_body must be a self-contained body including braces, (4) preview is for diagnostics only — apply proceeds even if diagnostics exist; errors are returned. LLM summary limits: errors≤30 (message≤200 chars, file≤260), large text (preview/diff/text/content)≤1000 chars with Truncated flag.',
+            {
+                type: 'object',
+                properties: {
+                    operation: {
+                        type: 'string',
+                        enum: ['insert_before', 'insert_after', 'replace_body'],
+                        description: 'Edit type: insert_before, insert_after, or replace_body.'
+                    },
+                    path: {
+                        type: 'string',
+                        description: 'Project-relative C# path starting with Assets/ or Packages/ (e.g., Packages/unity-mcp-server/Editor/Foo.cs). Do NOT prefix repository folders like UnityMCPServer/….'
+                    },
+                    symbolName: {
+                        type: 'string',
+                        description: 'Target symbol name (e.g., class/method/field name).'
+                    },
+                    kind: {
+                        type: 'string',
+                        description: 'Symbol kind (e.g., class, method, field, property). Optional but improves precision.'
+                    },
+                    newText: {
+                        type: 'string',
+                        description: 'Text to insert or use as replacement body.'
+                    },
+                    preview: {
+                        type: 'boolean',
+                        description: 'If true, returns a preview without writing files. Default=false to reduce large diff payloads.'
+                    }
+                },
+                required: ['operation', 'path', 'symbolName']
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+        this.lsp = null;
+    }
+
+    validate(params) {
+        super.validate(params);
+
+        const { operation, path, symbolName, kind } = params;
+
+        const validOperations = ['insert_before', 'insert_after', 'replace_body'];
+        if (!validOperations.includes(operation)) {
+            throw new Error(`Invalid operation: ${operation}`);
+        }
+
+        if (!path || path.trim() === '') {
+            throw new Error('path cannot be empty');
+        }
+
+        if (!symbolName || symbolName.trim() === '') {
+            throw new Error('symbolName cannot be empty');
+        }
+
+        // Safety guard: forbid inserting members into a method scope
+        if ((operation === 'insert_after' || operation === 'insert_before') && (kind || '').toLowerCase() === 'method') {
+            throw new Error('Insert operations must target class/namespace, not method scope. Use kind:"class" and insert at class level.');
+        }
+    }
+
+    async execute(params) {
+        // Normalize to project-relative path
+        const raw = String(params.path).replace(/\\\\/g, '/');
+        const ai = raw.indexOf('Assets/');
+        const pi = raw.indexOf('Packages/');
+        const idx = (ai >= 0 && pi >= 0) ? Math.min(ai, pi) : (ai >= 0 ? ai : pi);
+        const relative = idx >= 0 ? raw.substring(idx) : raw;
+
+        const operation = String(params.operation);
+        const kind = (params.kind || '').toLowerCase();
+        const symbolName = String(params.symbolName);
+        const preview = params?.preview === true;
+        const body = String(params.newText || '');
+
+        // Map operations to LSP extensions
+        const info = await this.projectInfo.get();
+        if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
+
+        if (operation === 'replace_body') {
+            const resp = await this.lsp.request('mcp/replaceSymbolBody', {
+                relative,
+                namePath: symbolName,
+                body,
+                apply: !preview
+            });
+            return this._summarizeResult(resp?.result ?? resp, { preview });
+        }
+        if (operation === 'insert_before' || operation === 'insert_after') {
+            const method = operation === 'insert_before' ? 'mcp/insertBeforeSymbol' : 'mcp/insertAfterSymbol';
+            const resp = await this.lsp.request(method, {
+                relative,
+                namePath: symbolName,
+                text: body,
+                apply: !preview
+            });
+            return this._summarizeResult(resp?.result ?? resp, { preview });
+        }
+
+        return { error: `Unsupported operation: ${operation}` };
+    }
+
+    /**
+     * Summarize/trim responses to avoid huge token usage.
+     * - Caps error items and message lengths
+     * - Trims large text fields (e.g., preview/diff) to a short excerpt
+     */
+    _summarizeResult(res, { preview }) {
+        if (!res || typeof res !== 'object') return res;
+
+        const MAX_ERRORS = 30;
+        const MAX_MSG_LEN = 200;
+        const MAX_TEXT_LEN = 1000; // generic cap for any preview-like text
+
+        const out = {};
+        // Preserve common flags if present
+        if ('id' in res) out.id = res.id;
+        if ('success' in res) out.success = !!res.success;
+        if ('applied' in res) out.applied = !!res.applied;
+
+        // Errors trimming
+        if (Array.isArray(res.errors)) {
+            const trimmed = res.errors.slice(0, MAX_ERRORS).map(e => {
+                const obj = {};
+                if (e && typeof e === 'object') {
+                    if ('id' in e) obj.id = e.id;
+                    if ('message' in e) obj.message = this._trimString(String(e.message), MAX_MSG_LEN);
+                    if ('file' in e) obj.file = this._trimString(String(e.file), 260);
+                    if ('line' in e) obj.line = e.line;
+                    if ('column' in e) obj.column = e.column;
+                } else {
+                    obj.message = this._trimString(String(e), MAX_MSG_LEN);
+                }
+                return obj;
+            });
+            out.errorCount = trimmed.length; // summarized count (<= MAX_ERRORS)
+            out.totalErrors = res.errors.length; // raw count for reference
+            out.errors = trimmed;
+        }
+
+        // Propagate workspace info if present (which .sln/.csproj is open)
+        // workspace情報は返さない（厳格: .sln必須のため）
+
+        // Generic handling for any large text properties commonly returned by tools
+        for (const key of ['preview', 'diff', 'text', 'content']) {
+            if (typeof res[key] === 'string' && res[key].length > 0) {
+                out[key] = this._trimString(res[key], MAX_TEXT_LEN);
+                if (res[key].length > MAX_TEXT_LEN) out[`${key}Truncated`] = true;
+            }
+        }
+
+        // Echo minimal identifiers to aid clients
+        for (const key of ['operation', 'path', 'relative', 'symbolName']) {
+            if (res[key] !== undefined) out[key] = res[key];
+        }
+
+        return Object.keys(out).length ? out : res;
+    }
+
+    _trimString(s, max) {
+        if (typeof s !== 'string') return s;
+        return s.length > max ? (s.slice(0, max) + '…') : s;
+    }
+}

package/src/handlers/script/ScriptIndexStatusToolHandler.js

@@ -0,0 +1,61 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+
+export class ScriptIndexStatusToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_index_status',
+            'Report code index status and readiness for symbol/search operations. BEST PRACTICES: Check before heavy symbol operations. Shows total files indexed and coverage percentage. If coverage is low, some symbol operations may be incomplete. Index is automatically built on first use. No parameters needed - lightweight status check.',
+            {
+                type: 'object',
+                properties: {},
+                required: []
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+    }
+
+  async execute(params) {
+        // まず永続インデックスの有無を確認。未構築なら明示エラーで build_code_index を促す。
+        const { CodeIndex } = await import('../../core/codeIndex.js');
+        const idx = new CodeIndex(this.unityConnection);
+        const ready = await idx.isReady();
+        if (!ready) {
+            return { success: false, error: 'index_not_built', message: 'Code index is not built. Please run UnityMCP.build_code_index first.' };
+        }
+
+        // 構築済みなら .cs 総数をローカル走査で取得（軽量）
+        const info = await this.projectInfo.get();
+        const fs = await import('fs');
+        const path = await import('path');
+        const roots = [
+            path.default.resolve(info.projectRoot, 'Assets'),
+            path.default.resolve(info.projectRoot, 'Packages'),
+            path.default.resolve(info.projectRoot, 'Library/PackageCache'),
+        ];
+        let total = 0; const breakdown = { assets: 0, packages: 0, packageCache: 0, other: 0 };
+        const walk = (dir) => {
+            try {
+                if (!fs.default.existsSync(dir)) return;
+                const st = fs.default.statSync(dir);
+                if (st.isFile()) {
+                    if (dir.endsWith('.cs')) {
+                        total++;
+                        const rel = dir.replace(/\\\\/g, '/').replace(info.projectRoot.replace(/\\\\/g,'/'), '').replace(/^\//,'');
+                        if (rel.startsWith('Assets/')) breakdown.assets++; else if (rel.startsWith('Packages/')) breakdown.packages++; else if (rel.includes('Library/PackageCache/')) breakdown.packageCache++; else breakdown.other++;
+                    }
+                    return;
+                }
+                for (const e of fs.default.readdirSync(dir)) {
+                    if (e === 'obj' || e === 'bin' || e.startsWith('.')) continue;
+                    walk(path.default.join(dir, e));
+                }
+            } catch {}
+        };
+        for (const r of roots) walk(r);
+        const stats = await idx.getStats();
+        const coverage = total > 0 ? Math.min(1, stats.total / total) : 0;
+        return { success: true, totalFiles: total, indexedFiles: stats.total, coverage, breakdown, index: { ready: true, rows: stats.total, lastIndexedAt: stats.lastIndexedAt } };
+  }
+}

package/src/handlers/script/ScriptPackagesListToolHandler.js

@@ -0,0 +1,103 @@
+import fs from 'fs';
+import path from 'path';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { logger } from '../../core/config.js';
+
+export class ScriptPackagesListToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_packages_list',
+            'List Unity packages in the project (optionally include built‑in). BEST PRACTICES: Use to discover available packages and their paths. Set includeBuiltIn=false to see only user packages. Returns package IDs, versions, and resolved paths. Embedded packages can be edited directly. Essential for understanding project dependencies.',
+            {
+                type: 'object',
+                properties: {
+                    includeBuiltIn: {
+                        type: 'boolean',
+                        description: 'If true, includes built‑in packages in results (default: false).'
+                    }
+                },
+                required: []
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+    }
+
+    async execute(params) {
+        const { includeBuiltIn = false } = params;
+        const info = await this.projectInfo.get();
+
+        // Prefer packages-lock.json for authoritative list (includes builtin/embedded/registry)
+        const lockPath = path.join(info.projectRoot, 'Packages', 'packages-lock.json');
+        const manifestPath = path.join(info.projectRoot, 'Packages', 'manifest.json');
+        let results = [];
+        try {
+            if (fs.existsSync(lockPath)) {
+                const json = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+                const deps = json?.dependencies || {};
+                for (const [name, meta] of Object.entries(deps)) {
+                    const source = String(meta.source || '').toLowerCase();
+                    if (!includeBuiltIn && source === 'builtin') continue;
+                    const version = String(meta.version || '');
+                    let resolvedPath = null;
+                    let isEmbedded = source === 'embedded';
+                    if (isEmbedded) {
+                        // For embedded, manifest specifies file:folder
+                        try {
+                            const man = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+                            const spec = man?.dependencies?.[name];
+                            if (typeof spec === 'string' && spec.startsWith('file:')) {
+                                const folder = spec.substring('file:'.length);
+                                resolvedPath = path.join(info.projectRoot, 'Packages', folder).replace(/\\/g, '/');
+                            }
+                        } catch {}
+                    }
+                    results.push({
+                        packageId: `${name}@${version}`,
+                        name,
+                        displayName: name,
+                        version,
+                        source,
+                        isEmbedded,
+                        resolvedPath
+                    });
+                }
+            } else if (fs.existsSync(manifestPath)) {
+                const man = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+                const deps = man?.dependencies || {};
+                for (const [name, spec] of Object.entries(deps)) {
+                    let source = 'registry';
+                    let version = String(spec);
+                    let resolvedPath = null;
+                    let isEmbedded = false;
+                    if (version.startsWith('file:')) {
+                        source = 'embedded';
+                        isEmbedded = true;
+                        const folder = version.substring('file:'.length);
+                        resolvedPath = path.join(info.projectRoot, 'Packages', folder).replace(/\\/g, '/');
+                    }
+                    if (!includeBuiltIn && source === 'builtin') continue;
+                    results.push({
+                        packageId: `${name}@${version}`,
+                        name,
+                        displayName: name,
+                        version,
+                        source,
+                        isEmbedded,
+                        resolvedPath
+                    });
+                }
+            } else {
+                return { success: true, packages: [], totalCount: 0 };
+            }
+        } catch (e) {
+            logger.error(`[script_packages_list] local parse failed: ${e.message}`);
+            return { error: e.message };
+        }
+
+        // Sort by name
+        results.sort((a, b) => a.name.localeCompare(b.name));
+        return { success: true, packages: results, totalCount: results.length };
+    }
+}

package/src/handlers/script/ScriptReadToolHandler.js

@@ -0,0 +1,106 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { logger } from '../../core/config.js';
+
+export class ScriptReadToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_read',
+            'Read a C# file with optional line range and payload limits. Files must be under Assets/ or Packages/ and have .cs extension. PRIORITY: Read minimally — locate the target with script_symbols_get and read only the signature area (~30–40 lines). For large files, always pass startLine/endLine and (optionally) maxBytes.',
+            {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Project-relative C# path under Assets/ or Packages/ (e.g., Packages/unity-mcp-server/Editor/Example.cs). Do NOT prefix repository folders (e.g., UnityMCPServer/…).'
+                    },
+                    startLine: {
+                        type: 'number',
+                        description: 'Starting line (1-based, inclusive). Defaults to 1.'
+                    },
+                    endLine: {
+                        type: 'number',
+                        description: 'Ending line (inclusive). Defaults to startLine + 199 when omitted.'
+                    },
+                    maxBytes: {
+                        type: 'number',
+                        description: 'Maximum bytes to return to cap payload size for LLMs.'
+                    }
+                },
+                required: ['path']
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+    }
+
+    validate(params) {
+        super.validate(params);
+
+        const { path, startLine, endLine } = params;
+
+        // Validate path
+        if (!path || path.trim() === '') {
+            throw new Error('path cannot be empty');
+        }
+
+        // Validate line numbers if provided
+        if (startLine !== undefined && startLine < 1) {
+            throw new Error('startLine must be at least 1');
+        }
+
+        if (endLine !== undefined && startLine !== undefined && endLine < startLine) {
+            throw new Error('endLine cannot be less than startLine');
+        }
+    }
+
+    async execute(params) {
+        const {
+            path,
+            startLine = 1,
+            endLine,
+            maxBytes
+        } = params;
+
+        try {
+            // Resolve project paths (Unity未接続でも推定可)
+            const info = await this.projectInfo.get();
+
+            // Normalize and validate
+            // Normalize common mistakes like UnityMCPServer/Packages/… → Packages/…
+            const raw = (path || '').replace(/\\/g, '/');
+            const ai = raw.indexOf('Assets/');
+            const pi = raw.indexOf('Packages/');
+            const idx = (ai >= 0 && pi >= 0) ? Math.min(ai, pi) : (ai >= 0 ? ai : pi);
+            const norm = idx >= 0 ? raw.substring(idx) : raw;
+            if (!norm.startsWith('Assets/') && !norm.startsWith('Packages/')) {
+                return { error: 'Path must be under Assets/ or Packages/' };
+            }
+            if (!norm.toLowerCase().endsWith('.cs')) {
+                return { error: 'Only .cs files are supported' };
+            }
+
+            const abs = info.projectRoot + '/' + norm;
+            const stat = await fs.stat(abs).catch(() => null);
+            if (!stat || !stat.isFile()) return { error: 'File not found', path: norm };
+
+            const data = await fs.readFile(abs, 'utf8');
+            const lines = data.split('\n');
+            const s = Math.max(1, startLine);
+            const e = Math.min(lines.length, endLine || (s + 199));
+            let content = lines.slice(s - 1, e).join('\n');
+
+            if (typeof maxBytes === 'number' && maxBytes > 0) {
+                const buf = Buffer.from(content, 'utf8');
+                if (buf.length > maxBytes) content = buf.subarray(0, maxBytes).toString('utf8');
+            }
+
+            return { success: true, path: norm, startLine: s, endLine: e, content };
+        } catch (e) {
+            logger.error(`[script_read] failed: ${e.message}`);
+            return { error: e.message };
+        }
+    }
+}