sap-ai-dev-toolkit 0.9.8 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",

package/scripts/postinstall.mjs

@@ -3,6 +3,7 @@ import { closeSync, openSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { installBinary } from '../src/binary.mjs';
+import { detectAdtUrl } from '../src/local-sap-gui.mjs';
 import { runSetup } from '../src/setup.mjs';
 import { installUserAssetsForHarnesses } from '../src/install-user-assets.mjs';
 import { installMcpServersForHarnesses } from '../src/harness-mcp-config.mjs';
@@ -76,8 +77,9 @@ async function withInstallTerminal(action) {
   }
 }
 
-async function runInstallSetup() {
-  return withInstallTerminal(terminal => runSetup({ env: runtimeEnv, ...(terminal || {}) }));
+async function runInstallSetup(binary) {
+  const detect = binary ? target => detectAdtUrl(binary, { ...target, env: runtimeEnv }) : undefined;
+  return withInstallTerminal(terminal => runSetup({ env: runtimeEnv, ...(terminal || {}), detectAdtUrl: detect }));
 }
 
 function harnessSelectionLabels(ids) {
@@ -300,15 +302,16 @@ async function main() {
   // runs `go` (only the repository-only build:vsp script does), so a toolchain
   // download at install time was pure cost. The pinned, checksum-verified VSP
   // binary ships with the package; the download below is the fallback.
+  let binary = brandedEnvValue(runtimeEnv, 'BINARY');
   try {
-    if (brandedEnvValue(runtimeEnv, 'BINARY')) {
+    if (binary) {
       await announce('Using the SAP_AI_DEV_TOOLKIT_BINARY override.', 'info');
     } else {
       // The bundled binary resolves in milliseconds; the animation only
       // appears when provisioning actually takes time (download fallback).
       const stopBinaryProgress = startProgress('Preparing the pinned VSP runtime for this platform', { output: process.stderr, env: runtimeEnv });
       try {
-        await installBinary(pkg, { env: runtimeEnv });
+        binary = await installBinary(pkg, { env: runtimeEnv });
         stopBinaryProgress();
         await announce('Pinned VSP binary installed and ready.', 'success');
       } catch (error) {
@@ -326,7 +329,7 @@ async function main() {
   let setupResult;
   let setupCompleted = false;
   try {
-    setupResult = await runInstallSetup();
+    setupResult = await runInstallSetup(binary);
     setupCompleted = true;
   } catch (error) {
     await announce(`BAS MCP setup failed: ${error.message}`, 'error');

package/src/launcher.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDestinations, remediation, slugifyDestination, statusRows } from './bas-discovery.mjs';
-import { detectAdtUrl, discoverSapGuiSystems, hasExplicitPort } from './local-sap-gui.mjs';
-import { binaryTarget, downloadBinary, findBinary } from './binary.mjs';
+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 { runSetup } from './setup.mjs';
@@ -165,7 +166,14 @@ function probeDiagnostic(destination) {
 
 // npx MCP entries run with --ignore-scripts, so postinstall's verified
 // download fallback never ran; a missing or corrupt bundled binary heals here.
-async function binaryOrError() {
+// Port detection and the server share one resolution, so a failed download is not repeated.
+let binaryResolution;
+function binaryOrError() {
+  binaryResolution ??= resolveBinary();
+  return binaryResolution;
+}
+
+async function resolveBinary() {
   const notes = [];
   const found = await findBinary(pkg, { env: runtimeEnv, log: note => notes.push(note) });
   if (found) return found;
@@ -190,6 +198,68 @@ async function detectLocalAdtUrl(target) {
   return detectAdtUrl(await binaryOrError(), { ...target, env: runtimeEnv });
 }
 
+const adtUrlCachePath = () => join(cacheDirectory(runtimeEnv), 'adt-urls.json');
+
+async function cachedAdtUrls() {
+  try { return JSON.parse(await readFile(adtUrlCachePath(), 'utf8')) || {}; }
+  catch { return {}; }
+}
+
+async function rememberAdtUrl(configured, found) {
+  try {
+    const path = adtUrlCachePath();
+    const urls = { ...await cachedAdtUrls(), [configured.toLowerCase()]: found };
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(urls, null, 2)}\n`);
+    await rename(temporary, path);
+  } catch {
+    // The cache only saves a later scan.
+  }
+}
+
+// A named port gets one probe, a scan result is remembered, and every port is
+// swept only when the configuration never named one.
+async function resolveLocalAdtUrl(name, configured, client) {
+  const log = message => logLine(`[sap-ai-dev] ${name}: ${message}`);
+  const detect = target => detectLocalAdtUrl({ client, ...target }).catch(error => ({ url: '', reason: error.message, failed: true }));
+  const explicit = hasExplicitPort(configured);
+  let verdict = { url: '', reason: '' };
+  if (explicit) {
+    verdict = await detect({ url: configured, ports: [adtPort(configured)] });
+    if (verdict.url) return { url: verdict.url, verified: true };
+    log(`ADT did not answer at ${configured}: ${verdict.reason}`);
+    if (verdict.unresolved || verdict.failed) return { url: configured, verified: false, reason: verdict.reason };
+  }
+  const remembered = (await cachedAdtUrls())[configured.toLowerCase()];
+  if (remembered) {
+    const recheck = await detect({ url: remembered, ports: [adtPort(remembered)] });
+    if (recheck.url) {
+      log(`ADT answers at ${recheck.url} (found by an earlier port scan)`);
+      return { url: recheck.url, verified: true };
+    }
+  }
+  const host = new URL(configured).hostname;
+  log(`port scan in progress on ${host} (usual ADT ports)`);
+  verdict = await detect({ url: configured });
+  if (!verdict.url && !explicit && !verdict.unresolved && !verdict.failed) {
+    log(`no ADT port on the usual ports (${verdict.reason}); port scan in progress on every conventional SAP port of ${host} (can take a minute)`);
+    verdict = await detect({ url: configured, exhaustive: true });
+  }
+  if (verdict.url) {
+    log(`port scan finished; ADT answers at ${verdict.url}`);
+    await rememberAdtUrl(configured, verdict.url);
+    return { url: verdict.url, verified: true };
+  }
+  log(`port scan finished; ${verdict.reason}; keeping ${configured}. Add the ADT port to SAP_URL or rerun sap-ai-dev --setup.`);
+  return { url: configured, verified: false, reason: verdict.reason };
+}
+
+function noProxyEnv(env, host) {
+  const noProxy = [env.NO_PROXY || env.no_proxy, host].filter(Boolean).join(',');
+  return { NO_PROXY: noProxy, no_proxy: noProxy };
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -206,56 +276,54 @@ async function configuredLocalSapGuiDestination(env) {
   if (!env.SAP_URL) throw new Error('SAP_URL is required for local SAP GUI MCP entries. Rerun sap-ai-dev --setup and enter the ADT URL.');
   const client = env.SAP_CLIENT || '001';
   const systemId = env.SAP_SYSTEM_ID || '';
+  const configuredUrl = adtBaseUrl(env.SAP_URL);
   // Older entries used windows-sso, browser-saml or saml-password; all of them now mean browser SSO.
-  if (!['', 'basic'].includes(String(env.SAP_AUTH_MODE || '').toLowerCase())) {
-    const cacheKey = `${systemId || new URL(env.SAP_URL).hostname}-${client}`.toLowerCase().replace(/[^a-z0-9.-]+/g, '-');
-    let url = env.SAP_URL;
-    // SAP GUI landscapes carry no HTTP port, and the SSO browser cannot sign in on a guessed one.
-    if (!hasExplicitPort(url)) {
-      const host = new URL(url).hostname;
-      logLine(`[sap-ai-dev] ${name}: SAP_URL has no port; port scan in progress on ${host} (usual ADT ports)`);
-      let detected = await detectLocalAdtUrl({ url, client }).catch(() => '');
-      if (!detected) {
-        logLine(`[sap-ai-dev] ${name}: no ADT port on the usual ports; port scan in progress on every conventional SAP port of ${host} (can take a minute)`);
-        detected = await detectLocalAdtUrl({ url, client, exhaustive: true }).catch(() => '');
-      }
-      logLine(detected
-        ? `[sap-ai-dev] ${name}: port scan finished; ADT answers at ${detected}`
-        : `[sap-ai-dev] ${name}: port scan finished; no ADT port answered on ${host}; add the port to SAP_URL or rerun sap-ai-dev --setup`);
-      url = detected || url;
-    }
+  const sso = !['', 'basic'].includes(String(env.SAP_AUTH_MODE || '').toLowerCase());
+  const tlsServerName = String(env.SAP_TLS_SERVER_NAME || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME || '').trim();
+  const tlsServerNames = String(env.SAP_TLS_SERVER_NAMES || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES || tlsServerName).split(',').map(value => value.trim()).filter(Boolean);
+  const tlsCaFile = String(env.SAP_TLS_CA_FILE || env.SAP_AI_DEV_TOOLKIT_TLS_CA_FILE || '').trim();
+  // SNI-routed Basic entries pin port and certificate names on purpose; SSO ignores those names.
+  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.
+  const direct = adt.verified ? noProxyEnv(env, new URL(adt.url).hostname) : {};
+  const probe = adt.verified === undefined
+    ? { status: 'configured', available: true }
+    : (adt.verified ? { status: `adt-verified at ${adt.url}`, available: true } : { status: `adt-unverified: ${adt.reason}`, available: false });
+  if (sso) {
+    const cacheKey = `${systemId || new URL(configuredUrl).hostname}-${client}`.toLowerCase().replace(/[^a-z0-9.-]+/g, '-');
+    if (isIP(new URL(adt.url).hostname.replace(/^\[(.*)\]$/, '$1'))) logLine(`[sap-ai-dev] ${name}: SSO is configured for an IP address; Kerberos and the browser certificate check need the DNS host name`);
     return {
       source: 'sap-gui-local',
       name,
-      url,
+      url: adt.url,
       client,
       systemId,
       authentication: 'SSO',
       // SAP_SAML_AUTH survives sanitizeChildEnv and would make VSP demand SAML credentials.
-      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '' },
-      probe: { status: 'configured', available: true }
+      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '', ...direct },
+      probe
     };
   }
-  const tlsServerName = String(env.SAP_TLS_SERVER_NAME || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME || '').trim();
-  const tlsServerNames = String(env.SAP_TLS_SERVER_NAMES || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES || tlsServerName).split(',').map(value => value.trim()).filter(Boolean);
-  const tlsCaFile = String(env.SAP_TLS_CA_FILE || env.SAP_AI_DEV_TOOLKIT_TLS_CA_FILE || '').trim();
   const tlsRoute = tlsServerNames.length
-    ? await createTlsServerNameAdtProxy({ destinationUrl: env.SAP_URL, tlsServerNames, caFile: tlsCaFile || undefined })
+    ? await createTlsServerNameAdtProxy({ destinationUrl: configuredUrl, tlsServerNames, caFile: tlsCaFile || undefined })
     : null;
   return {
     source: 'sap-gui-local',
     name,
-    url: tlsRoute?.url || env.SAP_URL,
-    backendUrl: tlsRoute ? env.SAP_URL : undefined,
+    url: tlsRoute?.url || adt.url,
+    backendUrl: tlsRoute ? configuredUrl : undefined,
     client,
     systemId,
     authentication: 'Basic',
     childEnv: {
       SAP_USER: env.SAP_USER || env.SAP_USERNAME || '',
-      SAP_PASSWORD: env.SAP_PASSWORD || env.SAP_PASS || ''
+      SAP_PASSWORD: env.SAP_PASSWORD || env.SAP_PASS || '',
+      ...direct
     },
     close: tlsRoute?.close,
-    probe: { status: tlsRoute ? 'configured-tls-server-name' : 'configured', available: true }
+    probe: tlsRoute ? { status: 'configured-tls-server-name', available: true } : probe
   };
 }
 

package/src/local-sap-gui.mjs

@@ -1,4 +1,5 @@
 import { platform, homedir } from 'node:os';
+import { isIP } from 'node:net';
 import { promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -149,6 +150,8 @@ function normalizeRecord(record, sourcePath) {
   const port = endpoint ? Number(endpoint[2]) : 0;
   const instance = instanceFrom(record) || (port >= 3200 && port <= 3299 ? String(port - 3200).padStart(2, '0') : '');
   const client = text(record.client || record.sapclient) || '001';
+  // A load-balanced entry names the message server, whose port is 3600 + its instance.
+  const messageServerPort = text(record.msport).match(/^36(\d{2})$/);
   return {
     source: 'sap-gui-local',
     name,
@@ -157,6 +160,7 @@ function normalizeRecord(record, sourcePath) {
     systemId,
     instance,
     client,
+    ...(messageServerPort ? { messageServer: { host, httpPort: 8100 + Number(messageServerPort[1]) } } : {}),
     authentication: ssoHintFrom(record) ? 'Basic/SSO hint' : 'Basic',
     authMode: 'basic',
     ssoHint: ssoHintFrom(record),
@@ -182,6 +186,7 @@ function parseLandscapeXml(content, sourcePath) {
       // 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 (normalized) records.push(normalized);
@@ -407,25 +412,110 @@ 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.
+export function adtBaseUrl(url) {
+  return String(url || '').trim().replace(/[?#].*$/, '').replace(/\/sap\/bc\/adt(?:\/.*)?$/i, '').replace(/\/+$/, '');
+}
+
+// A gateway path prefix cannot be probed by host and port alone.
+export function hasPathPrefix(url) {
+  return /^[a-z][a-z0-9+.-]*:\/\/[^/?#]+\/[^?#]/i.test(adtBaseUrl(url));
+}
+
+export function adtPort(url) {
+  const parsed = new URL(url);
+  return Number(parsed.port) || (parsed.protocol === 'http:' ? 80 : 443);
+}
+
+// A redirect proves less than a 401 or 200: a gateway can redirect every path.
+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.
+export function adtVerdict(result, protocol = 'https:') {
+  const findings = Array.isArray(result?.findings) ? result.findings.filter(Boolean) : [];
+  const usable = findings
+    .filter(finding => finding.kind === 'adt' && /^https?:\/\//i.test(String(finding.url || '')) && (finding.secure || protocol === 'http:'))
+    .sort((left, right) => adtRank(left) - adtRank(right));
+  if (usable.length) return { url: usable[0].url, reason: '' };
+  const host = result?.host || 'the host';
+  const unsearched = Array.isArray(result?.unsearched) ? result.unsearched[0] : undefined;
+  if (unsearched) {
+    const unresolved = /does not resolve/i.test(String(unsearched.reason));
+    return { url: '', unresolved, reason: unresolved ? `${unsearched.object} does not resolve; connect to the company network or VPN` : `${unsearched.object}: ${unsearched.reason}` };
+  }
+  const plain = findings.find(finding => finding.kind === 'adt');
+  // The SSO session cookie is the whole credential; https is never traded for http silently.
+  if (plain) return { url: '', reason: `only plain HTTP answers ADT (${plain.url}); enter it explicitly to accept an unencrypted connection` };
+  const inactive = findings.find(finding => finding.kind === 'sap-without-adt');
+  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` };
+  }
+  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);
+  if (open.length) return { url: '', reason: `${open.length === 1 ? `port ${open[0]} on ${host} accepts` : `ports ${open.join(', ')} on ${host} accept`} connections but none answered as ADT` };
+  return { url: '', reason: `no port answered on ${host}` };
+}
+
 // A portless URL means 443, which on-premise ICMs rarely serve; VSP's `detect`
 // probes the conventional ADT ports and reports which one answers.
-export async function detectAdtUrl(binary, { url, client, env = process.env, exhaustive = false, ports = [], timeoutMs = 180_000 } = {}) {
+export async function detectAdtUrl(binary, { url, client, instance, env = process.env, exhaustive = false, ports = [], timeoutMs = 180_000 } = {}) {
   let configured;
-  try { configured = new URL(url); } catch { return ''; }
+  try { configured = new URL(url); } catch { return { url: '', reason: `${url} is not a valid URL` }; }
   const host = configured.hostname.replace(/^\[(.*)\]$/, '$1');
-  const args = ['detect', host, '--json', ...(client ? ['--client', String(client)] : []), ...(exhaustive ? ['--all'] : []), ...ports.flatMap(port => ['--port', String(port)])];
+  const args = ['detect', host, '--json',
+    ...(client ? ['--client', String(client)] : []),
+    ...(/^\d{2}$/.test(String(instance || '')) ? ['--instance', String(instance)] : []),
+    ...(exhaustive ? ['--all'] : []),
+    ...ports.flatMap(port => ['--port', String(port)])];
   // A corporate HTTPS_PROXY rarely routes internal SAP hosts; probe them directly.
   const noProxy = [env.NO_PROXY || env.no_proxy, host].filter(Boolean).join(',');
-  env = { ...env, NO_PROXY: noProxy, no_proxy: noProxy };
   const [command, ...prefixArgs] = /\.(?:mjs|cjs|js)$/i.test(binary)
     ? [process.execPath, binary]
     : (/\.(?:cmd|bat)$/i.test(binary) && platform() === 'win32' ? ['cmd', '/c', binary] : [binary]);
+  let stdout;
   try {
-    const { stdout } = await execFileAsync(command, [...prefixArgs, ...args], { env, windowsHide: true, timeout: timeoutMs, maxBuffer: 1024 * 1024 });
-    const adt = (JSON.parse(stdout)?.findings || []).filter(finding => finding?.kind === 'adt' && /^https?:\/\//i.test(String(finding.url || '')));
-    // The SSO session cookie is the whole credential; never trade https for http.
-    return (adt.find(finding => finding.secure) || (configured.protocol === 'http:' ? adt[0] : undefined))?.url || '';
-  } catch {
-    return '';
+    ({ stdout } = await execFileAsync(command, [...prefixArgs, ...args], { env: { ...env, NO_PROXY: noProxy, no_proxy: noProxy }, windowsHide: true, timeout: timeoutMs, maxBuffer: 1024 * 1024 }));
+  } 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}` };
   }
+  try { return adtVerdict(JSON.parse(stdout), configured.protocol); }
+  catch { return { url: '', reason: 'VSP detect returned unreadable output' }; }
+}
+
+// Application servers appear by their SM51 names, host_SID_NN.
+export function parseMessageServerServers(body, { host = '', systemId = '' } = {}) {
+  const domain = isIP(host) ? '' : (/^[^.]+\.(.+)$/.exec(host)?.[1] || '');
+  const servers = new Map();
+  for (const [, name, sid, instance] of String(body).matchAll(/\b([A-Za-z0-9][A-Za-z0-9.-]*)_([A-Za-z][A-Za-z0-9]{2})_(\d{2})\b/g)) {
+    if (systemId && sid.toUpperCase() !== systemId.toUpperCase()) continue;
+    const appHost = name.includes('.') || !domain ? name : `${name}.${domain}`;
+    servers.set(`${appHost.toLowerCase()}:${instance}`, { host: appHost, instance });
+  }
+  return [...servers.values()];
+}
+
+// A load-balanced landscape entry names the message server, which serves no
+// ADT; its HTTP port lists the application servers that do, the same source
+// SAP Web Dispatcher reads.
+export async function messageServerAppServers({ host, httpPort, systemId } = {}, { timeoutMs = 5000 } = {}) {
+  if (!host || !httpPort) return [];
+  const authority = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  for (const path of ['/msgserver/text/logon', '/msgserver/text/serverlist']) {
+    let body = '';
+    try {
+      const response = await fetch(`http://${authority}:${httpPort}${path}`, { signal: AbortSignal.timeout(timeoutMs) });
+      if (response.ok) body = await response.text();
+    } catch {
+      continue;
+    }
+    const servers = parseMessageServerServers(body, { host, systemId });
+    if (servers.length) return servers;
+  }
+  return [];
 }

package/src/setup.mjs

@@ -4,7 +4,7 @@ import { platform } from 'node:os';
 import { isIP } from 'node:net';
 import { checkboxPrompt, colorText, formatStatus, selectPrompt, startProgress, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
-import { defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort } from './local-sap-gui.mjs';
+import { adtBaseUrl, adtPort, defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix, messageServerAppServers } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
 import { SAP_DEVELOPMENT_MCP_SERVERS, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, resolveMcpConfigPath } from './mcp-config.mjs';
 import { discoverCertificateDnsNames } from './tls-adt-proxy.mjs';
@@ -124,41 +124,96 @@ function localAuthenticationLabel(authMode) {
   return authMode === 'sso' ? 'SSO' : 'Basic';
 }
 
-// The SSO browser signs in on the ADT URL itself, and SAP GUI landscapes never
-// carry the HTTP port, so a portless URL would send it to 443.
-async function detectSsoAdtPort(destination, label, client, { input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
-  if (!detectAdtUrl || hasExplicitPort(destination.url)) return;
-  const scan = async (message, options) => {
-    const stopProgress = startProgress(message, { output, env, label: 'SSO' });
-    try { return await detectAdtUrl({ url: destination.url, client, ...options }); }
-    catch { return ''; }
+// Ports typed at the prompt are range-checked before anything parses them as a URL.
+export function adtCandidate(answer, baseUrl) {
+  const value = String(answer || '').trim();
+  if (/^\d+$/.test(value)) {
+    const port = Number(value);
+    if (port < 1 || port > 65535) throw new Error('Enter a port between 1 and 65535, or a full URL.');
+    const base = new URL(baseUrl);
+    return `${base.protocol}//${base.hostname}:${port}`;
+  }
+  const validation = validateAdtUrlCandidate(value);
+  if (validation !== true) throw new Error(validation);
+  return adtBaseUrl(value);
+}
+
+// Cheapest evidence first: named ports get one probe, then the host's usual
+// ports, then the message server's application servers, then every port.
+async function findAdtUrl(destination, label, client, { candidates = [], scan = true, output = stdout, env = process.env, detectAdtUrl } = {}) {
+  const detect = async (message, target) => {
+    print(output, formatStatus(message, 'progress', output, 'ADT'));
+    const stopProgress = startProgress(message, { output, env, label: 'ADT' });
+    try { return await detectAdtUrl({ client, ...target }); }
+    catch (error) { return { url: '', reason: error.message }; }
     finally { stopProgress(); }
   };
-  print(output, formatStatus(`Port scan in progress on ${new URL(destination.url).hostname} to find the ADT port for ${label}.`, 'progress', output, 'SSO'));
-  let detected = await scan(`Detecting the ADT port for ${label}`, {});
-  if (!detected) {
-    print(output, formatStatus(`No ADT port answered on the usual ports for ${label}; port scan in progress on every conventional SAP port (this can take a minute).`, 'progress', output, 'SSO'));
-    detected = await scan(`Sweeping SAP HTTP(S) ports for ${label}`, { exhaustive: true });
+  let verdict = { url: '', reason: `no port was checked for ${label}` };
+  for (const candidate of [...new Set([destination.url, ...candidates].filter(url => url && hasExplicitPort(url)))]) {
+    verdict = await detect(`Checking ADT at ${candidate}`, { url: candidate, ports: [adtPort(candidate)] });
+    if (verdict.url || verdict.unresolved) return verdict;
   }
-  // Nothing on the machine knows the port, so the person who does is asked until one answers.
-  while (!detected) {
-    const host = new URL(destination.url).hostname;
-    print(output, formatStatus(`No ADT port answered on ${host}. Ask basis or check SMICM (Goto > Services) for the HTTPS port.`, 'warning', output, 'SSO'));
-    const answer = String(await textPrompt({
-      message: `ADT port or URL for ${label}`,
-      placeholder: '44300 or https://host:44300',
-      validate: value => /^\d{2,5}$/.test(String(value).trim()) || validateAdtUrlCandidate(String(value).trim())
-    }, { input, output })).trim();
-    const candidate = /^\d+$/.test(answer) ? `${new URL(destination.url).origin}:${answer}` : answer;
-    const port = Number(new URL(candidate).port || (candidate.startsWith('http:') ? 80 : 443));
-    detected = await detectAdtUrl({ url: candidate, client, ports: [port] }).catch(() => '');
-    if (!detected && await confirmPrompt(`${candidate} did not answer as ADT. Use it anyway? (y/Enter=yes, n=try another)`, { input, output })) {
-      destination.url = candidate;
-      return;
+  if (!scan) return verdict;
+  const host = new URL(destination.url).hostname;
+  verdict = await detect(`Port scan in progress on ${host} to find the ADT port for ${label}`, { url: destination.url, ...(destination.instance ? { instance: destination.instance } : {}) });
+  if (verdict.url || verdict.unresolved) return verdict;
+  if (destination.messageServer) {
+    print(output, formatStatus(`Asking the message server ${destination.messageServer.host}:${destination.messageServer.httpPort} for the application servers of ${label}`, 'progress', output, 'ADT'));
+    for (const server of (await messageServerAppServers({ ...destination.messageServer, systemId: destination.systemId })).slice(0, 3)) {
+      const found = await detect(`Port scan in progress on application server ${server.host} (instance ${server.instance})`, { url: `${new URL(destination.url).protocol}//${server.host}`, instance: server.instance });
+      if (found.url) return found;
+    }
+  }
+  return detect(`No ADT port on the usual ports for ${label} (${verdict.reason}); port scan in progress on every conventional SAP port of ${host} (this can take a minute)`, { url: destination.url, exhaustive: true });
+}
+
+// An SSO sign-in can only start where ADT answers, so for SSO setup does not
+// end on an unverified URL unless the user chooses to.
+async function settleAdtUrl(destination, label, client, { insist = false, candidates = [], input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
+  if (!detectAdtUrl) return 'unchecked';
+  if (hasPathPrefix(destination.url)) {
+    print(output, formatStatus(`${destination.url} has a gateway path, so setup uses it as entered without a port scan.`, 'info', output, 'ADT'));
+    return 'unchecked';
+  }
+  const options = { candidates, output, env, detectAdtUrl };
+  let verdict = await findAdtUrl(destination, label, client, options);
+  while (!verdict.url) {
+    print(output, formatStatus(`No ADT answer for ${label}: ${verdict.reason}.`, 'warning', output, 'ADT'));
+    if (!insist) return 'unverified';
+    const choice = await selectPrompt({
+      message: `ADT for ${label}`,
+      defaultValue: 'enter',
+      choices: [
+        { name: 'Enter the ADT port or URL (basis finds it in SMICM > Goto > Services)', value: 'enter', shortcut: 'e' },
+        { name: 'Scan again, for example after connecting the VPN', value: 'retry', shortcut: 'r' },
+        { name: `Keep ${destination.url} without an ADT answer`, value: 'keep', shortcut: 'k' },
+        { name: 'Skip this system', value: 'skip', shortcut: 's' }
+      ]
+    }, { input, output });
+    if (choice === 'keep') return 'unverified';
+    if (choice === 'skip') return 'skipped';
+    if (choice === 'enter') {
+      const answer = await textPrompt({
+        message: `ADT port or URL for ${label}`,
+        placeholder: '44300 or https://host:44300',
+        validate: value => {
+          try { adtCandidate(value, destination.url); return true; }
+          catch (error) { return error.message; }
+        }
+      }, { input, output });
+      destination.url = adtCandidate(answer, destination.url);
     }
+    const retry = choice === 'retry';
+    verdict = await findAdtUrl(destination, label, client, { ...options, candidates: retry ? candidates : [], scan: retry || !hasExplicitPort(destination.url) });
   }
-  destination.url = detected;
-  print(output, formatStatus(`ADT answers at ${detected}; SSO signs in there.`, 'success', output, 'SSO'));
+  destination.url = verdict.url;
+  print(output, formatStatus(`ADT answers at ${verdict.url}.`, 'success', output, 'ADT'));
+  return 'verified';
+}
+
+function warnSsoIpHost(destination, label, output) {
+  if (!isIP(new URL(destination.url).hostname.replace(/^\[(.*)\]$/, '$1'))) return;
+  print(output, formatStatus(`${label} uses an IP address; SSO needs the DNS host name for Kerberos and the browser certificate check. Enter the host name if the sign-in fails.`, 'warning', output, 'SSO'));
 }
 
 async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
@@ -252,7 +307,7 @@ async function runManualEntryWizard({ env = process.env, input = stdin, output =
       source: 'sap-gui-local',
       name,
       serverName: name,
-      url,
+      url: adtBaseUrl(url),
       host: parsedUrl?.hostname || '',
       client: '001',
       authentication: 'Basic',
@@ -263,16 +318,21 @@ async function runManualEntryWizard({ env = process.env, input = stdin, output =
       // destination picker.
       configuredManually: true
     };
-    await maybeConfigureTlsSelfHeal(destination, name, { input, output });
     const clients = await promptSapClients(destination, { input, output });
     const authMode = await chooseLocalAuthMode(destination, { input, output, env });
-    if (authMode === 'sso') await detectSsoAdtPort(destination, name, clients[0], { input, output, env, detectAdtUrl });
-    destination.authentication = localAuthenticationLabel(authMode);
-    destination.authMode = authMode;
-    for (const client of clients) {
-      expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1 }));
+    const adt = await settleAdtUrl(destination, name, clients[0], { insist: authMode === 'sso', input, output, env, detectAdtUrl });
+    if (adt === 'skipped') {
+      print(output, formatStatus(`Skipped ${name}; no MCP server was added for it.`, 'info', output, 'Manual entry'));
+    } else {
+      if (authMode === 'sso') warnSsoIpHost(destination, name, output);
+      else await maybeConfigureTlsSelfHeal(destination, name, { input, output });
+      destination.authentication = localAuthenticationLabel(authMode);
+      destination.authMode = authMode;
+      for (const client of clients) {
+        expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1 }));
+      }
+      print(output, formatStatus(`Added ${name} (client${clients.length === 1 ? '' : 's'} ${clients.join(', ')}).`, 'success', output, 'Manual entry'));
     }
-    print(output, formatStatus(`Added ${name} (client${clients.length === 1 ? '' : 's'} ${clients.join(', ')}).`, 'success', output, 'Manual entry'));
     addAnother = await confirmPrompt('Add another system? (y/Enter=yes, n=no)', { input, output });
   }
   return expanded;
@@ -293,6 +353,18 @@ function localClientDestinationName(destination, client, { multipleClients = fal
 }
 
 
+// Two systems sharing a SID cannot be told apart, so neither URL is offered for them.
+function previousLocalAdtUrls(config) {
+  const urls = new Map();
+  for (const entry of Object.values(config?.servers || {})) {
+    const entryEnv = entry?.env || {};
+    if (entryEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE !== 'sap-gui-local' || !entryEnv.SAP_SYSTEM_ID || !entryEnv.SAP_URL) continue;
+    const key = String(entryEnv.SAP_SYSTEM_ID).toUpperCase();
+    urls.set(key, urls.has(key) && urls.get(key) !== entryEnv.SAP_URL ? '' : entryEnv.SAP_URL);
+  }
+  return urls;
+}
+
 function safeProbe(probe) {
   const result = {};
   if (typeof probe?.status === 'string') result.status = probe.status;
@@ -330,6 +402,7 @@ function safeLocalSapGuiDestination(destination) {
     proxyType: 'Internet',
     tlsServerName: destination.tlsServerName,
     tlsServerNames: destination.tlsServerNames,
+    messageServer: destination.messageServer,
     probe: safeProbe(destination.probe),
     childEnv: destination.childEnv || {}
   };
@@ -384,7 +457,7 @@ function printConnectionInstructions(output, result) {
 
 // Checkbox selection over the discovered destinations plus, outside BAS, the
 // per-system confirmation prompts (clients, ADT URL, TLS self-heal, login).
-async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
+async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin, output = stdout, env = process.env, detectAdtUrl, previousAdtUrls = new Map() } = {}) {
   const orderedDestinations = [...destinations].sort((left, right) => {
     const leftRank = left.disabledReason ? 2 : (left.probe?.available === false ? 1 : 0);
     const rightRank = right.disabledReason ? 2 : (right.probe?.available === false ? 1 : 0);
@@ -446,17 +519,24 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
       const discriminator = duplicateSystemName ? localSystemDiscriminator(destination) : '';
       const promptLabel = discriminator ? `${destination.name} (${discriminator})` : destination.name;
       const clients = await promptSapClients({ ...destination, name: promptLabel }, { input, output });
-      const fallback = defaultAdtUrl(destination);
+      const guess = defaultAdtUrl(destination);
+      // A URL an earlier setup verified beats the 443NN naming convention.
+      const fallback = previousAdtUrls.get(String(destination.systemId || '').toUpperCase()) || guess;
       const url = await textPrompt({
         message: `ADT URL for ${promptLabel}`,
         placeholder: fallback || 'https://host:44300',
         validate: value => validateAdtUrlCandidate(value || fallback),
         required: false
       }, { input, output });
-      destination.url = url || fallback;
-      await maybeConfigureTlsSelfHeal(destination, promptLabel, { input, output });
+      destination.url = adtBaseUrl(url || fallback);
       const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
-      if (authMode === 'sso') await detectSsoAdtPort(destination, promptLabel, clients[0], { input, output, env, detectAdtUrl });
+      const adt = await settleAdtUrl(destination, promptLabel, clients[0], { insist: authMode === 'sso', candidates: url ? [] : [guess], input, output, env, detectAdtUrl });
+      if (adt === 'skipped') {
+        print(output, formatStatus(`Skipped ${promptLabel}; no MCP server was added for it.`, 'info', output, 'Local SAP GUI'));
+        continue;
+      }
+      if (authMode === 'sso') warnSsoIpHost(destination, promptLabel, output);
+      else await maybeConfigureTlsSelfHeal(destination, promptLabel, { input, output });
       destination.authentication = localAuthenticationLabel(authMode);
       destination.authMode = authMode;
       for (const client of clients) {
@@ -524,9 +604,12 @@ export async function runSetup({
   let createdKeys = [];
   let configPath;
   let managedKeys = [];
+  let previousAdtUrls = new Map();
   try {
     configPath = await resolveMcpConfigPath(env);
-    managedKeys = collectManagedCloudFoundryKeyReferences(await readMcpConfig(configPath));
+    const existingConfig = await readMcpConfig(configPath);
+    managedKeys = collectManagedCloudFoundryKeyReferences(existingConfig);
+    previousAdtUrls = previousLocalAdtUrls(existingConfig);
   } catch {
     warnings.push('Existing MCP config could not be read before setup; existing CF service keys will not be reused.');
   }
@@ -628,7 +711,7 @@ export async function runSetup({
     selected = await runManualEntryWizard({ env, input, output, detectAdtUrl });
     if (!selected.length) return await exitWithoutDestinations();
   } else {
-    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl });
+    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl, previousAdtUrls });
   }
 
   let sapDevelopmentServers = [];

package/src/terminal-ui.mjs

@@ -267,7 +267,7 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
   const footer = error => {
     if (error) return [[error, 'red']];
     if (awaitingEmptyConfirm) return [['Nothing is selected yet. Press Space to select the highlighted item (❯).', 'yellow'], [confirmEmpty, 'yellow']];
-    if (searchable && matchingIndexes().length === 0) return [['No choices match. Backspace or Esc clears search.', 'yellow']];
+    if (searchable && matchingIndexes().length === 0) return [['No choices match.', 'yellow']];
     if (!selected.size) return [['Press Space to select the highlighted item (❯), then Enter to confirm.', 'cyan']];
     return [[`${selected.size} selected. Press Enter to confirm, or Space to change.`, 'green']];
   };
@@ -281,7 +281,10 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
     ensureVisible(pageSize, indexes.length, cursorPosition);
     const lines = [];
     lines.push(truncateToColumns(`${message} (Space: select, ${shortcuts?.all || 'a'}: toggle all, Enter: confirm)`, columns));
-    if (searchable) lines.push(truncateToColumns(`Search: ${searchQuery || (searchMode ? '' : 'type a prefix; / for a or m')}`, columns));
+    if (searchable) {
+      const hint = searchQuery ? 'Backspace edits; Esc clears' : 'type prefix; / before a or m';
+      lines.push(truncateToColumns(`Search: ${searchQuery || 'type prefix'} (${hint})`, columns));
+    }
     const end = Math.min(indexes.length, top + pageSize);
     for (let index = top; index < end; index += 1) {
       const choiceIndex = indexes[index];