sap-ai-dev-toolkit 0.9.94 → 0.9.9903

package/src/launcher.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import { dirname, join } from 'node:path';
@@ -8,7 +9,7 @@ import { discoverDestinations, remediation, slugifyDestination, statusRows } fro
 import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix } from './local-sap-gui.mjs';
 import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
+import { configuredVersionHandoff, installMcpConfig, npxPackageLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
@@ -80,15 +81,15 @@ async function runDoctor(destinations) {
     checks.push(doctorRow('-', 'MCP config repair', 'failed', redactText(error.message || error).slice(0, 300)));
   }
   for (const destination of destinations) {
-    stopProgress.update(`Checking ${destination.name}: ADT probe, VSP startup, tools/list`);
+    stopProgress.update(`Checking ${destination.name}: ADT probe, runtime startup, tools/list`);
     const probe = destination.probe;
     const probeStatus = !probe || probe.status === 'skipped' ? 'skipped' : (probe.available === true ? 'passed' : 'failed');
     checks.push(doctorRow(destination.name, 'ADT probe', probeStatus, probe?.status || 'No BAS ADT probe was supplied; GetSystemInfo will check the route.'));
-    checks.push(doctorRow(destination.name, 'VSP binary', binary ? 'passed' : 'failed', binary ? 'installed' : binaryError));
+    checks.push(doctorRow(destination.name, 'Runtime executable', binary ? 'passed' : 'failed', binary ? 'installed' : binaryError));
     if (!binary) {
-      checks.push(doctorRow(destination.name, 'VSP MCP startup', 'skipped', 'The VSP binary is unavailable.'));
-      checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'VSP MCP startup could not run.'));
-      checks.push(doctorRow(destination.name, 'MCP tools/list', 'skipped', 'VSP MCP startup could not run.'));
+      checks.push(doctorRow(destination.name, 'MCP startup', 'skipped', 'The runtime executable is unavailable.'));
+      checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'MCP startup could not run.'));
+      checks.push(doctorRow(destination.name, 'MCP tools/list', 'skipped', 'MCP startup could not run.'));
       try { await destination.close?.(); } catch {}
       continue;
     }
@@ -97,7 +98,7 @@ async function runDoctor(destinations) {
       proxy.start();
       const initialized = await proxy.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05' } });
       if (initialized?.error) throw new Error(initialized.error.message || 'MCP initialization failed');
-      checks.push(doctorRow(destination.name, 'VSP MCP startup', 'passed', 'initialized'));
+      checks.push(doctorRow(destination.name, 'MCP startup', 'passed', 'initialized'));
       const listed = await proxy.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
       if (listed?.error) throw new Error(listed.error.message || 'MCP tools/list failed');
       const tools = listed.result?.tools || [];
@@ -108,13 +109,13 @@ async function runDoctor(destinations) {
       const localSegments = new Set(['lint_abap', 'get_application_log', 'prepare_abap_change_set', 'apply_abap_change_set', 'check_transport_readiness', 'plan_abap_cloud_migration', 'generate_rap_regression_suite', 'run_rap_regression_suite']);
       const isUpstreamTool = tool => (tool.name.startsWith(toolPrefix) ? tool.name.slice(toolPrefix.length) : tool.name);
       const upstreamCount = tools.filter(tool => !localSegments.has(isUpstreamTool(tool))).length;
-      checks.push(doctorRow(destination.name, 'MCP tools/list', upstreamCount ? 'passed' : 'failed', `${upstreamCount} VSP tools and ${tools.length} total MCP tools returned; chat-picker binding is host-managed`));
+      checks.push(doctorRow(destination.name, 'MCP tools/list', upstreamCount ? 'passed' : 'failed', `${upstreamCount} upstream tools and ${tools.length} total MCP tools returned; chat-picker binding is host-managed`));
       const systemInfo = tools.find(tool => tool.name === 'get_system_info' || tool.name === `${toolPrefix}get_system_info`);
       const needsAdtUrl = destination.probe?.status === 'needs-adt-url';
       if (needsAdtUrl) {
         checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'No ADT URL is configured for this SAP GUI system; run sap-ai-dev --setup to add one.'));
       } else if (!systemInfo) {
-        checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'GetSystemInfo is not exposed by this VSP mode.'));
+        checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'GetSystemInfo is not exposed by this runtime mode.'));
       } else {
         const inspected = await proxy.handle({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: systemInfo.name, arguments: {} } });
         const failed = inspected?.error || inspected?.result?.isError;
@@ -122,8 +123,8 @@ async function runDoctor(destinations) {
       }
     } catch (error) {
       const detail = redactText(error.message || error).slice(0, 300);
-      const initialized = checks.some(row => row.name === destination.name && row.stage === 'VSP MCP startup' && row.status === 'passed');
-      if (!initialized) checks.push(doctorRow(destination.name, 'VSP MCP startup', 'failed', detail));
+      const initialized = checks.some(row => row.name === destination.name && row.stage === 'MCP startup' && row.status === 'passed');
+      if (!initialized) checks.push(doctorRow(destination.name, 'MCP startup', 'failed', detail));
       else checks.push(doctorRow(destination.name, 'MCP tools/list', 'failed', detail));
       checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'An earlier diagnostic step failed.'));
     } finally {
@@ -178,20 +179,20 @@ async function resolveBinary() {
   const notes = [];
   const found = await findBinary(pkg, { env: runtimeEnv, log: note => notes.push(note) });
   if (found) return found;
-  logLine(`[sap-ai-dev] ${notes.join('; ') || 'no VSP binary found'}; downloading a checksum-verified copy`);
+  logLine(`[sap-ai-dev] ${notes.join('; ') || 'no runtime executable found'}; downloading a checksum-verified copy`);
   try {
     const downloaded = await downloadBinary(pkg, { env: runtimeEnv });
-    logLine(`[sap-ai-dev] VSP binary installed at ${downloaded}`);
+    logLine(`[sap-ai-dev] runtime executable installed at ${downloaded}`);
     return downloaded;
   } catch (error) {
     notes.push(`download fallback failed: ${error.message}${error.cause?.code ? ` (${error.cause.code})` : ''}`);
   }
   const npxDirectory = root.match(/^(.*[\\/]_npx[\\/][^\\/]+)[\\/]node_modules[\\/]/)?.[1];
   throw new Error([
-    `VSP binary ${binaryTarget().asset} is unavailable for ${pkg.name}@${pkg.version}: ${notes.join('; ')}.`,
+    `Runtime executable ${binaryTarget().asset} is unavailable for ${pkg.name}@${pkg.version}: ${notes.join('; ')}.`,
     npxDirectory
-      ? `The npm package ships this binary, so an interrupted install or an antivirus quarantine usually removed it: delete ${npxDirectory} and restart the MCP server so npx reinstalls the package, or set SAP_AI_DEV_TOOLKIT_BINARY to a trusted patched VSP binary.`
-      : `Reinstall ${pkg.name} (a git checkout needs npm run build:vsp), check whether antivirus quarantined the binary, or set SAP_AI_DEV_TOOLKIT_BINARY to a trusted patched VSP binary.`
+      ? `The npm package ships this binary, so an interrupted install or an antivirus quarantine usually removed it: delete ${npxDirectory} and restart the MCP server so npx reinstalls the package, or set SAP_AI_DEV_TOOLKIT_BINARY to a trusted executable.`
+      : `Reinstall ${pkg.name} (a git checkout must build its bundled runtime executable first), check whether antivirus quarantined the executable, or set SAP_AI_DEV_TOOLKIT_BINARY to a trusted executable.`
   ].join(' '));
 }
 
@@ -268,6 +269,33 @@ function noProxyEnv(env, host) {
   return { NO_PROXY: noProxy, no_proxy: noProxy };
 }
 
+// Runs a child on this process's stdio and mirrors its exit; rejects only when it cannot start.
+async function runOnOwnStdio(command, commandArgs, env) {
+  const child = spawn(command, commandArgs, { env, stdio: 'inherit' });
+  process.once('SIGINT', () => child.kill('SIGINT'));
+  process.once('SIGTERM', () => child.kill('SIGTERM'));
+  const [code, signal] = await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
+  });
+  if (signal) process.kill(process.pid, signal);
+  process.exitCode = code ?? 1;
+}
+
+// A source checkout runs as-is: its developer chose that code.
+async function handOffToConfiguredVersion() {
+  const handoff = existsSync(join(root, '.git')) ? null : configuredVersionHandoff(runtimeEnv, pkg.version);
+  if (!handoff) return false;
+  logLine(`[sap-ai-dev] sap-ai-dev-toolkit ${pkg.version} is older than ${handoff.version}, which configured this MCP entry; self-healing: handing off to sap-ai-dev-toolkit@${handoff.version} through npx. Run "npm install -g sap-ai-dev-toolkit@${handoff.version}" to update the global install.`);
+  try {
+    await runOnOwnStdio(handoff.command, handoff.args, { ...runtimeEnv, SAP_AI_DEV_TOOLKIT_HANDOFF: pkg.version });
+    return true;
+  } catch (error) {
+    logLine(`[sap-ai-dev] handoff to sap-ai-dev-toolkit@${handoff.version} could not start (${error.message}); continuing with ${pkg.version}`);
+    return false;
+  }
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -294,7 +322,7 @@ async function configuredLocalSapGuiDestination(env) {
   const adt = (sso || !tlsServerNames.length) && !hasPathPrefix(configuredUrl)
     ? await resolveLocalAdtUrl(name, configuredUrl, client)
     : { url: configuredUrl };
-  // The scan reached ADT directly, so an env proxy the browser's PAC would bypass must not reroute VSP.
+  // The scan reached ADT directly, so an env proxy the browser's PAC would bypass must not reroute the runtime.
   const direct = adt.verified ? noProxyEnv(env, new URL(adt.url).hostname) : {};
   const probe = adt.verified === undefined
     ? { status: 'configured', available: true }
@@ -312,7 +340,7 @@ async function configuredLocalSapGuiDestination(env) {
       systemId,
       authentication: 'SSO',
       ssoBrowsers,
-      // SAP_SAML_AUTH survives sanitizeChildEnv and would make VSP demand SAML credentials.
+      // SAP_SAML_AUTH survives sanitizeChildEnv and would make the runtime demand SAML credentials.
       // A first sign-in has no session a hidden browser could renew, so its window opens at once.
       childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '', SAP_SSO_FIRST_LOGIN: env.SAP_SSO_FIRST_LOGIN || 'window', SAP_SSO_SILENT_TIMEOUT: env.SAP_SSO_SILENT_TIMEOUT || '15s', ...(ssoBrowsers.length ? { SAP_BROWSER_EXEC: ssoBrowsers[0].path } : {}), ...direct },
       probe
@@ -349,6 +377,7 @@ async function main() {
     process.stdout.write(usage());
     return;
   }
+  if (!setup && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
   if (doctor && demo) throw new Error('Use either --doctor or --demo, not both.');
   if (demo) {
     await runOfflineDemo();
@@ -383,14 +412,8 @@ async function main() {
       detectAdtUrl: detectLocalAdtUrl
     };
     if (hasFlag('--npx')) {
-      // Windows has no npx.exe, so generated entries there launch through
-      // `cmd /c npx`; other platforms use npx directly.
-      const launcher = npxMcpLauncher();
-      setupOptions.install = (selected, options) => installMcpConfig(selected, {
-        ...options,
-        command: launcher.command,
-        args: [...launcher.prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
-      });
+      const launcher = npxPackageLauncher(pkg.version);
+      setupOptions.install = (selected, options) => installMcpConfig(selected, { ...options, ...launcher });
     }
     await runSetup(setupOptions);
     return;
@@ -420,7 +443,7 @@ async function main() {
     let proxy;
     try {
       const binary = await binaryOrError();
-      logLine(`[sap-ai-dev] VSP binary: ${binary}`);
+      logLine(`[sap-ai-dev] runtime executable: ${binary}`);
       proxy = new MCPProxy({ binary, destinations: [destination], env: runtimeEnv, log: logLine, version: pkg.version });
       const shutdown = signal => { void proxy.close().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143)); };
       process.once('SIGINT', () => shutdown('SIGINT'));
@@ -450,15 +473,7 @@ async function main() {
       : (/\.(?:cmd|bat)$/i.test(binary)
         ? { command: 'cmd', prefixArgs: ['/c', binary] }
         : { command: binary, prefixArgs: [] });
-    const child = spawn(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], { env: runtimeEnv, stdio: 'inherit' });
-    process.once('SIGINT', () => child.kill('SIGINT'));
-    process.once('SIGTERM', () => child.kill('SIGTERM'));
-    const [code, signal] = await new Promise((resolve, reject) => {
-      child.once('error', reject);
-      child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
-    });
-    if (signal) process.kill(process.pid, signal);
-    process.exitCode = code ?? 1;
+    await runOnOwnStdio(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], runtimeEnv);
     return;
   }
 
@@ -477,7 +492,7 @@ async function main() {
   }
   const binary = await binaryOrError();
   logLine(`[sap-ai-dev] sap-ai-dev-toolkit v${pkg.version} (node ${process.version}, pid ${process.pid})`);
-  logLine(`[sap-ai-dev] VSP binary: ${binary}`);
+  logLine(`[sap-ai-dev] runtime executable: ${binary}`);
   logLine(`[sap-ai-dev] starting MCP proxy for ${destinations.map(destination => `${destination.name} (client=${destination.client})`).join(', ')}`);
   const proxy = new MCPProxy({ binary, destinations, env: process.env, log: logLine, version: pkg.version });
   const shutdown = signal => { void proxy.close().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143)); };

package/src/local-sap-gui.mjs

@@ -164,6 +164,8 @@ function normalizeRecord(record, sourcePath) {
     authentication: ssoHintFrom(record) ? 'Basic/SSO hint' : 'Basic',
     authMode: 'basic',
     ssoHint: ssoHintFrom(record),
+    ...(record.uuid ? { serviceId: text(record.uuid).toLowerCase() } : {}),
+    ...(record.msid ? { logonGroup: text(record.logongroup || record.server || record.group) } : {}),
     proxyType: 'Internet',
     landscapePath: sourcePath,
     probe: { status: 'needs-adt-url' }
@@ -175,30 +177,53 @@ function parseLandscapeXml(content, sourcePath) {
   // Comments must not turn deleted entries into selectable systems.
   content = content.replace(/<!--[\s\S]*?-->/g, '');
   const messageServers = new Map();
-  for (const match of content.matchAll(/<Messageserver\b([^>]*)>/gi)) {
+  for (const match of content.matchAll(/<Messageserver\b((?:[^>"']|"[^"]*"|'[^']*')*)>/gi)) {
     const record = attributes(match[1]);
-    if (record.uuid) messageServers.set(record.uuid, record);
+    if (record.uuid) messageServers.set(record.uuid.toLowerCase(), record);
   }
-  for (const match of content.matchAll(/<Service\b([^>]*)\/?>(?:\s*<\/Service>)?/gi)) {
+  const services = new Map();
+  for (const match of content.matchAll(/<Service\b((?:[^>"']|"[^"]*"|'[^']*')*)\/?>(?:\s*<\/Service>)?/gi)) {
     const record = attributes(match[1]);
-    if (record.msid) {
-      const messageServer = messageServers.get(record.msid);
-      // For load-balanced entries `server` is a logon group, not a host.
-      if (!messageServer?.host) continue;
-      record.server = messageServer.host;
-      record.msport = messageServer.port;
-    }
-    const normalized = normalizeRecord(record, sourcePath);
+    if (record.uuid) services.set(record.uuid.toLowerCase(), record);
+    const normalized = normalizeLandscapeService(record, messageServers, sourcePath);
     if (normalized) records.push(normalized);
   }
-  // SAP GUI for Java files may use generic Item/Connection elements.
-  for (const match of content.matchAll(/<(?:Item|Connection)\b([^>]*)\/?>(?:\s*<\/(?:Item|Connection)>)?/gi)) {
-    const normalized = normalizeRecord(attributes(match[1]), sourcePath);
+
+  // Workspace trees organize visibility, not service definitions. Items can
+  // point at shared services, so resolve those references across all groups.
+  const referencedServiceIds = new Set();
+  for (const match of content.matchAll(/<(?:Item|Reference)\b((?:[^>"']|"[^"]*"|'[^']*')*)\/?>(?:\s*<\/(?:Item|Reference)>)?/gi)) {
+    const item = attributes(match[1]);
+    const serviceId = text(item.serviceid || item.service_id || item.link || item.ref).replace(/^#/, '').toLowerCase();
+    const referenced = serviceId ? services.get(serviceId) : null;
+    if (serviceId && !referenced) continue;
+    const record = referenced ? { ...referenced, ...item } : item;
+    if (referenced) {
+      for (const key of ['server', 'host', 'applicationserver', 'messageserver', 'mshost', 'msid', 'systemid', 'sid', 'r3name', 'type', 'kind']) {
+        if (referenced[key] && !item[key]) record[key] = referenced[key];
+      }
+      // Emit an unaliased service only once even when multiple groups include it.
+      if (!(item.name || item.description || item.desc) && referencedServiceIds.has(serviceId)) continue;
+      referencedServiceIds.add(serviceId);
+    }
+    const normalized = normalizeLandscapeService(record, messageServers, sourcePath);
     if (normalized) records.push(normalized);
   }
   return records;
 }
 
+function normalizeLandscapeService(record, messageServers, sourcePath) {
+  if (record.msid) {
+    const messageServer = messageServers.get(record.msid.toLowerCase());
+    // For load-balanced entries `server` is a logon group, not a host.
+    if (!messageServer?.host) return null;
+    record.logongroup = record.logongroup || record.server || record.group;
+    record.server = messageServer.host;
+    record.msport = messageServer.port;
+  }
+  return normalizeRecord(record, sourcePath);
+}
+
 function parseSapLogonIni(content, sourcePath) {
   const sections = new Map();
   let section = '';
@@ -390,7 +415,7 @@ export async function discoverSapGuiSystems({ env = process.env, paths } = {}) {
   if (!systems.length && !paths) systems = await parseSapGuiCandidatePaths(await broadSelfHealingSapGuiCandidates(env));
   const seen = new Set();
   return systems.filter(system => {
-    const key = `${system.name}\0${system.host}\0${system.systemId}\0${system.instance}\0${system.client}`.toLowerCase();
+    const key = `${system.serviceId || ''}\0${system.logonGroup || ''}\0${system.name}\0${system.host}\0${system.systemId}\0${system.instance}\0${system.client}`.toLowerCase();
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -412,7 +437,7 @@ export function hasExplicitPort(url) {
   return /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*:\d+(?:[/?#]|$)/i.test(String(url || '').trim());
 }
 
-// VSP appends every ADT path to the base URL, so a pasted ADT path would double up.
+// The runtime appends every ADT path to the base URL, so a pasted ADT path would double up.
 export function adtBaseUrl(url) {
   return String(url || '').trim().replace(/[?#].*$/, '').replace(/\/sap\/bc\/adt(?:\/.*)?$/i, '').replace(/\/+$/, '');
 }
@@ -432,7 +457,7 @@ function adtRank(finding) {
   return (finding.secure ? 0 : 2) + (finding.status >= 300 && finding.status < 400 ? 1 : 0);
 }
 
-// Picks the ADT URL from VSP detect's JSON, or explains why there is none.
+// Picks the ADT URL from runtime detect JSON, or explains why there is none.
 export function adtVerdict(result, protocol = 'https:') {
   const findings = Array.isArray(result?.findings) ? result.findings.filter(Boolean) : [];
   const usable = findings
@@ -452,7 +477,7 @@ export function adtVerdict(result, protocol = 'https:') {
   if (inactive) return { url: '', reason: `SAP answers at ${inactive.url} but /sap/bc/adt is not active; ask basis to activate it in SICF` };
   const tls = findings.find(finding => finding.kind === 'tls-name-mismatch');
   if (tls && /certificate required|bad certificate/i.test(String(tls.detail))) {
-    return { url: '', reason: `port ${tls.port} demands a client certificate (smart card), which VSP cannot present` };
+    return { url: '', reason: `port ${tls.port} demands a client certificate (smart card), which the runtime cannot present` };
   }
   if (tls) return { url: '', reason: `port ${tls.port} presents a certificate ${tls.certHost ? `for ${tls.certHost}` : 'this machine does not trust'}${tls.detail ? ` (${tls.detail})` : ''}` };
   const open = findings.filter(finding => ['open', 'http'].includes(finding.kind)).map(finding => finding.port);
@@ -460,7 +485,7 @@ export function adtVerdict(result, protocol = 'https:') {
   return { url: '', reason: `no port answered on ${host}` };
 }
 
-// A portless URL means 443, which on-premise ICMs rarely serve; VSP's `detect`
+// A portless URL means 443, which on-premise ICMs rarely serve; runtime `detect`
 // probes the conventional ADT ports and reports which one answers. A host that
 // accepts every port makes each probe wait out its HTTP timeouts, so the full
 // sweep gets minutes.
@@ -484,10 +509,10 @@ export async function detectAdtUrl(binary, { url, client, instance, env = proces
   } catch (error) {
     const why = error.killed ? `timed out after ${Math.round(timeoutMs / 1000)} s` : (typeof error.code === 'string' ? error.code : `exit code ${error.code}`);
     const blocked = ['EACCES', 'EPERM', 'UNKNOWN'].includes(error.code) ? '; antivirus or application control may block it' : '';
-    return { url: '', reason: `VSP detect could not run (${why}) from ${binary}${blocked}` };
+    return { url: '', reason: `Runtime detect could not run (${why}) from ${binary}${blocked}` };
   }
   try { return adtVerdict(JSON.parse(stdout), configured.protocol); }
-  catch { return { url: '', reason: 'VSP detect returned unreadable output' }; }
+  catch { return { url: '', reason: 'Runtime detect returned unreadable output' }; }
 }
 
 // Application servers appear by their SM51 names, host_SID_NN.

package/src/mcp-config.mjs

@@ -131,6 +131,26 @@ export function npxMcpLauncher(platform = process.platform) {
     : { command: 'npx', prefixArgs: [] };
 }
 
+export function npxPackageLauncher(version, platform = process.platform) {
+  const { command, prefixArgs } = npxMcpLauncher(platform);
+  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit${version ? `@${version}` : ''}`, 'sap-ai-dev'] };
+}
+
+function isOlderVersion(version, other) {
+  const parts = value => Array.from({ length: 3 }, (_, index) => Number.parseInt(String(value).split('.')[index], 10) || 0);
+  const [current, target] = [parts(version), parts(other)];
+  const index = current.findIndex((part, position) => part !== target[position]);
+  return index >= 0 && current[index] < target[index];
+}
+
+// Setup pins its version into each entry, so a stale sap-ai-dev on PATH can hand off
+// to that version through npx instead of running old code; the handoff happens once.
+export function configuredVersionHandoff(env, runningVersion, platform = process.platform) {
+  const configured = brandedEnvValue(env, 'VERSION');
+  if (!configured || brandedEnvValue(env, 'HANDOFF') || !isOlderVersion(runningVersion, configured)) return null;
+  return { version: configured, ...npxPackageLauncher(configured, platform) };
+}
+
 // Normalizes the argument list of npx-launched entries, whether written as
 // `npx ...` or the Windows `cmd /c npx ...` form; returns null when the entry
 // is not npx-launched.
@@ -150,13 +170,29 @@ function npxLaunchArgs(entry) {
 // sap-ai-dev command when it is on PATH, otherwise the pinned package
 // through npx (routed through cmd /c on Windows) so entries written by a
 // pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
+async function commandPackageVersion(command) {
+  const target = await realpath(command).catch(() => command);
+  for (const manifest of [join(dirname(dirname(target)), 'package.json'), join(dirname(command), 'node_modules', 'sap-ai-dev-toolkit', 'package.json')]) {
+    try {
+      const pkg = JSON.parse(await readFile(manifest, 'utf8'));
+      if (pkg.name === 'sap-ai-dev-toolkit') return pkg.version;
+    } catch {
+      // Try the other layout.
+    }
+  }
+  return null;
+}
+
 async function resolveLauncherInstallCommand(env) {
   const resolved = await resolveMcpServerCommand(env);
-  if (resolved !== 'sap-ai-dev') return { command: resolved, args: null };
-  const { command, prefixArgs } = npxMcpLauncher();
   const selfVersion = await runningPackageVersion();
-  const packageSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : 'sap-ai-dev-toolkit';
-  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=${packageSpec}`, 'sap-ai-dev'] };
+  let warning;
+  if (resolved !== 'sap-ai-dev') {
+    const installed = await commandPackageVersion(resolved);
+    if (installed === null || !selfVersion || installed === selfVersion) return { command: resolved, args: null };
+    warning = `${resolved} is sap-ai-dev-toolkit ${installed}, not ${selfVersion}; MCP entries start sap-ai-dev-toolkit@${selfVersion} through npx instead. Run "npm install -g sap-ai-dev-toolkit@${selfVersion}" to use the global command.`;
+  }
+  return { ...npxPackageLauncher(selfVersion), warning };
 }
 
 export async function resolveMcpConfigPath(env = process.env) {
@@ -304,7 +340,7 @@ function isPackageLauncher(entry) {
     && hasPackage(npxArgs, legacyPackages);
   // Current launchers are treated as managed only when tagged by this add-on.
   // Some early bas-mcp-addon entries were not tagged with BAS_EXT, though, and
-  // leaving them behind keeps advertising the old full VSP surface (~159 tools).
+  // leaving them behind keeps advertising the old full child tool surface (~159 tools).
   return (entry?.BAS_EXT === 'true' && (currentCommand || currentNpxLauncher || legacyCommand || legacyNpxLauncher))
     || legacyCommand
     || legacyNpxLauncher;
@@ -552,6 +588,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     options = destinationsOrOptions || {};
   }
   const env = options.env || process.env;
+  const additive = options.additive === true;
   const path = options.path || await resolveMcpConfigPath(env);
   const installWarnings = [];
   // recoverInvalid: BOM/encoding damage, VS Code JSONC comments, torn writes
@@ -576,16 +613,20 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     const resolved = await resolveLauncherInstallCommand(env);
     launcherCommand = resolved.command;
     launcherArgs = resolved.args;
+    if (resolved.warning) installWarnings.push(resolved.warning);
   }
   if (launcherCommand) {
     for (const entry of Object.values(generated)) {
       if (isCompanionServer(entry)) continue;
       entry.command = launcherCommand;
       if (launcherArgs?.length) entry.args = [...launcherArgs];
+      if (selfVersion) entry.env.SAP_AI_DEV_TOOLKIT_VERSION = selfVersion;
     }
   }
   const servers = Object.create(null);
+  const managedEntries = [];
   const managedInputIds = new Set();
+  const generatedNames = new Set(Object.keys(generated));
   for (const [name, entry] of Object.entries(config.servers)) {
     const managed = isPackageLauncher(entry)
       && typeof destinationValue(entry?.env) === 'string'
@@ -598,17 +639,38 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
         if (match) managedInputIds.add(match[1]);
       }
     }
-    if (!LEGACY_MCP_SERVER_PREFIXES.some(prefix => name.startsWith(prefix)) && !managed && !isCompanionServer(entry)) servers[name] = entry;
+    const exactManagedUpdate = managed && generatedNames.has(name)
+      && destinationValue(entry.env) === generated[name]?.env?.SAP_AI_DEV_TOOLKIT_DESTINATION
+      && destinationSource(entry.env) === generated[name]?.env?.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE;
+    if (additive && (managed || isCompanionServer(entry)) && !exactManagedUpdate) managedEntries.push([name, entry]);
+    else if (!managed && !isCompanionServer(entry) && !LEGACY_MCP_SERVER_PREFIXES.some(prefix => name.startsWith(prefix))) servers[name] = entry;
   }
+  const retainedNames = new Set(managedEntries.map(([name]) => name));
   for (const name of Object.keys(generated)) {
-    if (Object.hasOwn(servers, name)) {
-      throw new Error(`MCP server "${name}" already exists and is not managed by sap-ai-dev-toolkit`);
+    if (Object.hasOwn(servers, name) || retainedNames.has(name)) {
+      const existing = Object.hasOwn(servers, name) ? servers[name] : config.servers[name];
+      const conflict = Object.hasOwn(servers, name)
+        ? 'already exists and is not managed by sap-ai-dev-toolkit'
+        : `conflicts with a different managed destination${isCompanionServer(existing) ? ' or companion server' : ''}`;
+      throw new Error(`MCP server "${name}" ${conflict}`);
     }
   }
-  config.servers = { ...servers, ...generated };
+  config.servers = { ...servers, ...Object.fromEntries(managedEntries), ...generated };
   if (generatedInputs.size || managedInputIds.size) {
-    const existingInputs = Array.isArray(config.inputs) ? config.inputs.filter(input => !generatedInputs.has(input?.id) && !managedInputIds.has(input?.id)) : [];
-    config.inputs = [...existingInputs, ...generatedInputs.values()];
+    const retainedInputIds = new Set();
+    if (additive) {
+      for (const [, entry] of managedEntries) {
+        for (const value of Object.values(entry.env || {})) {
+          const match = typeof value === 'string' ? value.match(/^\$\{input:([^}]+)}$/) : null;
+          if (match) retainedInputIds.add(match[1]);
+        }
+      }
+    }
+    const existingInputs = Array.isArray(config.inputs) ? config.inputs.filter(input =>
+      !managedInputIds.has(input?.id) || retainedInputIds.has(input?.id)) : [];
+    const inputsById = new Map(existingInputs.map(input => [input?.id, input]));
+    for (const [id, input] of generatedInputs) inputsById.set(id, input);
+    config.inputs = [...inputsById.values()];
   }
   await writeConfig(path, config);
   return { path, servers: generated, warnings: installWarnings };