dsh-eda-mcp 0.6.2 → 0.7.1

package/src/bridge/index.ts

@@ -1,8 +1,15 @@
 // @ts-nocheck -- the bridge is authored as dependency-free JS and bundled by esbuild; runtime tests cover it.
 import { createHash } from 'node:crypto'
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
 import type { Socket } from 'node:net'
 import { createInterface } from 'node:readline'
+import { buildLaunchArgs, buildLaunchScript, decodeRegistryOutput, resolveExecutable, type LaunchProbe } from './eda-launch.ts'
 import {
   ANNULUS_MIN_MM, BOARD_OUTLINE_WIDTH_MIL, MIN_TRACK_WIDTH_MIL, POUR_CLEARANCE_MIN_MIL,
   POUR_CLEARANCE_RECOMMENDED_MIL, SILKSCREEN_HEIGHT_MIN_MM, SILKSCREEN_WIDTH_MIN_MM,
@@ -10,7 +17,7 @@ import {
   assertNetName, checkNetName, checkTrackWidth, checkVia, classifyNet, milToMm, suggestTrackWidthMil,
 } from './design-rules.ts'
 
-const VERSION = '0.3.5'
+const VERSION = '0.4.0'
 const WS_PORT = Number(process.env.DSH_EDA_MCP_WS_PORT ?? 39009)
 const WS_HOST = '127.0.0.1'
 const ALLOW_RAW_API = (process.env.DSH_EDA_MCP_ALLOW_RAW_API ?? '1') !== '0'
@@ -230,6 +237,21 @@ function objectSchema(properties, required = []) {
 
 const TOOLS = [
   { name: 'eda_status', description: 'Get the dsh-eda-mcp bridge status and how many JLCEDA Pro bridge extensions are connected.', inputSchema: objectSchema({}) },
+  { name: 'eda_list_projects', description: 'List project UUIDs in the workspace (dmt_Project.getAllProjectsUuid). resolveNames=true (default) also reads getProjectInfo per project so callers can match by friendly name.', inputSchema: objectSchema({ teamUuid: { type: 'string' }, folderUuid: { type: 'string' }, workspaceUuid: { type: 'string' }, resolveNames: { type: 'boolean' }, limit: { type: 'integer' } }) },
+  { name: 'eda_get_project', description: 'Read the current project (dmt_Project.getCurrentProjectInfo): uuid, friendly name, folder/team and other brief fields.', inputSchema: objectSchema({}) },
+  { name: 'eda_open_project', description: 'Open a project by uuid, or by friendly name when only a name is known (the name is resolved through getAllProjectsUuid + getProjectInfo, exact match first, then case-insensitive substring).', inputSchema: objectSchema({ uuid: { type: 'string' }, name: { type: 'string' } }) },
+  { name: 'eda_create_project', description: 'Create a project (dmt_Project.createProject) and return its uuid; open=true (default false) also opens it. friendlyName is required; name and folder/team default to the app defaults.', inputSchema: objectSchema({ friendlyName: { type: 'string' }, name: { type: 'string' }, teamUuid: { type: 'string' }, folderUuid: { type: 'string' }, description: { type: 'string' }, open: { type: 'boolean' } }, ['friendlyName']) },
+  { name: 'eda_get_workspace', description: 'Read the current workspace and team (dmt_Workspace.getCurrentWorkspaceInfo / dmt_Team.getCurrentTeamInfo). Needed before creating a project, which requires a team (and usually a folder) uuid.', inputSchema: objectSchema({}) },
+  { name: 'eda_list_teams', description: 'List teams (dmt_Team.getAllTeamsInfo), optionally including the teams this account is involved in.', inputSchema: objectSchema({ involved: { type: 'boolean' } }) },
+  { name: 'eda_list_folders', description: 'List folder uuids of one team (dmt_Folder.getAllFoldersUuid), optionally resolved through getFolderInfo.', inputSchema: objectSchema({ teamUuid: { type: 'string' }, resolveNames: { type: 'boolean', } }) },
+  { name: 'eda_delete_project', description: 'Delete a project (dmt_Project.deleteProject) by uuid or friendly name.', inputSchema: objectSchema({ uuid: { type: 'string' }, name: { type: 'string' } }) },
+  { name: 'eda_modify_project', description: 'Rename a project or change its description (dmt_Project.modifyProjectFriendlyName / modifyProjectDescription), addressed by uuid or current friendly name.', inputSchema: objectSchema({ uuid: { type: 'string' }, name: { type: 'string' }, friendlyName: { type: 'string' }, description: { type: 'string' } }) },
+  { name: 'eda_copy_project', description: 'Copy a project (dmt_Project.copyProject), optionally into another team/folder and with a new friendly name; returns the new uuid.', inputSchema: objectSchema({ sourceUuid: { type: 'string' }, sourceName: { type: 'string' }, targetTeamUuid: { type: 'string' }, targetFolderUuid: { type: 'string' }, newFriendlyName: { type: 'string' }, newName: { type: 'string' } }) },
+  { name: 'eda_close_document', description: 'Close one editor tab (dmt_EditorControl.closeDocument).', inputSchema: objectSchema({ tabId: { type: 'string' } }, ['tabId']) },
+  { name: 'eda_export_project', description: 'Export a project file (sys_FileManager.getProjectFile / getProjectFileByProjectUuid). With outPath the bridge writes the bytes to disk and returns the path; without it the base64 payload is returned only when inline=true.', inputSchema: objectSchema({ uuid: { type: 'string' }, fileName: { type: 'string' }, fileType: { type: 'string', enum: ['epro', 'epro2'] }, outPath: { type: 'string' }, inline: { type: 'boolean' } }) },
+  { name: 'eda_import_project', description: 'Import a local project file (.eprj2/.epro/...) into a team (sys_FileManager.importProjectByProjectFile with a saveTo target). teamUuid is required in local mode: without a target team the app imports nothing. Returns whether the import actually landed.', inputSchema: objectSchema({ path: { type: 'string' }, teamUuid: { type: 'string' }, folderUuid: { type: 'string' }, friendlyName: { type: 'string' }, fileType: { type: 'string' }, open: { type: 'boolean' } }, ['path']) },
+  { name: 'eda_close', description: 'Close JLCEDA Pro gracefully (taskkill /T on Windows, SIGTERM elsewhere), then force-kill if it is still running after waitMs (default 8000). Returns the remaining process count.', inputSchema: objectSchema({ force: { type: 'boolean' }, waitMs: { type: 'integer' } }) },
+  { name: 'eda_launch', description: 'Launch JLCEDA Pro (EasyEDA Pro), optionally opening a .eprj2/.eprj project, then wait until the bridge extension connects. The executable is resolved from DSH_EDA_EXECUTABLE/JLCEDA_EXECUTABLE, the registry handler the installer registered, conventional install directories, then PATH - so it works on any machine without configuration.', inputSchema: objectSchema({ project: { type: 'string' }, executable: { type: 'string' }, waitForExtension: { type: 'boolean' }, timeoutMs: { type: 'integer' } }) },
   { name: 'eda_get_page_info', description: 'Return the current schematic page, the A4 frame range, the title-block keep-out range, and the recommended safe placement areas. All coordinates are MCP units (0.01 inch).', inputSchema: objectSchema({ paper: { type: 'string' } }) },
   { name: 'eda_get_schematic_pages', description: 'List the schematic pages of the current schematic, or fetch one page by uuid.', inputSchema: objectSchema({ pageUuid: { type: 'string' } }) },
   { name: 'eda_search_components', description: 'Search JLCEDA library devices by keyword. Returns candidate components with uuid/libraryUuid needed by eda_place_component.', inputSchema: objectSchema({ keyword: { type: 'string' }, limit: { type: 'integer' } }, ['keyword']) },
@@ -391,6 +413,9 @@ class WsConnection {
     this.socket.destroy()
   }
   handleData(chunk) {
+    // Liveness: a page that navigates away leaves a half-open socket that still
+    // looks ready, so every timestamp counts, not just pongs.
+    this.lastSeenAt = Date.now()
     this.buffer = Buffer.concat([this.buffer, chunk])
     for (;;) {
       const frame = parseFrame(this.buffer)
@@ -449,16 +474,25 @@ async function pcbComponentIds(timeoutMs) {
 }
 let nextCallId = 1
 
-function firstReadyClient() {
-  for (const client of clients) if (client.ready) return client
-  return undefined
+/** A socket that has been silent this long is treated as dead even if it never closed. */
+const CLIENT_STALE_MS = 60000
+
+/** Ready clients, freshest first. Stale sockets are used only as a last resort. */
+function pickClients() {
+  const now = Date.now()
+  const ready = [...clients].filter(client => client.ready)
+  const fresh = ready.filter(client => now - (client.lastSeenAt ?? 0) < CLIENT_STALE_MS)
+  const pool = fresh.length > 0 ? fresh : ready
+  return pool.sort((left, right) => (right.lastSeenAt ?? 0) - (left.lastSeenAt ?? 0))
 }
 
-function callExtension(method, args, timeoutMs) {
-  const client = firstReadyClient()
-  if (client === undefined) {
-    return Promise.reject(new Error('JLCEDA bridge extension is not connected. Open JLCEDA Pro, import dsh-eda-bridge-extension.zip, enable "Allow interactive with external", and keep a schematic or PCB page open.'))
-  }
+/** Read-only calls may be repeated on another page; a write must never be. */
+function isIdempotentRead(method) {
+  const fn = method.slice(method.lastIndexOf('.') + 1).toLowerCase()
+  return fn.startsWith('get') || fn.startsWith('is') || fn.startsWith('has') || fn.startsWith('list') || fn.startsWith('search')
+}
+
+function sendToClient(client, method, args, timeoutMs) {
   const id = nextCallId++
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -470,6 +504,27 @@ function callExtension(method, args, timeoutMs) {
   })
 }
 
+async function callExtension(method, args, timeoutMs) {
+  const pool = pickClients()
+  if (pool.length === 0) {
+    throw new Error('JLCEDA bridge extension is not connected. Open JLCEDA Pro, import dsh-eda-bridge-extension-' + VERSION + '.zip, enable "Allow interactive with external", and keep a schematic or PCB page open.')
+  }
+  const deadline = Date.now() + timeoutMs
+  let lastError
+  for (const client of pool) {
+    const remaining = deadline - Date.now()
+    if (remaining <= 100) break
+    try {
+      return await sendToClient(client, method, args, remaining)
+    } catch (error) {
+      lastError = error
+      // A different error means the page answered; retrying would only repeat it.
+      if (!isIdempotentRead(method) || !/timed out/.test(String((error as Error)?.message))) throw error
+    }
+  }
+  throw lastError ?? new Error('JLCEDA bridge call timed out after ' + timeoutMs + 'ms: ' + method)
+}
+
 function asRecord(value) {
   if (value === null || typeof value !== 'object') return {}
   return value
@@ -773,6 +828,86 @@ async function auditPcb(args, timeoutMs) {
   }
 }
 
+/**
+ * Real probe for `resolveExecutable`: filesystem existence plus `reg query`.
+ * Kept separate from the pure resolver so the resolution order stays testable.
+ */
+function launchProbe() {
+  const cache = new Map()
+  return {
+    platform: process.platform,
+    env: process.env,
+    exists(path) {
+      try { return statSync(path).isFile() } catch { return false }
+    },
+    registryQuery(key, valueName) {
+      if (process.platform !== 'win32') return undefined
+      // `undefined` (list every value) and `''` (the default value) are different
+      // queries and must not share a cache entry.
+      const cacheKey = key + '|' + (valueName === undefined ? 'LIST' : (valueName === '' ? 'DEFAULT' : 'V:' + valueName))
+      if (cache.has(cacheKey)) return cache.get(cacheKey)
+      let output
+      try {
+        // `reg query <key>` alone prints only the default value, so listing a key
+        // (valueName undefined) needs `/s`; a single value uses `/v`, and the
+        // default value uses `/ve`.
+        const extra = valueName === undefined ? ['/s'] : (valueName === '' ? ['/ve'] : ['/v', valueName])
+        const raw = execFileSync('reg', ['query', key, ...extra], {
+          timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        output = decodeRegistryOutput(raw)
+      } catch {
+        output = undefined
+      }
+      cache.set(cacheKey, output)
+      return output
+    },
+  }
+}
+
+/** How many processes currently run that image name (Windows tasklist). */
+function processCountByName(imageName) {
+  if (process.platform !== 'win32') {
+    // pgrep exits non-zero when nothing matches, which is the "closed" case.
+    try {
+      const out = execFileSync('pgrep', ['-f', imageName], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
+      return out.split(/\r?\n/).filter(line => line.trim() !== '').length
+    } catch {
+      return 0
+    }
+  }
+  try {
+    const out = execFileSync('tasklist', ['/FI', 'IMAGENAME eq ' + imageName, '/FO', 'CSV', '/NH'], {
+      encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return out.split(/\r?\n/).filter(line => line.trim().startsWith('"')).length
+  } catch {
+    return 0
+  }
+}
+
+/** Ask the app to close (/T closes the renderer children too); force kills it. */
+function terminateByName(imageName, force) {
+  if (process.platform === 'win32') {
+    execFileSync('taskkill', ['/IM', imageName, '/T'].concat(force ? ['/F'] : []), {
+      timeout: 10000, stdio: ['ignore', 'ignore', 'ignore'],
+    })
+    return
+  }
+  execFileSync('pkill', [force ? '-9' : '-TERM', '-f', imageName], { timeout: 10000, stdio: ['ignore', 'ignore', 'ignore'] })
+}
+
+/** Wait (bounded) until at least one EDA extension reports ready. */
+async function waitForExtensionConnection(timeoutMs) {
+  const started = Date.now()
+  const readyCount = () => pickClients().length
+  while (Date.now() - started < timeoutMs) {
+    if (readyCount() > 0) return { connected: true, clients: readyCount(), waitedMs: Date.now() - started }
+    await new Promise(resolve => setTimeout(resolve, 500))
+  }
+  return { connected: false, clients: readyCount(), waitedMs: Date.now() - started }
+}
+
 async function clearRoutingBatched(args, type, timeoutMs) {
   if (type === 'connection') throw new Error('eda_pcb_clear_routing: type=connection needs the EDA user interface; use type=all/net with mode=batched')
   const net = args.net === undefined ? undefined : String(args.net)
@@ -877,28 +1012,457 @@ function pickDefined(source, keys) {
   return out
 }
 
+/** Resolve a project uuid from { uuid } or { name } (exact match first, then case-insensitive substring). */
+async function resolveProjectUuid(args, timeoutMs) {
+  const direct = args.uuid === undefined ? '' : String(args.uuid).trim()
+  if (direct !== '') return { uuid: direct, matched: null }
+  const name = args.name === undefined ? '' : String(args.name).trim()
+  if (name === '') throw new Error('provide uuid or name')
+  const unfiltered = await callExtension('dmt_Project.getAllProjectsUuid', [], toolTimeout(args, timeoutMs))
+  const candidates = Array.isArray(unfiltered) ? unfiltered.map(String) : []
+  // Local directories are modelled as teams, so an unfiltered listing is empty;
+  // collect every team's projects before giving up on the name.
+  if (candidates.length === 0) {
+    const teams = await callExtension('dmt_Team.getAllTeamsInfo', [], toolTimeout(args, timeoutMs)).catch(() => [])
+    const seen = new Set()
+    for (const team of Array.isArray(teams) ? teams : []) {
+      const teamUuid = String(pickValue(asRecord(team), 'uuid', 'Uuid') ?? '')
+      if (teamUuid === '') continue
+      const owned = await callExtension('dmt_Project.getAllProjectsUuid', [teamUuid], toolTimeout(args, timeoutMs)).catch(() => [])
+      for (const uuid of Array.isArray(owned) ? owned.map(String) : []) {
+        if (seen.has(uuid)) continue
+        seen.add(uuid)
+        candidates.push(uuid)
+      }
+    }
+  }
+  const resolved = []
+  for (const candidate of candidates) {
+    try {
+      const info = asRecord(await callExtension('dmt_Project.getProjectInfo', [candidate], toolTimeout(args, timeoutMs)))
+      resolved.push({ uuid: candidate, friendly: String(pickValue(info, 'FriendlyName', 'friendlyName', 'Name', 'name') ?? '') })
+    } catch {
+      resolved.push({ uuid: candidate, friendly: '' })
+    }
+  }
+  const matched = resolved.find(item => item.friendly === name)
+    ?? resolved.find(item => item.friendly.toLowerCase().includes(name.toLowerCase()))
+    ?? null
+  if (matched === null) {
+    throw new Error('no project matches "' + name + '"; known names: ' +
+      resolved.map(item => item.friendly || item.uuid).slice(0, 20).join(', '))
+  }
+  return { uuid: matched.uuid, matched }
+}
+
 async function executeTool(name, rawArgs, timeoutMs) {
   const args = asRecord(rawArgs)
   const tool = PCB_TOOL_ALIASES[name] ?? name
 
   switch (tool) {
     case 'eda_status': {
-      const ready = [...clients].filter(client => client.ready)
-      const extensionVersion = ready.map(client => client.extensionVersion).find(value => typeof value === 'string')
+      const ready = pickClients()
+      // Every EDA page keeps its own socket, so several clients can disagree: list
+      // them all and judge the bridge as outdated when ANY of them is not on VERSION.
+      const versions = ready.map(client => (typeof client.extensionVersion === 'string' ? client.extensionVersion : null))
+      const extensionVersion = versions.find(value => typeof value === 'string') ?? null
+      const stale = versions.filter(value => value !== VERSION)
       return {
         ok: true, bridgeVersion: VERSION, wsPort: WS_PORT, allowRawApi: ALLOW_RAW_API,
         connectedClients: ready.length,
         extensionVersion: extensionVersion ?? null,
-        versionMismatch: typeof extensionVersion === 'string' && extensionVersion !== VERSION,
+        extensionVersions: versions,
+        versionMismatch: stale.length > 0,
         mcpUnits: '0.01 inch', defaultPaper: DEFAULT_PAPER,
         hint: ready.length === 0
-          ? 'No JLCEDA extension is connected. Open JLCEDA Pro and click DSH MCP -> connect, or re-import dsh-eda-bridge-extension.zip.'
-          : (typeof extensionVersion === 'string' && extensionVersion !== VERSION
-            ? 'The connected EDA extension version differs from the bridge version. Re-import dsh-eda-bridge-extension.zip and restart JLCEDA Pro.'
+          ? 'No JLCEDA extension is connected. Open JLCEDA Pro and click DSH MCP -> connect, or re-import dsh-eda-bridge-extension-' + VERSION + '.zip.'
+          : (stale.length > 0
+            ? 'Connected EDA extension ' + stale.join(', ') + ' does not match bridge ' + VERSION +
+              '. In JLCEDA Pro remove the OLD dsh-eda-bridge extension first, import dsh-eda-bridge-extension-' + VERSION + '.zip again, then restart the app; a simple reload keeps the old copy.'
             : 'ok'),
       }
     }
 
+    case 'eda_close_document':
+      return await callExtension('dmt_EditorControl.closeDocument', [String(args.tabId ?? '')], timeoutMs)
+
+    case 'eda_export_project': {
+      const result = await callExtension('dsh.internal.exportProjectFile', [
+        args.uuid === undefined ? null : String(args.uuid),
+        args.fileName === undefined ? undefined : String(args.fileName),
+        undefined,
+        args.fileType === undefined ? undefined : String(args.fileType),
+      ], toolTimeout(args, timeoutMs))
+      const base64 = typeof result?.base64 === 'string' ? result.base64 : ''
+      const outPath = args.outPath === undefined ? '' : String(args.outPath).trim()
+      if (outPath !== '') {
+        await writeFile(outPath, Buffer.from(base64, 'base64'))
+        return { ok: true, written: outPath, name: result?.name ?? null, size: base64 === '' ? 0 : Buffer.from(base64, 'base64').length }
+      }
+      if (args.inline !== true) {
+        return { ok: true, name: result?.name ?? null, base64Length: base64.length, hint: 'Pass outPath to write the file, or inline=true to receive the base64 payload.' }
+      }
+      return { ok: true, name: result?.name ?? null, base64 }
+    }
+
+    case 'eda_import_project': {
+      const path = String(args.path ?? '').trim()
+      if (path === '') throw new Error('eda_import_project requires path')
+      let bytes
+      try { bytes = await readFile(path) } catch {
+        throw new Error('eda_import_project: cannot read "' + path + '"')
+      }
+      // importProjectByProjectFile only lands anything when the target team is given
+      // (saveTo); without it the app answers undefined and nothing is imported.
+      let teamUuid = args.teamUuid === undefined ? '' : String(args.teamUuid).trim()
+      if (teamUuid === '') {
+        const current = await callExtension('dmt_Team.getCurrentTeamInfo', [], timeoutMs).catch(() => undefined)
+        teamUuid = String(pickValue(asRecord(current), 'uuid', 'Uuid') ?? '')
+      }
+      if (teamUuid === '') {
+        throw new Error('eda_import_project needs teamUuid: the app imports nothing without a target team. Use a team uuid from eda_list_teams (local mode reports project directories) or the teamUuid of an existing project (eda_list_projects).')
+      }
+      const saveTo: Record<string, unknown> = { operation: 'New Project', newProjectOwnerTeamUuid: teamUuid }
+      if (args.folderUuid !== undefined) saveTo.newProjectOwnerFolderUuid = String(args.folderUuid)
+      if (args.friendlyName !== undefined) saveTo.newProjectFriendlyName = String(args.friendlyName)
+      const imported = await callExtension('dsh.internal.importProjectFile', [
+        bytes.toString('base64'),
+        basename(path),
+        args.fileType === undefined ? undefined : String(args.fileType),
+        saveTo,
+      ], toolTimeout(args, timeoutMs))
+      const raw = imported?.result ?? imported
+      const uuid = typeof raw === 'string' ? raw : (typeof raw?.uuid === 'string' ? raw.uuid : undefined)
+      const landed = raw !== null && raw !== undefined
+      let opened = false
+      if (args.open === true && uuid !== undefined) {
+        try { opened = (await callExtension('dmt_Project.openProject', [uuid], timeoutMs)) !== false } catch { opened = false }
+      }
+      return {
+        ok: landed,
+        imported: landed,
+        name: basename(path),
+        size: bytes.length,
+        teamUuid,
+        uuid: uuid ?? null,
+        opened,
+        result: raw ?? null,
+        hint: landed ? null : 'The app returned nothing: the import did not create a project. That means this build ignores the saveTo target (same limitation as createProject), so import cannot be used to create projects here.',
+      }
+    }
+
+    case 'eda_close': {
+      const resolved = resolveExecutable(launchProbe(), {
+        executable: args.executable === undefined ? undefined : String(args.executable),
+      })
+      const imageName = resolved === undefined ? 'lceda-pro.exe' : basename(resolved.executable)
+      const before = processCountByName(imageName)
+      const waitMs = Number.isFinite(Number(args.waitMs)) ? Math.max(1000, Number(args.waitMs)) : 8000
+      let error = null
+      try {
+        terminateByName(imageName, false)
+      } catch (failure) {
+        error = failure instanceof Error ? failure.message : String(failure)
+      }
+      const started = Date.now()
+      let remaining = processCountByName(imageName)
+      while (remaining > 0 && Date.now() - started < waitMs) {
+        await new Promise(resolve => setTimeout(resolve, 500))
+        remaining = processCountByName(imageName)
+      }
+      let forced = false
+      if (remaining > 0) {
+        try {
+          terminateByName(imageName, true)
+          forced = true
+          await new Promise(resolve => setTimeout(resolve, 1500))
+          remaining = processCountByName(imageName)
+        } catch (failure) {
+          error = error ?? (failure instanceof Error ? failure.message : String(failure))
+        }
+      }
+      const connected = pickClients().length
+      return {
+        ok: remaining <= 0,
+        closed: remaining <= 0,
+        forced,
+        imageName,
+        processesBefore: before,
+        processesAfter: remaining,
+        connectedClients: connected,
+        waitedMs: Date.now() - started,
+        error,
+      }
+    }
+
+    case 'eda_list_projects': {
+      // Omit the filters entirely when they are not given: the official API treats a
+      // literal null as a filter value and the call does not resolve.
+      const filters = []
+      if (args.teamUuid !== undefined) filters.push(String(args.teamUuid))
+      if (args.folderUuid !== undefined || args.workspaceUuid !== undefined) filters.push(args.folderUuid === undefined ? null : String(args.folderUuid))
+      if (args.workspaceUuid !== undefined) filters.push(String(args.workspaceUuid))
+      let uuids = await callExtension('dmt_Project.getAllProjectsUuid', filters, toolTimeout(args, timeoutMs))
+      let list = Array.isArray(uuids) ? uuids.map(String) : []
+      let aggregated = false
+      // In semi-offline mode the app models each local project directory as a
+      // "team", so an unfiltered call returns nothing; walk the teams instead.
+      if (list.length === 0 && filters.length === 0) {
+        const teams = await callExtension('dmt_Team.getAllTeamsInfo', [], toolTimeout(args, timeoutMs)).catch(() => [])
+        const seen = new Set()
+        for (const team of Array.isArray(teams) ? teams : []) {
+          const teamUuid = String(pickValue(asRecord(team), 'uuid', 'Uuid') ?? '')
+          if (teamUuid === '') continue
+          const owned = await callExtension('dmt_Project.getAllProjectsUuid', [teamUuid], toolTimeout(args, timeoutMs)).catch(() => [])
+          for (const uuid of Array.isArray(owned) ? owned.map(String) : []) {
+            if (seen.has(uuid)) continue
+            seen.add(uuid)
+            list.push(uuid)
+          }
+        }
+        aggregated = true
+      }
+      if (args.resolveNames === false) return { count: list.length, uuids: list, aggregated }
+      const limit = Number.isFinite(Number(args.limit)) ? Math.max(1, Number(args.limit)) : list.length
+      const projects = []
+      for (const uuid of list.slice(0, limit)) {
+        try {
+          // Verbatim: project records carry unstable keys and summarising them
+          // produced empty objects.
+          projects.push(await callExtension('dmt_Project.getProjectInfo', [uuid], toolTimeout(args, timeoutMs)))
+        } catch {
+          projects.push({ uuid })
+        }
+      }
+      return { count: list.length, resolved: projects.length, aggregated, projects }
+    }
+
+    case 'eda_get_project': {
+      const project = await callExtension('dmt_Project.getCurrentProjectInfo', [], timeoutMs)
+      return project === undefined || project === null
+        ? { project: null, hint: 'No project is open: JLCEDA Pro is on the HOME page. Use eda_list_projects + eda_open_project, or open one in the app.' }
+        : project
+    }
+
+    case 'eda_open_project': {
+      const resolvedProject = await resolveProjectUuid(args, timeoutMs)
+      const uuid = resolvedProject.uuid
+      const opened = await callExtension('dmt_Project.openProject', [uuid], toolTimeout(args, timeoutMs))
+      const current = await callExtension('dmt_Project.getCurrentProjectInfo', [], timeoutMs).catch(() => undefined)
+      return { opened: opened !== false, uuid, matched: resolvedProject.matched, current: current === undefined ? null : summarizePrimitive(current) }
+    }
+
+    case 'eda_get_workspace': {
+      const workspace = await callExtension('dmt_Workspace.getCurrentWorkspaceInfo', [], timeoutMs).catch(() => undefined)
+      const team = await callExtension('dmt_Team.getCurrentTeamInfo', [], timeoutMs).catch(() => undefined)
+      // Team/workspace payloads are small and their field names are unstable, so
+      // they are returned verbatim: summarising them produced empty objects.
+      return {
+        workspace: workspace === undefined ? null : workspace,
+        team: team === undefined ? null : team,
+        hint: workspace === undefined && team === undefined
+          ? 'No workspace/team is available: start JLCEDA Pro and sign in to a JLC account. Workspace projects cannot be created or listed without one.'
+          : 'ok',
+      }
+    }
+
+    case 'eda_list_teams': {
+      const teams = await callExtension(args.involved === true ? 'dmt_Team.getAllInvolvedTeamInfo' : 'dmt_Team.getAllTeamsInfo', [], toolTimeout(args, timeoutMs))
+      const list = Array.isArray(teams) ? teams : []
+      return { count: list.length, teams: list }
+    }
+
+    case 'eda_list_folders': {
+      const teamUuid = args.teamUuid === undefined ? '' : String(args.teamUuid).trim()
+      let resolvedTeam = teamUuid
+      if (resolvedTeam === '') {
+        const current = await callExtension('dmt_Team.getCurrentTeamInfo', [], timeoutMs).catch(() => undefined)
+        resolvedTeam = String(pickValue(asRecord(current), 'Uuid', 'uuid') ?? '')
+      }
+      if (resolvedTeam === '') throw new Error('eda_list_folders needs teamUuid (eda_list_teams shows them)')
+      // The app throws a bare TypeError when the team is not a real uuid (the local
+      // directories reported by eda_list_teams are paths), so say what to pass.
+      let uuids
+      try {
+        uuids = await callExtension('dmt_Folder.getAllFoldersUuid', [resolvedTeam], toolTimeout(args, timeoutMs))
+      } catch (failure) {
+        throw new Error('eda_list_folders: the app rejected team "' + resolvedTeam + '" (' +
+          (failure instanceof Error ? failure.message : String(failure)) +
+          '); pass the uuid from a project record (eda_list_projects) or eda_list_teams')
+      }
+      const list = Array.isArray(uuids) ? uuids.map(String) : []
+      if (args.resolveNames === false) return { teamUuid: resolvedTeam, count: list.length, uuids: list }
+      const folders = []
+      for (const folderUuid of list.slice(0, 20)) {
+        try {
+          folders.push({ folderUuid, info: await callExtension('dmt_Folder.getFolderInfo', [resolvedTeam, folderUuid], timeoutMs) })
+        } catch {
+          folders.push({ folderUuid, info: null })
+        }
+      }
+      return { teamUuid: resolvedTeam, count: list.length, folders }
+    }
+
+    case 'eda_delete_project': {
+      const resolvedProject = await resolveProjectUuid(args, timeoutMs)
+      const deleted = await callExtension('dmt_Project.deleteProject', [resolvedProject.uuid], toolTimeout(args, timeoutMs))
+      const ok = deleted !== false
+      return {
+        deleted: ok,
+        uuid: resolvedProject.uuid,
+        matched: resolvedProject.matched,
+        hint: ok ? null : 'The app returned false and the project still exists: this build refuses deleteProject for local projects (verified with the project open and after switching away), so remove it in the app.',
+      }
+    }
+
+    case 'eda_modify_project': {
+      const resolvedProject = await resolveProjectUuid(args, timeoutMs)
+      const changes = []
+      if (args.friendlyName !== undefined) {
+        changes.push(['friendlyName', await callExtension('dmt_Project.modifyProjectFriendlyName', [resolvedProject.uuid, String(args.friendlyName)], timeoutMs)])
+      }
+      if (args.description !== undefined) {
+        changes.push(['description', await callExtension('dmt_Project.modifyProjectDescription', [resolvedProject.uuid, String(args.description)], timeoutMs)])
+      }
+      if (changes.length === 0) throw new Error('eda_modify_project requires friendlyName or description')
+      return {
+        ok: changes.every(([, value]) => value !== false),
+        uuid: resolvedProject.uuid,
+        matched: resolvedProject.matched,
+        applied: changes.map(([field, value]) => ({ field, ok: value !== false })),
+      }
+    }
+
+    case 'eda_copy_project': {
+      const source = await resolveProjectUuid({
+        uuid: args.sourceUuid, name: args.sourceName,
+      }, timeoutMs)
+      const uuid = await callExtension('dmt_Project.copyProject', [
+        source.uuid,
+        args.targetTeamUuid === undefined ? undefined : String(args.targetTeamUuid),
+        args.targetFolderUuid === undefined ? undefined : String(args.targetFolderUuid),
+        args.newFriendlyName === undefined ? undefined : String(args.newFriendlyName),
+        args.newName === undefined ? undefined : String(args.newName),
+      ], toolTimeout(args, timeoutMs))
+      return { copied: typeof uuid === 'string' && uuid !== '', sourceUuid: source.uuid, uuid: uuid ?? null }
+    }
+
+    case 'eda_create_project': {
+      const friendlyName = String(args.friendlyName ?? '').trim()
+      if (friendlyName === '') throw new Error('eda_create_project requires friendlyName')
+      // createProject needs an owning team: default to the current one instead of
+      // passing undefined, which the app answers with an empty uuid.
+      let teamUuid = args.teamUuid === undefined ? '' : String(args.teamUuid).trim()
+      let teamSource = 'argument'
+      if (teamUuid === '') {
+        const current = await callExtension('dmt_Team.getCurrentTeamInfo', [], timeoutMs).catch(() => undefined)
+        teamUuid = String(pickValue(asRecord(current), 'Uuid', 'uuid') ?? '')
+        teamSource = teamUuid === '' ? 'unavailable' : 'current-team'
+      }
+      if (teamUuid === '') {
+        throw new Error('eda_create_project: no team is available (sign in to a JLC account in JLCEDA Pro, or pass teamUuid from eda_list_teams)')
+      }
+      const folderUuid = args.folderUuid === undefined ? '' : String(args.folderUuid).trim()
+      const uuid = await callExtension('dmt_Project.createProject', [
+        friendlyName,
+        args.name === undefined ? undefined : String(args.name),
+        teamUuid,
+        folderUuid === '' ? undefined : folderUuid,
+        args.description === undefined ? undefined : String(args.description),
+      ], toolTimeout(args, timeoutMs))
+      if (typeof uuid !== 'string' || uuid === '') {
+        throw new Error('eda_create_project: the app returned no project uuid (team ' + teamUuid + ' from ' + teamSource + '; the app may have shown a dialog or rejected the name)')
+      }
+      let opened = false
+      if (args.open === true) {
+        try {
+          opened = (await callExtension('dmt_Project.openProject', [uuid], timeoutMs)) !== false
+        } catch {
+          opened = false
+        }
+      }
+      return { created: true, uuid, friendlyName, teamUuid, teamSource, folderUuid: folderUuid === '' ? null : folderUuid, opened }
+    }
+
+    case 'eda_launch': {
+      const probe = launchProbe()
+      const resolved = resolveExecutable(probe, {
+        executable: args.executable === undefined ? undefined : String(args.executable),
+        project: args.project === undefined ? undefined : String(args.project),
+      })
+      if (resolved === undefined) {
+        throw new Error([
+          'eda_launch: could not find the JLCEDA Pro executable on this machine.',
+          'Set `DSH_EDA_EXECUTABLE` (or the plugin setting edaExecutable) to the full path of lceda-pro.exe.',
+          'Searched: DSH_EDA_EXECUTABLE / JLCEDA_EXECUTABLE, the registry handler registered for .eprj2/.eprj,',
+          'conventional install directories under Program Files / LOCALAPPDATA / the system drive, and PATH.',
+        ].join(' '))
+      }
+
+      const alreadyConnected = pickClients().length
+      const project = args.project === undefined ? undefined : String(args.project)
+      if (project !== undefined && project !== '') {
+        try { if (!statSync(project).isFile()) throw new Error('not a file') } catch {
+          throw new Error('eda_launch: project "' + project + '" does not exist or is not a file')
+        }
+      }
+
+      // On Windows a direct spawn (and even ShellExecute) makes lceda-pro.exe start
+      // and quit immediately, while the same executable works when the desktop
+      // shell launches it. Explorer runs in the interactive desktop, so the launch
+      // is handed to it through a tiny script that starts the app (with the project
+      // when given). Other platforms spawn the resolved command directly.
+      const plan = buildLaunchArgs(process.platform, resolved.executable, project)
+      let child
+      let via = 'direct'
+      if (process.platform === 'win32') {
+        try {
+          const scriptPath = join(tmpdir(), 'dsh-eda-launch-' + process.pid + '-' + Date.now() + '.cmd')
+          await writeFile(scriptPath, buildLaunchScript(resolved.executable, project), 'utf8')
+          child = spawn(process.env.SystemRoot ? join(process.env.SystemRoot, 'explorer.exe') : 'explorer.exe', [scriptPath], {
+            detached: true, stdio: 'ignore', windowsHide: false,
+          })
+          via = 'explorer'
+        } catch {
+          child = spawn(plan.command, plan.args, { detached: true, stdio: 'ignore', windowsHide: false })
+          via = 'direct'
+        }
+      } else {
+        child = spawn(plan.command, plan.args, { detached: true, stdio: 'ignore', windowsHide: false })
+      }
+      child.unref()
+
+      const shouldWait = args.waitForExtension !== false
+      const timeoutMs = Number.isFinite(Number(args.timeoutMs)) ? Math.max(1000, Number(args.timeoutMs)) : 30000
+      const waited = shouldWait
+        ? await waitForExtensionConnection(timeoutMs)
+        : { connected: alreadyConnected > 0, clients: alreadyConnected, waitedMs: 0 }
+
+      return {
+        ok: true,
+        launched: true,
+        pid: child.pid ?? null,
+        via,
+        executable: resolved.executable,
+        source: resolved.source,
+        project: project ?? null,
+        // Verified on JLCEDA Pro 3.2.186: the app starts but ignores the project
+        // argument passed on the command line (it opens on HOME), so the caller must
+        // not assume the project was opened.
+        projectOpenedByArgument: false,
+        projectNote: project === undefined || project === ''
+          ? null
+          : 'The app was started with the project path, but this JLCEDA Pro build ignores it and opens on HOME; open the project from the app itself.',
+        target: { command: plan.command, args: plan.args },
+        connected: waited.connected,
+        connectedClients: waited.clients,
+        waitedMs: waited.waitedMs,
+        hint: waited.connected
+          ? 'JLCEDA is connected; the eda_* tools can be used now.'
+          : 'The app was started but no EDA extension connected yet. In JLCEDA Pro: 扩展 → DSH MCP → 连接 (and enable “允许外部交互”); the extension must be imported once from dsh-eda-bridge-extension-' + VERSION + '.zip.',
+      }
+    }
+
     case 'eda_get_page_info': {
       const paper = paperOf(args.paper)
       let page
@@ -1418,7 +1982,7 @@ async function executeTool(name, rawArgs, timeoutMs) {
           triggered: true, backgroundUnavailable: true, importResult: result,
           componentsBefore: pcbComponentBaseline.length, componentsAfter: after.length,
           confirmedYet: after.length > pcbComponentBaseline.length,
-          hint: 'The imported EDA extension has no background-job helper, so the sync was awaited. Re-import dsh-eda-bridge-extension.zip to use the async + polling flow.',
+          hint: 'The imported EDA extension has no background-job helper, so the sync was awaited. Re-import dsh-eda-bridge-extension-' + VERSION + '.zip to use the async + polling flow.',
         }
       }
       return {
@@ -1720,7 +2284,7 @@ async function executeTool(name, rawArgs, timeoutMs) {
           // Older EDA extension without the background-job helper: fall back to the
           // blocking call (which may hit the tool timeout for large boards).
           const blocking = asRecord(await callExtension('pcb_Document.autoRouting', [props], toolTimeout(args, timeoutMs)))
-          return { ...blocking, backgroundUnavailable: true, props, hint: 'The imported EDA extension has no background-job helper, so routing was awaited. Re-import dsh-eda-bridge-extension.zip to get the async + polling flow.' }
+          return { ...blocking, backgroundUnavailable: true, props, hint: 'The imported EDA extension has no background-job helper, so routing was awaited. Re-import dsh-eda-bridge-extension-' + VERSION + '.zip to get the async + polling flow.' }
         }
         const running = started.started === true || started.alreadyRunning === true
         return {
@@ -1807,7 +2371,7 @@ const server = createServer((req, res) => {
   const url = new URL(req.url ?? '/', 'http://127.0.0.1')
   if (req.method === 'GET' && url.pathname === '/healthz') {
     res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-    res.end(JSON.stringify({ status: 'ok', version: VERSION, clients: [...clients].filter(client => client.ready).length }))
+    res.end(JSON.stringify({ status: 'ok', version: VERSION, clients: pickClients().length }))
     return
   }
   res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })