dsh-unity-mcp 0.0.5 → 0.0.7

package/README.md

@@ -6,7 +6,7 @@
 
 ## 能做什么
 
-**不依赖已连接的 Unity MCP：** 在 Windows 上按工程版本匹配并打开编辑器、等待工程就绪、准备 CoderGamester 安装、保存已加载场景和修改资源、先保存再安全关闭编辑器，以及保存 DSH 的工程连接配置。保存、关闭和就绪检查会向工程加入一个小型 Editor 桥接，仍需编辑器正常编译并运行。
+**不依赖已连接的 Unity MCP：** 在 Windows 上查看已打开的工程及 DSH 配置的连接目标，按工程版本匹配并打开编辑器、等待工程就绪、准备 CoderGamester 安装、保存已加载场景和修改资源、先保存再安全关闭编辑器，以及保存 DSH 的工程连接配置。保存、关闭和就绪检查会向工程加入一个小型 Editor 桥接，仍需编辑器正常编译并运行。
 
 **依赖引擎端 CoderGamester MCP：** 查询和编辑场景、GameObject、组件、材质与资源，查看控制台，以及调用上游提供的编辑器和测试功能。具体能力随上游版本变化；有工具清单不代表编辑器已经连通。
 
@@ -28,9 +28,11 @@ dsh-unity-mcp
 
 可以直接说：“打开 `C:/Projects/MyGame`，准备 CoderGamester，再连接这个工程。”
 
-Agent 加载工具后，会匹配工程要求的编辑器版本并打开工程，等待编辑器就绪，再准备包依赖和自动启动。工程处于关闭状态时，也可以先离线准备安装，再打开编辑器。包依赖固定在已核验的上游 commit，已有不同的 CoderGamester 依赖时不会擅自替换；其他包会保留。
+Agent 加载工具后，先用 `unity_project` 的 `list` 查看打开的工程和 DSH 配置的连接目标，再对明确的工程路径执行 `status`、`open`、`save` 或 `close`。`list` 只读，不会写入桥接或启动工程；工程路径无法读取的编辑器进程也会列出，并标为未知。`status` 会检查就绪但不启动编辑器，`open` 则在需要时按版本匹配并启动。
 
-**打开工程需要时间。** 工具会等待编辑器完成当前导入、编译并回应新鲜握手：返回 `editor_ready` / `editorReady: true` 才代表这次编辑器就绪检查通过。`editor_loading` 表示仍未确认就绪，应再次调用打开工具继续等待，不要重复启动或直接假设工程已经加载完成。运行或启动中的工程，安装工具也会在修改依赖前执行就绪检查；等待失败不会改写依赖。关闭工程的离线安装只代表文件准备完成，不代表工程已打开。
+安装 CoderGamester 和保存 DSH 连接分别由独立工具处理，避免把打开工程、修改包和切换所有会话的连接混为一次操作。工程处于关闭状态时，也可以先离线准备安装，再打开编辑器。包依赖固定在已核验的上游 commit，已有不同的 CoderGamester 依赖时不会擅自替换；其他包会保留。
+
+**打开工程需要时间。** 工具会等待编辑器完成当前导入、编译并回应新鲜握手：返回 `editor_ready` / `editorReady: true` 才代表这次编辑器就绪检查通过。`list` 中的 `running_not_verified` 只表示发现了进程。`status` 返回 `readiness_unconfirmed` 或 `open` 返回 `editor_loading` 时，应继续检查或等待，不要重复启动或假设工程已经加载完成。运行或启动中的工程，安装工具也会在修改依赖前执行就绪检查；等待失败不会改写依赖。关闭工程的离线安装只代表文件准备完成，不代表工程已打开。
 
 编辑器就绪仍不等于 MCP 连通。Package Manager 还需下载和编译引擎包，服务需要成功启动；Node 服务器缺少构建文件时，还需在其 `Server~` 目录执行 `npm install` 和 `npm run build`。安装工具不会代为下载或构建 Node 服务器，也不自动改变 DSH 连接。
 
@@ -48,7 +50,13 @@ Agent 加载工具后，会匹配工程要求的编辑器版本并打开工程
 
 ## 使用与安全边界
 
-每个 Agent 初始只看到 `unity_load_tools`，调用后才获得本地工程管理和已发现的上游工具；其他 Agent 不受影响。未连接 MCP 时仍可加载本地功能。服务器重连、工具更新和移除会同步到已加载的 Agent。需要立即暴露全部工具时，可将 `lazyTools` 设为 `false`。
+每个 Agent 初始只看到 `unity_load_tools`，调用后才获得本地工程管理和已发现的引擎工具；其他 Agent 不受影响。未连接 MCP 时仍可加载本地功能。服务器重连、工具更新和移除会同步到已加载的 Agent。需要立即暴露全部工具时，可将 `lazyTools` 设为 `false`，参数检查仍然有效。
+
+引擎操作按领域组织：`unity_transform` 处理位置、旋转和缩放，`unity_scene` 管理场景，`unity_material` 管理共享材质与绑定，`unity_play` 查询或控制播放状态。其他操作保留上游名称。目标对象只能指定一个 `instanceId` 或 `objectPath`；对象详情默认只读自身且不展开组件属性，核对变换或组件值时需显式设置 `includeComponentProperties: true`。控制台默认返回 20 条且不带堆栈。
+
+场景操作沿用上游副作用：创建场景使用 Single 模式；非 additive 加载会先尝试保存再替换已打开场景；删除场景不保存脏修改。场景 `save` 的 `scenePath` 是当前活动场景的另存目标，必须配合 `saveAs: true`，不能用来选择待保存场景。工程级安全保存请用 `unity_project`。材质修改会保存共享资源；未知 shader 属性可能被上游忽略，写后应回读。播放 `pause` 是切换操作，失败或超时后先查状态，不要盲目重试。
+
+适配层会拒绝容易误操作的参数，包括冲突目标、缺省父级、越界 layer、非有限数值及不受上游支持的材质路径。组件更新可能添加组件或留下部分修改，批量调用也不保证所有操作可回滚；工具成功回执不能替代回读验证。
 
 打开工程可能导入资源、运行工程内的编辑器脚本；安装包也会执行第三方代码。请只操作可信且已备份的工程。工具不会用不匹配的编辑器版本自动升级工程；自定义编辑器位置或多个匹配时，需要提供确切的 `editorPath`。
 

package/index.mjs

@@ -2,8 +2,7 @@ import z from '@deepseek-ai/schemastery';
 import * as mcp from '@deepseek-ai/dsh-mcp-client';
 import { connectionConfig } from './lib/connection.mjs';
 import { installLazyTools } from './lib/lazy-tools.mjs';
-import { openProjectTool } from './lib/open-project.mjs';
-import { lifecycleTools } from './lib/project-lifecycle.mjs';
+import { projectTool } from './lib/project.mjs';
 import { installationTool } from './lib/install-codergamester.mjs';
 import { configurationTool } from './lib/configure-project.mjs';
 export const name = 'dsh-unity-mcp';
@@ -19,7 +18,7 @@ export const Config = z.object({
 });
 export async function apply(ctx, config) {
   // Install the loader even before configuration, so discovery explains setup.
-  installLazyTools(ctx, config.lazyTools, [configurationTool(ctx), openProjectTool(), ...lifecycleTools(), installationTool()]);
+  installLazyTools(ctx, config.lazyTools, [projectTool(ctx), installationTool(), configurationTool(ctx)]);
   if (!config.projectPath && !config.serverPath) {
     ctx.logger.info('Unity MCP: configure projectPath or serverPath to connect CoderGamester/mcp-unity.');
     return;

package/lib/engine-tools.mjs

@@ -0,0 +1,150 @@
+const PREFIX = 'mcp__unity__';
+const object = properties => ({ type: 'object', properties, additionalProperties: false });
+const text = value => [{ type: 'text', text: JSON.stringify(value) }];
+const has = (o, k) => Object.hasOwn(o, k) && o[k] !== undefined;
+function target(args) {
+  const id = has(args, 'instanceId'), p = has(args, 'objectPath');
+  if (id === p) throw Error('Provide exactly one target: instanceId or objectPath. Use an instanceId from a recent read for inactive or ambiguous objects.');
+  if (id && (!Number.isInteger(args.instanceId) || args.instanceId === 0)) throw Error('instanceId must be a nonzero integer.');
+  if (p) {
+    if (typeof args.objectPath !== 'string' || !args.objectPath.trim()) throw Error('objectPath must be nonempty.');
+    args.objectPath = args.objectPath.replace(/^\/+/, '');
+    if (!args.objectPath.trim()) throw Error('objectPath must identify an object, not the hierarchy root.');
+  }
+}
+export function normalizeEngineArgs(name, input) {
+  const args = { ...input };
+  const finite = value => { if (typeof value === 'number' && !Number.isFinite(value)) throw Error('Numeric values must be finite.'); if (value && typeof value === 'object') for (const item of Object.values(value)) finite(item); };
+  finite(args);
+  if (['move_gameobject', 'rotate_gameobject', 'scale_gameobject', 'set_transform', 'update_gameobject', 'delete_gameobject', 'duplicate_gameobject', 'reparent_gameobject', 'update_component', 'assign_material', 'select_gameobject'].includes(name)) {
+    if (name === 'select_gameobject' && args.objectName && !args.objectPath) { args.objectPath = args.objectName; delete args.objectName; }
+    target(args);
+  }
+  if (name === 'get_gameobject') {
+    if (typeof args.idOrName !== 'string' || !args.idOrName.trim()) throw Error('idOrName must be a nonempty ID or hierarchy path.');
+    args.idOrName = args.idOrName.replace(/^\/+/, '');
+    args.maxDepth ??= 0; args.includeComponents ??= true; args.includeComponentProperties ??= false;
+  }
+  if (name === 'get_console_logs') { args.includeStackTrace ??= false; args.limit ??= 20; args.offset ??= 0; }
+  if (name === 'reparent_gameobject') {
+    if (!has(args, 'newParent') && !has(args, 'newParentId')) throw Error('Specify newParent or newParentId explicitly; use newParent:null to move to the scene root.');
+    if (has(args, 'newParent') && has(args, 'newParentId')) throw Error('Provide only one new parent selector.');
+    if (args.worldPositionStays === false) throw Error('Upstream false resets local position, rotation AND scale. Reparent with worldPositionStays:true, then set explicit local TRS.');
+    args.worldPositionStays = true;
+  }
+  if (name === 'update_gameobject') {
+    const data = args.gameObjectData;
+    if (!data || !Object.keys(data).length) throw Error('gameObjectData must contain a change.');
+    if (has(data, 'layer') && (!Number.isInteger(data.layer) || data.layer < 0 || data.layer > 31)) throw Error('layer must be an integer from 0 to 31.');
+  }
+  if (name === 'set_transform' && !['position', 'rotation', 'scale'].some(k => has(args, k))) throw Error('Supply at least one of position, rotation or scale.');
+  if (name === 'update_component' && args.componentData && Object.values(args.componentData).some(v => typeof v === 'number' && !Number.isFinite(v))) throw Error('Component values must be finite.');
+  if (name === 'save_scene' && args.saveAs && !args.scenePath) throw Error('scenePath is required for Save As.');
+  if (name === 'save_scene' && args.scenePath && args.saveAs !== true) throw Error('scenePath always saves the ACTIVE scene to a destination; set saveAs:true explicitly. It is not a scene selector.');
+  if (name === 'modify_material' && (!args.properties || !Object.keys(args.properties).length)) throw Error('properties must contain at least one shader property.');
+  if (['load_scene', 'unload_scene', 'delete_scene'].includes(name) && !args.scenePath && !args.sceneName) throw Error('Provide scenePath or sceneName. Prefer scenePath for an unambiguous scene.');
+  if (['create_material', 'modify_material', 'get_material_info', 'assign_material'].includes(name)) {
+    const key = name === 'create_material' ? 'savePath' : 'materialPath';
+    if (typeof args[key] !== 'string' || !/^Assets\/.+\.mat$/i.test(args[key]) || args[key].split('/').includes('..')) throw Error(key + ' must be an explicit Assets/.../*.mat path; Packages paths are not supported by this upstream implementation.');
+    if (args.properties && Object.values(args.properties).some(v => v === null)) throw Error('Upstream cannot clear textures with null. Use an explicit supported shader value.');
+  }
+  return args;
+}
+const notes = {
+  update_gameobject: ' Updates may create missing paths. Prefer instanceId to update existing objects. Invalid tags can be silently ignored upstream; read back after writing.',
+  update_component: ' May add a missing component; failed updates may leave partial changes. Enum integers are indices, not underlying values; prefer names. References accept assets, not scene instance IDs. Read back after writing.',
+  duplicate_gameobject: ' Upstream returns only an acknowledgement: query the new hierarchy for IDs before further edits.',
+  reparent_gameobject: ' Parent must be explicit; only preserving world TRS is supported here.',
+  batch_execute: ' Upstream batch is not an adapter transaction. Tool names/params use raw upstream contracts; do not use batch to bypass safer domain selectors or assume every write is atomic.',
+};
+function validate(schema, value, path = 'arguments') {
+  if (schema.oneOf) {
+    let matches = 0;
+    for (const branch of schema.oneOf) { try { validate(branch, value, path); matches++; } catch {} }
+    if (matches !== 1) throw Error(path + ' must match exactly one supported shape.');
+  }
+  const type = schema.type;
+  if (type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error(path + ' must be an object.');
+    for (const key of schema.required ?? []) if (!has(value, key)) throw Error(path + '.' + key + ' is required.');
+    for (const [key, item] of Object.entries(value)) {
+      const child = schema.properties?.[key];
+      if (child) validate(child, item, path + '.' + key);
+      else if (schema.additionalProperties === false) throw Error(path + '.' + key + ' is not supported.');
+    }
+  } else if (type === 'array') {
+    if (!Array.isArray(value)) throw Error(path + ' must be an array.');
+    if (schema.items) value.forEach((v, i) => validate(schema.items, v, path + '[' + i + ']'));
+  } else if (type === 'null' ? value !== null : type === 'integer' ? !Number.isInteger(value) : type && typeof value !== type) throw Error(path + ' must be ' + type + '.');
+  if (schema.enum && !schema.enum.includes(value)) throw Error(path + ' is not a supported value.');
+  if (has(schema, 'const') && value !== schema.const) throw Error(path + ' does not match the required value.');
+  if (typeof value === 'number' && (!Number.isFinite(value) || has(schema, 'minimum') && value < schema.minimum || has(schema, 'maximum') && value > schema.maximum)) throw Error(path + ' is outside the supported numeric range.');
+}
+export function createEngineTools(rawTools) {
+  const raw = new Map(rawTools.map(t => [t.name.slice(PREFIX.length), t]));
+  const invoke = async (name, input, exec) => {
+    const definition = raw.get(name);
+    if (!definition) throw Error('Unity tool is unavailable: ' + name + '. Check the connection and reload tools.');
+    const args = normalizeEngineArgs(name, input);
+    validate(definition.parameters, args);
+    return definition.execute(args, exec);
+  };
+  const result = [], consumed = new Set();
+  function group(name, description, actions) {
+    const entries = Object.entries(actions).filter(([, upstream]) => raw.has(upstream));
+    if (!entries.length) return;
+    const branches = entries.map(([action, upstream]) => {
+      consumed.add(upstream);
+      const schema = structuredClone(raw.get(upstream).parameters);
+      delete schema.$schema;
+      schema.properties = { action: { type: 'string', const: action }, ...schema.properties };
+      schema.required = ['action', ...(schema.required ?? [])];
+      return schema;
+    });
+    const properties = { action: { type: 'string', enum: entries.map(([a]) => a) } };
+    for (const branch of branches) for (const [key, value] of Object.entries(branch.properties)) if (key !== 'action') properties[key] ??= value;
+    for (const [key, schema] of Object.entries(properties)) {
+      if (key === 'action') continue;
+      const used = entries.filter(([, upstream]) => has(raw.get(upstream).parameters.properties ?? {}, key)).map(([a]) => a);
+      const required = entries.filter(([, upstream]) => raw.get(upstream).parameters.required?.includes(key)).map(([a]) => a);
+      properties[key] = { ...schema, description: (schema.description ? schema.description + ' ' : '') + 'Actions: ' + used.join(', ') + '.' + (required.length ? ' Required for: ' + required.join(', ') + '.' : '') };
+    }
+    result.push({ name, description, parameters: { ...object(properties), required: ['action'] },
+      output: { schema: {}, render: (args, value) => { const { action, ...input } = args; return raw.get(actions[action]).output.render(input, value); } },
+      projectContent: (exec, value) => raw.get(actions[exec.arguments.action])?.projectContent?.(exec, value),
+      execute: async (input, exec) => {
+        const upstream = actions[input.action];
+        if (!entries.some(([a]) => a === input.action)) throw Error('Unsupported action: ' + input.action);
+        const { action, ...args } = input;
+        const schema = raw.get(upstream).parameters;
+        for (const key of Object.keys(args)) if (!has(schema.properties ?? {}, key)) throw Error(key + ' is not valid for action ' + action);
+        for (const key of schema.required ?? []) if (!has(args, key)) throw Error(key + ' is required for action ' + action);
+        return invoke(upstream, args, exec);
+      } });
+  }
+  group('unity_transform', 'Set position/rotation/local scale, translate, rotate or multiply local scale. Targets require exactly one instanceId or objectPath. Relative rotation composes rotations; local translation adds parent-local coordinates. Writes return upstream acknowledgement, not verified actual TRS; read the object to verify.', { set: 'set_transform', translate: 'move_gameobject', rotate: 'rotate_gameobject', scale: 'scale_gameobject' });
+  group('unity_scene', 'Inspect or manage scenes. create uses Single mode even with makeActive:false and can replace open scenes. load defaults to saving then replacing open scenes (save failure is not checked upstream); additive:true keeps them. unload defaults to saveIfDirty:true but does not verify save success; delete closes without saving. Prefer scenePath over ambiguous names. save targets the ACTIVE scene; scenePath is a Save As destination, never a selector. For verified all-scene save use unity_project save.', { info: 'get_scene_info', create: 'create_scene', load: 'load_scene', save: 'save_scene', unload: 'unload_scene', delete: 'delete_scene' });
+  group('unity_material', 'Inspect/create/modify a material asset or bind an existing Renderer slot. Modification affects every shared reference and saves the asset. Creation may replace an existing asset: choose a new path. Unknown/invalid properties may be ignored upstream; read info after writes. Texture clearing is unsupported.', { info: 'get_material_info', create: 'create_material', modify: 'modify_material', assign: 'assign_material' });
+  // Play control already uses action, so expose direct state actions rather than nesting it.
+  if (raw.has('get_play_mode_status') && raw.has('set_play_mode_status')) {
+    consumed.add('get_play_mode_status'); consumed.add('set_play_mode_status');
+    result.push({ name: 'unity_play', description: 'Read or control Play Mode. pause toggles pause; play starts/unpauses; stop exits; step advances a paused frame. Play Mode changes can be discarded on stop.', parameters: { ...object({ action: { type: 'string', enum: ['status', 'play', 'pause', 'stop', 'step'] } }), required: ['action'] }, output: { schema: {}, render: (args, value) => raw.get(args.action === 'status' ? 'get_play_mode_status' : 'set_play_mode_status').output.render(args.action === 'status' ? {} : args, value) }, projectContent: (exec, value) => raw.get(exec.arguments.action === 'status' ? 'get_play_mode_status' : 'set_play_mode_status')?.projectContent?.(exec, value), execute: (input, exec) => {
+      if (Object.keys(input).some(key => key !== 'action')) throw Error('Play accepts only action.');
+      if (!['status', 'play', 'pause', 'stop', 'step'].includes(input.action)) throw Error('Unsupported Play action.');
+      return invoke(input.action === 'status' ? 'get_play_mode_status' : 'set_play_mode_status', input.action === 'status' ? {} : { action: input.action }, exec);
+    } });
+  }
+  for (const [name, tool] of raw) if (!consumed.has(name)) {
+    const parameters = structuredClone(tool.parameters);
+    if (name === 'get_gameobject') {
+      parameters.properties.maxDepth = { ...parameters.properties.maxDepth, default: 0, description: 'Child depth; default 0. Query children directly when truncated.' };
+      parameters.properties.includeComponentProperties = { type: 'boolean', default: false, description: 'Include serialized component values; default false.' };
+    }
+    if (name === 'get_console_logs') {
+      parameters.properties.includeStackTrace = { type: 'boolean', default: false, description: 'Include stack traces; default false.' };
+      parameters.properties.limit = { ...parameters.properties.limit, default: 20, description: 'Page size; default 20, maximum 500.' };
+    }
+    result.push({ ...tool, parameters, description: tool.description + (notes[name] ?? ''), execute: (args, exec) => invoke(name, args, exec) });
+  }
+  return result;
+}

package/lib/install-codergamester.mjs

@@ -17,7 +17,7 @@ export async function installCoderGamester(input, deps = {}) {
     const lock = await stat(path.join(root, 'Temp/UnityLockfile')).catch(e => { if (e.code !== 'ENOENT') throw e; });
     if (editor || launchPending(root) || lock) {
       try { await (deps.waitReady ?? waitForEditor)(root, Math.max(1, deadline - Date.now()), deps); }
-      catch (error) { throw Error('Editor not ready; package dependencies were not changed. Wait with unity_open_project before retrying installation. ' + error.message); }
+      catch (error) { throw Error('Editor not ready; package dependencies were not changed. Wait with unity_project action=status or open before retrying installation. ' + error.message); }
     }
     const manifest = path.join(root, 'Packages/manifest.json');
     const original = await readFile(manifest, 'utf8');

package/lib/lazy-tools.mjs

@@ -1,20 +1,23 @@
+import { createEngineTools } from './engine-tools.mjs';
 const PREFIX = 'mcp__unity__';
 const empty = { type: 'object', properties: {}, additionalProperties: false };
 export function installLazyTools(ctx, lazy = true, setupTools = []) {
   const states = new Map();
-  const definitions = () => [...setupTools, ...ctx.tools.schemas().filter(tool => tool.name.startsWith(PREFIX)).map(tool => ctx.tools.get(tool.name)).filter(Boolean)];
-  if (!lazy) for (const tool of setupTools) ctx.tools.register(tool);
+  const rawDefinitions = () => ctx.tools.schemas().filter(tool => tool.name.startsWith(PREFIX)).map(tool => ctx.tools.get(tool.name)).filter(Boolean);
+  const definitions = () => [...setupTools, ...createEngineTools(rawDefinitions())];
   function attach(agent) {
     if (states.has(agent)) return;
     const state = { loaded: !lazy, signature: '', disposers: [], tools: [] };
     const refresh = () => {
-      const defs = definitions(), signature = JSON.stringify(defs.map(({ name, description, parameters }) => ({ name, description, parameters })));
-      if (signature === state.signature) return;
+      const raw = rawDefinitions();
+      const defs = [...setupTools, ...createEngineTools(raw)], signature = JSON.stringify(defs.map(({ name, description, parameters }) => ({ name, description, parameters })));
+      if (signature === state.signature && raw.length === state.raw?.length && raw.every((tool, i) => tool === state.raw[i])) return;
+      state.raw = raw;
       for (const dispose of state.tools.splice(0).reverse()) dispose();
       if (state.mask) { state.mask(); state.mask = undefined; }
-      const engineNames = defs.filter(tool => tool.name.startsWith(PREFIX)).map(tool => tool.name);
-      if (lazy && engineNames.length) state.mask = agent.ctx.tools.restrict({ deny: engineNames });
-      if (state.loaded && lazy) {
+      const engineNames = rawDefinitions().map(tool => tool.name);
+      if (engineNames.length) state.mask = agent.ctx.tools.restrict({ deny: engineNames });
+      if (state.loaded) {
         const installed = [];
         try { for (const definition of defs) installed.push(agent.ctx.tools.register({ ...definition })); }
         catch (error) { for (const dispose of installed.reverse()) dispose(); throw error; }
@@ -32,7 +35,7 @@ export function installLazyTools(ctx, lazy = true, setupTools = []) {
     states.set(agent, state);
     if (lazy) state.disposers.push(agent.ctx.tools.register({
       name: 'unity_load_tools',
-      description: 'Load Unity/Tuanjie tools for this agent, including opening projects and configuring connections even when disconnected. Editor tools cover scenes, GameObjects, assets and console; they require CoderGamester/mcp-unity in the engine. Loading itself changes no configuration or project.',
+      description: 'Load Unity/Tuanjie tools for this agent. Start with unity_project action=list to discover open projects and the configured DSH target; then inspect/open/save/close a chosen project. Local management and package installation work without MCP; scene/object/asset tools require CoderGamester in the selected engine. Loading changes no project or connection.',
       parameters: empty,
       output: { schema: { type: 'object', properties: { tools: { type: 'array', items: { type: 'string' } } }, required: ['tools'], additionalProperties: false }, render: (_, value) => [{ type: 'text', text: JSON.stringify(value) }] },
       execute: async () => {

package/lib/open-project.mjs

@@ -21,7 +21,7 @@ async function finishOpen(result, input, deps) {
     await (deps.waitReady ?? waitForEditor)(result.projectPath, input.timeoutMs ?? 120000, deps);
     return { ...result, status: 'editor_ready', editorReady: true, message: 'Editor responded after import/compilation settled. MCP connectivity is not verified.' };
   } catch (error) {
-    return { ...result, status: 'editor_loading', editorReady: false, message: 'Not ready: ' + error.message + ' Do not assume loading finished. Retry unity_open_project to wait again; do not relaunch or configure MCP yet.' };
+    return { ...result, status: 'editor_loading', editorReady: false, message: 'Not ready: ' + error.message + ' Do not assume loading finished. Retry unity_project action=status or open to wait again; do not relaunch or configure MCP yet.' };
   }
 }
 async function powershell(script) {
@@ -97,8 +97,3 @@ async function launchEditor(editor, project) {
     child.once('spawn', () => { child.unref(); resolve(child.pid); });
   });
 }
-export function openProjectTool() {
-  return { name: 'unity_open_project', description: 'Open a Unity/Tuanjie project in its exact matching Windows editor and wait for an Editor readiness handshake, including when already running. May import assets and run project scripts; installs/updates the DSH Editor bridge. editor_loading means not ready: retry this tool to wait again, without relaunching. Does not configure or verify MCP.',
-    parameters: { type: 'object', properties: { projectPath: { type: 'string', description: 'Absolute existing project directory.' }, editorPath: { type: 'string', description: 'Optional absolute matching Unity.exe/Tuanjie.exe; omit to search standard Hub install locations.' }, timeoutMs: { type: 'integer', minimum: 1000, maximum: 180000, description: 'Editor readiness wait budget; default 120000 ms. Timeout returns editor_loading; retry to wait longer.' } }, required: ['projectPath'], additionalProperties: false },
-    output: { schema: { type: 'object', properties: { status: { type: 'string' }, projectPath: { type: 'string' }, editorPath: { type: 'string' }, version: { type: 'string' }, pid: { type: 'integer' }, editorReady: { type: 'boolean' }, message: { type: 'string' } }, required: ['status', 'projectPath', 'editorPath', 'version', 'pid', 'editorReady', 'message'], additionalProperties: false }, render: (_, value) => [{ type: 'text', text: JSON.stringify(value) }] }, execute: input => openProject(input) };
-}

package/lib/project-lifecycle.mjs

@@ -75,9 +75,3 @@ export async function requestProject(input, action, deps = {}) {
     throw Error('Editor response timed out. Operation may have begun; inspect the editor before retrying. No force kill was attempted.');
   } finally { if (request) await unlink(request).catch(() => {}); pending.delete(root); }
 }
-export function lifecycleTools() {
-  return ['save', 'close'].map(action => ({ name: `unity_${action}_project`,
-    description: action === 'save' ? 'Save all named loaded scenes and dirty assets in a running Windows Unity/Tuanjie project. Installs a small Editor bridge in Assets/Editor/DshUnityMcp (may trigger compilation); no existing MCP connection required. Rejects Play mode, Prefab Mode and unnamed scenes.' : 'Save scenes/assets then request normal exit for the specified Windows Unity/Tuanjie project and verify process exit. Installs an Editor bridge if absent. Save failure prevents exit; never force-kills or discards changes. Timeout is not proof of exit.',
-    parameters: { type: 'object', properties: { projectPath: { type: 'string', description: 'Absolute running project directory.' }, timeoutMs: { type: 'integer', minimum: 1000, maximum: 180000, description: 'Wait budget including bridge compilation and exit; default 60000 ms.' } }, required: ['projectPath'], additionalProperties: false },
-    output: { schema: { type: 'object', properties: { status: { type: 'string' }, projectPath: { type: 'string' }, pid: { type: 'integer' } }, required: ['status', 'projectPath', 'pid'], additionalProperties: false }, render: (_, value) => [{ type: 'text', text: JSON.stringify(value) }] }, execute: input => requestProject(input, action) }));
-}

package/lib/project.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { readFile, realpath } from 'node:fs/promises';
+import { windowsProcesses, projectFromCommandLine, openProject } from './open-project.mjs';
+import { requestProject, projectRoot } from './project-lifecycle.mjs';
+
+export function connectionTarget(ctx) {
+  const rows = ctx.configEditor.configuration().filter(row => row.entry.options.name === 'dsh-unity-mcp');
+  if (rows.length !== 1) return { status: 'ambiguous', projectPath: '', serverPath: '' };
+  const config = { ...rows[0].inherited, ...rows[0].override };
+  return { status: config.projectPath || config.serverPath ? 'configured_not_verified' : 'not_configured', projectPath: config.projectPath || '', serverPath: config.serverPath || '' };
+}
+export async function listProjects(target = {}, deps = {}) {
+  if ((deps.platform ?? process.platform) !== 'win32') throw Error('Project discovery currently supports Windows only.');
+  const processes = await (deps.processes ?? windowsProcesses)();
+  const canonical = async value => value ? realpath(value).catch(() => path.resolve(value)) : '';
+  const selected = (await canonical(target.projectPath)).toLowerCase();
+  const projects = [];
+  for (const row of Array.isArray(processes) ? processes : [processes]) {
+    if (!row) continue;
+    const raw = projectFromCommandLine(row.CommandLine);
+    const projectPath = await canonical(raw);
+    let version = '';
+    if (projectPath) version = /^m_EditorVersion:\s*(\S+)/m.exec(await readFile(path.join(projectPath, 'ProjectSettings/ProjectVersion.txt'), 'utf8').catch(() => ''))?.[1] || '';
+    projects.push({ pid: row.ProcessId, projectPath, editorPath: row.ExecutablePath || '', version, state: projectPath ? 'running_not_verified' : 'project_unknown', configuredTarget: Boolean(selected && selected === projectPath.toLowerCase()) });
+  }
+  projects.sort((a, b) => a.pid - b.pid);
+  return { projects: projects.slice(0, 100), total: projects.length, truncated: projects.length > 100, connection: target, message: 'Process inventory only; readiness and MCP connectivity are not verified. Unknown project paths may reflect inaccessible process arguments. Use status for a selected project. Connection settings affect all profile sessions.' };
+}
+export async function manageProject(input, target = {}, deps = {}) {
+  if (input.action === 'list') return listProjects(target, deps);
+  if (!input.projectPath) throw Error('projectPath is required for this action. Use action=list to discover open projects.');
+  if (input.action === 'open') return (deps.open ?? openProject)(input, deps);
+  if (input.action === 'save' || input.action === 'close') return (deps.request ?? requestProject)(input, input.action, deps);
+  if (input.action === 'status') {
+    const root = await projectRoot(input.projectPath);
+    const inventory = await listProjects(target, deps);
+    if (inventory.truncated) throw Error('Editor inventory exceeds 100 processes; status cannot safely select a project.');
+    const matches = inventory.projects.filter(p => p.projectPath.toLowerCase() === root.toLowerCase());
+    if (!matches.length) return { status: 'not_running', projectPath: root, editorReady: false, connection: target, message: 'No matching editor process found; MCP connectivity is not verified.' };
+    if (matches.length !== 1) throw Error('Multiple editor processes match this project. Resolve duplicates before acting.');
+    try {
+      await (deps.request ?? requestProject)({ ...input, timeoutMs: input.timeoutMs ?? 10000 }, 'ready', deps);
+      return { ...matches[0], state: 'editor_ready', status: 'editor_ready', editorReady: true, connection: target, message: 'Editor readiness confirmed; MCP connectivity is not verified.' };
+    } catch (error) {
+      return { ...matches[0], status: 'readiness_unconfirmed', editorReady: false, connection: target, message: error.message };
+    }
+  }
+  throw Error('Unknown project action.');
+}
+export function projectTool(ctx) {
+  return { name: 'unity_project', description: 'Discover and manage Windows Unity/Tuanjie projects without MCP. list is read-only and shows all editor processes plus the configured DSH target; it does not prove readiness. status waits for readiness without launching; open launches if needed and waits. status/open/save/close may install an Editor bridge and trigger compilation. close saves first, verifies normal exit, never force-kills or discards changes. Save/close reject Play Mode, Prefab Mode and unnamed scenes. Does not switch or verify MCP connections.',
+    parameters: { type: 'object', properties: {
+      action: { type: 'string', enum: ['list', 'status', 'open', 'save', 'close'], description: 'Start with list to choose an explicit project. status checks readiness; open also starts a closed project; save saves all named loaded scenes/assets; close saves then exits.' },
+      projectPath: { type: 'string', description: 'Absolute project directory; required except for list. Never inferred from the current connection.' },
+      editorPath: { type: 'string', description: 'Only for open: optional absolute exact-version Unity.exe/Tuanjie.exe.' },
+      timeoutMs: { type: 'integer', minimum: 1000, maximum: 180000, description: 'Wait budget: status default 10000 ms, open 120000 ms, save/close 60000 ms. Retry status/open after an unconfirmed readiness result; do not assume it is ready.' }
+    }, required: ['action'], additionalProperties: false },
+    output: { schema: { type: 'object' }, render: (_, value) => [{ type: 'text', text: JSON.stringify(value) }] },
+    execute: input => {
+      if (input.action === 'list' && (input.projectPath || input.editorPath)) throw Error('list accepts no projectPath or editorPath.');
+      if (input.editorPath && input.action !== 'open') throw Error('editorPath is only used by open.');
+      return manageProject(input, connectionTarget(ctx));
+    } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-unity-mcp",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Unity and Tuanjie editor tools for DSH, powered by CoderGamester/mcp-unity with per-agent lazy loading.",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,7 @@
     }
   },
   "scripts": {
-    "check": "node --check index.mjs && node --check lib/connection.mjs && node --check lib/lazy-tools.mjs && node --check lib/configure-project.mjs && node --check lib/open-project.mjs && node --check lib/project-lifecycle.mjs && node --check lib/install-codergamester.mjs",
+    "check": "node --check index.mjs && node --check lib/project.mjs && node --check lib/connection.mjs && node --check lib/engine-tools.mjs && node --check lib/lazy-tools.mjs && node --check lib/configure-project.mjs && node --check lib/open-project.mjs && node --check lib/project-lifecycle.mjs && node --check lib/install-codergamester.mjs",
     "test": "node --test test/*.test.mjs",
     "build": "npm run check",
     "pack:check": "npm pack --dry-run --json"