sap-ai-dev-toolkit 0.9.2 → 0.9.4

package/README.md

@@ -41,15 +41,17 @@ SAP AI Dev Toolkit connects your AI coding assistant to the SAP development tool
 
 ## ⚡ Quick start
 
+The default installation is a single npx command — no global install, nothing left behind except the generated MCP configuration:
+
 ```sh
-npm install --global sap-ai-dev-toolkit
-sap-ai-dev --setup
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
 ```
 
-Or run the whole toolkit once with npx — no global install, nothing left behind except the generated MCP configuration:
+Prefer a persistent global install instead?
 
 ```sh
-npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+npm install --global sap-ai-dev-toolkit
+sap-ai-dev --setup
 ```
 
 To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, and browser validation, run:
@@ -248,17 +250,23 @@ Once the destination server is enabled in your chat's tools picker, ask for outc
 
 ## 📦 Installation
 
-Install globally from SAP Business Application Studio or from a local workstation with SAP GUI installed, then run setup explicitly for your environment:
+The default installation is a single npx command that runs the guided setup directly through npm — no global install required. It works in SAP Business Application Studio and on local workstations alike:
+
+```sh
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+```
+
+Prefer a persistent global install? Install globally from SAP Business Application Studio or from a local workstation with SAP GUI installed, then run setup explicitly for your environment:
 
 | Environment / device | What to run | What setup does |
 | --- | --- | --- |
-| **SAP Business Application Studio dev space** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers BAS destinations, optionally imports Cloud Foundry Destination service records, and writes VS Code/BAS MCP entries. |
-| **Windows workstation with SAP GUI** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries. Windows SSO can be selected if the ADT endpoint supports Negotiate/SPNEGO. |
-| **macOS workstation with SAP GUI** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries with secure login prompts. |
+| **Any environment (default — no global install)** | `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` | Runs the guided setup through npm and writes generated entries that launch the pinned package through `npx` (`cmd /c npx` on Windows). Add `--npx` to force the npx launcher even when a global `sap-ai-dev` command exists. |
+| **SAP Business Application Studio dev space (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers BAS destinations, optionally imports Cloud Foundry Destination service records, and writes VS Code/BAS MCP entries. |
+| **Windows workstation with SAP GUI (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries. Windows SSO can be selected if the ADT endpoint supports Negotiate/SPNEGO. |
+| **macOS workstation with SAP GUI (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries with secure login prompts. |
 | **Any local interactive terminal, already installed** | `sap-ai-dev --setup` | Re-runs the wizard to add, update, or remove generated MCP entries. Plain `sap-ai-dev` with no arguments also starts local setup when no BAS environment is detected. |
 | **npm install hook did not show a wizard** | `sap-ai-dev --setup` | This is expected on some npm/Windows combinations because lifecycle scripts may run without an interactive console. The explicit setup command is the reliable path. |
 | **Force npm to show install-time script output** | `npm install --global --foreground-scripts sap-ai-dev-toolkit` | Optional troubleshooting mode if you specifically want to see postinstall output during installation. Still run `sap-ai-dev --setup` afterwards if no destinations were configured. |
-| **No global install / temporary setup** | `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` | Runs the guided setup through npm and writes generated entries that launch the pinned package through `npx` (`cmd /c npx` on Windows). Add `--npx` to force the npx launcher even when a global `sap-ai-dev` command exists. |
 
 ### 🪟 Windows notes
 
@@ -267,6 +275,7 @@ Everything works natively on Windows — PowerShell, cmd, and Windows Terminal a
 - `npm install --global sap-ai-dev-toolkit` puts three commands on `PATH`: `sap-ai-dev`, its alias `sap-ai-dev-toolkit`, and `sap-ai-hana`. If `sap-ai-dev` is reported as unknown, npm's global bin directory is missing from `PATH` (run `npm prefix -g` to find it) or the install did not complete — `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` works without any global install.
 - The pinned VSP runtime ships inside the package as a native `vsp-win32-x64.exe`; no Go toolchain, WSL, or extra downloads are required.
 - MCP entries that launch through npm are written as `cmd /c npx ...` on Windows — the form VS Code, Claude Code, and Cursor can spawn there. Entries written on Linux/macOS use plain `npx`.
+- Setup reads `mcp.json` even when Windows tools saved it with a UTF-8/UTF-16 BOM (PowerShell `>`/`Set-Content`, Notepad "UTF-8 with BOM") and rewrites it as plain UTF-8. If the existing file cannot be used as-is, setup self-heals before falling back to a reset: VS Code-style comments and trailing commas (JSONC) are recovered in place, torn reads from a concurrent editor save are re-read once, and broken `servers`/`inputs` fields are repaired individually. Every lossy change first backs up the original next to the real file as `mcp.json.healed|repaired|invalid-<timestamp>.bak` (exclusive create, so reruns never overwrite an earlier backup; symlinked configs keep their link). `sap-ai-dev --doctor` stays strict and reports such files instead of rewriting them — run `sap-ai-dev --setup` to heal.
 - Local SAP GUI discovery reads the Windows landscape files and registry, and setup can write an experimental Windows SSO (`Negotiate`/SPNEGO) entry; see the “Local machine SAP GUI support” section below.
 
 If you previously installed the old package, remove it first because the legacy `bas-vsp-mcp` command is no longer shipped:
@@ -316,7 +325,7 @@ Typical local setup flow:
 sap-ai-dev --setup
 ```
 
-1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**.
+1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**. If no SAP GUI entries are found, setup offers the manual entry wizard: enter a system name, ADT URL, client(s), and login mode instead.
 2. Confirm the detected/default SAP client, or enter multiple clients such as `100,200`.
 3. Accept the proposed ADT URL when it is correct, or edit it if your landscape exposes ADT through a different HTTP(S) host/port.
 4. If setup discovers certificate DNS names for an IP-based HTTPS URL, accept the yes/no TLS self-healing prompt.
@@ -343,7 +352,7 @@ To configure without a global install, run the guided setup directly through npm
 npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
 ```
 
-This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Because no global `sap-ai-dev` command is on `PATH`, it writes MCP entries that launch the pinned package version through npx — through `cmd /c npx` on Windows, which is the form VS Code, Claude Code, and Cursor can spawn there. `--ignore-scripts` avoids running the install-time wizard a second time; add `--npx` to force this launcher shape even when the toolkit is installed globally. After setup, in BAS or VS Code run **MCP: List Servers**, select each chosen destination, and choose **Start Server**.
+This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, **a** to toggle all (select all if any are unchecked; otherwise clear the selection), and **m** to configure an undiscovered system manually in the manual entry wizard; configured systems join the picker pre-selected. Because no global `sap-ai-dev` command is on `PATH`, it writes MCP entries that launch the pinned package version through npx — through `cmd /c npx` on Windows, which is the form VS Code, Claude Code, and Cursor can spawn there. `--ignore-scripts` avoids running the install-time wizard a second time; add `--npx` to force this launcher shape even when the toolkit is installed globally. After setup, in BAS or VS Code run **MCP: List Servers**, select each chosen destination, and choose **Start Server**.
 
 For a non-interactive installation or a platform without a published VSP asset, provide a trusted binary override:
 
@@ -438,7 +447,9 @@ Review skipped or conflicting files and merge changes manually. `LintABAP` analy
 If the `cf` CLI is version 8.18 or newer and authenticated to a targeted space, setup offers an opt-in import from that space's SAP Destination service. It does not create service keys unless you accept. The imported records are limited to the current space and are merged with BAS destinations for selection. OnPremise destinations require choosing a Connectivity service instance; runtime traffic uses that service's proxy, and PrincipalPropagation uses the current CF user's token. Internet destinations use the configured HTTP(S) proxy environment. Setup stores only service-instance/key references in `mcp.json`, not the service-key credentials. At runtime the generated entry verifies the active CF space and resolves those references. Setup removes an add-on-created key only when no remaining CF entry references it and the CLI is targeted to the key's recorded space; keys are left untouched when the space cannot be verified.
 Cloud Foundry HTTP destination probes use forward-form HTTP requests, not CONNECT tunnels; SAP Connectivity requires HTTP from the application to its proxy. OnPremise requests are canceled when the client disconnects or the runtime route closes.
 
-Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination or local SAP GUI system selection without changing MCP config. Run the interactive setup command above; generated entries fall back to the pinned npx launcher automatically when the package is not installed globally.
+Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, **a** to toggle all (select all if any are unchecked; otherwise clear the selection), and **m** to configure an undiscovered system manually in the manual entry wizard; configured systems join the picker pre-selected. Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination or local SAP GUI system selection without changing MCP config. Run the interactive setup command above; generated entries fall back to the pinned npx launcher automatically when the package is not installed globally.
+
+When nothing is detected — no BAS destinations, no Cloud Foundry imports, or no local SAP GUI entries — setup offers the **manual entry wizard** instead of stopping. The same wizard is available at any point in the destination picker via the **m** shortcut. It asks for a system name, the ADT HTTP(S) base URL (for example `https://myhost.example:44300`), one or more 3-digit SAP clients, and (on Windows) the login mode. You can add several systems in one run; each becomes the same isolated per-system/client MCP server the discovery flows generate, including credential input prompts and TLS self-healing for IP-based HTTPS URLs. Declining the wizard when nothing was detected exits setup without changes; aborting it inside the picker (Ctrl+C) returns to the selection unchanged.
 
 Setup tidies its own footprint: it reconciles MCP entries managed by this package and removes legacy `sapAiDev_*` / `basVspMcp_*` entries from earlier releases. Existing unrelated MCP servers and top-level configuration such as `inputs` stay untouched.
 
@@ -848,6 +859,8 @@ Runtime diagnostics take the stderr lane. In the MCP server's Output view, check
 
 If `GetSystemInfo` or `RunQuery` reports a CSRF-token fetch failure, VSP tries `/sap/bc/adt/core/discovery` first and falls back to `/sap/bc/adt/discovery` when the core endpoint returns HTTP 404 or 5xx without a token. If both endpoints fail, the error includes their HTTP statuses; check BAS destination routing and the SAP ADT service. `GetInstalledComponents` is a separate GET request and a failure there is not evidence of a CSRF problem.
 
+**`MCP config ... contains invalid JSON`** usually means one of three things, all healed automatically by setup: the file starts with a byte-order mark (Windows PowerShell `>` redirection, `Set-Content`, or Notepad's "UTF-8 with BOM" mode — invisible in editors and terminals), it contains comments or trailing commas (VS Code reads `mcp.json` as JSONC), or setup raced an editor save and read a torn file (retried once before healing). Unrecoverable content is backed up as `mcp.json.<kind>-<timestamp>.bak` and replaced; the backup path is printed in the setup warning. On older versions, re-save the file as UTF-8 without BOM (VS Code: "Change File Encoding → Save with Encoding → UTF-8") and rerun `sap-ai-dev --setup`.
+
 If automatic Go or VSP provisioning fails, check network access and the package's supported platform. You can install Go manually or set `GO_BINARY` as an explicit fallback. A trusted prebuilt VSP can be supplied with `SAP_AI_DEV_TOOLKIT_BINARY`.
 
 ## 🧑‍💻 Development

package/package.json

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

package/src/bas-discovery.mjs

@@ -17,19 +17,26 @@ function scalar(value) {
 }
 
 function propertiesOf(item) {
+  // Nested property maps (BAS wraps destination attributes in `properties`,
+  // some proxies use `configuration` or a key/value array) only fill gaps:
+  // a nested `Name` — e.g. the Cloud Connector system name `_SIDCLNTOX` —
+  // must never overwrite the real destination name at the top level.
   const result = {};
-  for (const [key, value] of Object.entries(item || {})) result[keyName(key)] = scalar(value);
-  const maps = Object.entries(item || {}).filter(([key]) => ['properties', 'propertymap', 'destinationproperties', 'configuration'].includes(keyName(key))).map(([, value]) => value);
+  const entries = Object.entries(item || {});
+  const maps = entries.filter(([key]) => ['properties', 'propertymap', 'destinationproperties', 'configuration'].includes(keyName(key))).map(([, value]) => value);
   for (const map of maps) {
     if (Array.isArray(map)) {
       for (const entry of map) {
         const key = entry?.key ?? entry?.name ?? entry?.property;
-        if (key != null) result[keyName(key)] = scalar(entry?.value ?? entry?.val);
+        if (key != null && !(keyName(key) in result)) result[keyName(key)] = scalar(entry?.value ?? entry?.val);
       }
     } else if (map && typeof map === 'object') {
-      for (const [key, value] of Object.entries(map)) result[keyName(key)] = scalar(value);
+      for (const [key, value] of Object.entries(map)) {
+        if (!(keyName(key) in result)) result[keyName(key)] = scalar(value);
+      }
     }
   }
+  for (const [key, value] of entries) result[keyName(key)] = scalar(value);
   return result;
 }
 
@@ -42,23 +49,36 @@ function listFromBody(body) {
   if (Array.isArray(body)) return body;
   if (!body || typeof body !== 'object') return null;
   for (const [key, value] of Object.entries(body)) {
-    if (['destinations', 'data'].includes(keyName(key)) && Array.isArray(value)) return value;
+    if (!['destinations', 'destinationlist', 'data', 'items', 'value'].includes(keyName(key))) continue;
+    if (Array.isArray(value)) return value;
+    // Some destination services unwrap records into a name-keyed map
+    // instead of an array; heal the shape so discovery still proceeds.
+    if (value && typeof value === 'object') {
+      const records = Object.entries(value).filter(([, entry]) => entry && typeof entry === 'object').map(([mapName, entry]) => ({ name: mapName, ...entry }));
+      if (records.length) return records;
+    }
   }
   return null;
 }
 
 export function normalizeDestination(item) {
   const values = propertiesOf(item);
-  const name = text(values.name || values.destinationname || values.destname);
+  const name = text(values.name || values.destinationname || values.destname || values.destination || values.sapdestinationname);
   const authentication = text(values.authentication || values.authtype || values.auth);
-  const client = text(values.sapclient || values.client) || '001';
+  const client = text(values.sapclient || values.client || values.mandt) || '001';
   const backendUrl = text(values.url || values.host || values.webideexposedhost);
   const proxyType = text(values.proxytype || values.proxy);
+  // One destination with an unusable name must never abort discovery; the
+  // probe reports `invalid-name` for entries whose url stays null.
+  let url = null;
+  if (name) {
+    try { url = destinationUrl(name); } catch { url = null; }
+  }
   return {
     name,
     authentication: authentication || 'Unknown',
     client,
-    url: name ? destinationUrl(name) : null,
+    url,
     backendUrl: backendUrl || null,
     proxyType: proxyType || null,
     rawKeys: Object.keys(item || {}).map(String)
@@ -67,7 +87,10 @@ export function normalizeDestination(item) {
 
 export function destinationUrl(name) {
   const value = text(name);
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) throw new Error(`Invalid BAS destination name: ${value || '<empty>'}`);
+  // A leading underscore is valid: BAS destination names allow it (Cloud
+  // Connector system names like `_SIDCLNTOX`), and `<name>.dest` resolution
+  // inside a dev space is Host-header matching in the BAS proxy, not DNS.
+  if (!/^[A-Za-z0-9_][A-Za-z0-9._-]*$/.test(value)) throw new Error(`Invalid BAS destination name: ${value || '<empty>'}`);
   return `http://${value}.dest`;
 }
 
@@ -137,7 +160,7 @@ function proxyDispatcher(target, env) {
 
 export async function fetchDestinationList(h2oUrl, options = {}) {
   if (!h2oUrl) throw new Error('H2O_URL is required for BAS destination discovery');
-  const url = `${String(h2oUrl).replace(/\/$/, '')}/api/listDestinations`;
+  const url = `${String(h2oUrl).trim().replace(/\/+$/, '')}/api/listDestinations`;
   const env = options.env || process.env;
   const dispatcher = proxyDispatcher(url, env);
   try {
@@ -147,7 +170,15 @@ export async function fetchDestinationList(h2oUrl, options = {}) {
       ...(dispatcher ? { dispatcher } : {})
     });
     if (!response.ok) throw new Error(`BAS destination discovery failed with HTTP ${response.status}`);
-    return await response.json();
+    // Parse from text so UTF-8 BOMs and text/plain content types from
+    // proxies in front of BAS do not break discovery.
+    const payload = await response.text();
+    try {
+      return JSON.parse(payload.replace(/^\uFEFF/, ''));
+    } catch {
+      const preview = payload.trim().slice(0, 200);
+      throw new Error(`BAS destination discovery returned unparsable JSON${preview ? `: ${preview}` : ''}`);
+    }
   } finally {
     await dispatcher?.close();
   }
@@ -186,7 +217,12 @@ function requestProbe(target, proxyUrl, timeoutMs) {
 }
 
 export async function probeADT(destination, options = {}) {
-  const url = `${destinationUrl(destination.name)}/sap/bc/adt/discovery`;
+  let url;
+  try {
+    url = `${destinationUrl(destination.name)}/sap/bc/adt/discovery`;
+  } catch (error) {
+    return { status: 'invalid-name', available: false, warning: error.message };
+  }
   if (options.skipProbe) return { status: 'skipped', available: true, url };
   try {
     const result = options.probeImpl ? await options.probeImpl(url, options) : await requestProbe(url, options.proxyUrl ?? DEFAULT_PROXY, options.timeoutMs || 5000);
@@ -204,7 +240,13 @@ export async function discoverDestinations(options = {}) {
   const list = listFromBody(body);
   if (!list) throw new Error(`Unrecognized BAS destination response shape; top-level keys: ${Object.keys(body || {}).map(String).join(', ') || '<none>'}`);
   const allow = text(brandedEnvValue(env, 'DESTINATION')).split(',').map(value => value.trim().toLowerCase()).filter(Boolean);
-  const normalized = list.map(normalizeDestination).filter(item => item.name).filter(item => !allow.length || allow.includes(item.name.toLowerCase()));
+  const normalized = list
+    .map(item => {
+      try { return normalizeDestination(item); }
+      catch (error) { return { name: '', probe: { status: 'invalid-name', available: false, warning: error.message } }; }
+    })
+    .filter(item => item.name)
+    .filter(item => !allow.length || allow.includes(item.name.toLowerCase()));
   const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
   const configuredProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.HTTP_PROXY ?? env.http_proxy);
   const proxyUrl = configuredProxy !== undefined ? configuredProxy : DEFAULT_PROXY;

package/src/harness-mcp-config.mjs

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { harnessById, harnessRoot } from './harnesses.mjs';
+import { decodeJsonFileBuffer } from './mcp-config.mjs';
 
 const MANAGED_ENV = 'SAP_AI_DEV_TOOLKIT_MANAGED';
 
@@ -24,13 +25,15 @@ function mcpServersPath(harness, { home = process.env.HOME || homedir(), env = p
 async function readJsonConfig(path) {
   let raw;
   try {
-    raw = await readFile(path, 'utf8');
+    raw = await readFile(path);
   } catch (error) {
     if (error.code === 'ENOENT') return {};
     throw error;
   }
   try {
-    const parsed = JSON.parse(raw);
+    // decodeJsonFileBuffer tolerates the UTF-8 BOM / UTF-16 encodings that
+    // Windows tools commonly write (see mcp-config.mjs).
+    const parsed = JSON.parse(decodeJsonFileBuffer(raw));
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('top-level value is not an object');
     return parsed;
   } catch (error) {

package/src/mcp-config.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir, platform } from 'node:os';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -79,6 +80,26 @@ async function exists(path) {
   }
 }
 
+// Windows tools (PowerShell `>` redirection and Set-Content, Notepad "UTF-8
+// with BOM", several editors) write mcp.json with a byte-order mark or even
+// UTF-16. JSON.parse rejects a leading BOM (rendering invisibly as
+// "Unexpected token ''"), so decode defensively before parsing.
+export function decodeJsonFileBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer)) return String(buffer ?? '').replace(/^/, '');
+  if (buffer.length >= 2) {
+    if (buffer[0] === 0xFF && buffer[1] === 0xFE) return buffer.subarray(2).toString('utf16le');
+    if (buffer[0] === 0xFE && buffer[1] === 0xFF) {
+      let body = buffer.subarray(2);
+      if (body.length % 2) body = body.subarray(0, body.length - 1);
+      return Buffer.from(body).swap16().toString('utf16le');
+    }
+  }
+  const utf8 = (buffer.length >= 3 && buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF)
+    ? buffer.subarray(3).toString('utf8')
+    : buffer.toString('utf8');
+  return utf8.replace(/^\uFEFF/, '');
+}
+
 export async function resolveMcpServerCommand(env = process.env) {
   const executableNames = process.platform === 'win32'
     ? ['sap-ai-dev.cmd', 'sap-ai-dev.exe', 'sap-ai-dev']
@@ -336,36 +357,186 @@ export function collectCloudFoundryKeyReferencesFromAllEntries(config) {
   return collectCloudFoundryKeyReferences(config, false);
 }
 
-async function readConfig(path) {
-  let raw;
+function freshConfig() {
+  return { servers: {}, inputs: [] };
+}
+
+// VS Code parses mcp.json as JSONC: // and /* */ comments plus trailing
+// commas are accepted there but rejected by strict JSON.parse. Strip them in
+// one string-aware pass (string literals are copied verbatim, so "//", "/*",
+// and "," inside values survive) so self-healing can recover hand-written
+// content instead of resetting the file.
+export function loosenJsonText(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < n && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, Math.min(j + 1, n));
+      i = Math.min(j + 1, n);
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '/') {
+      i += 2;
+      while (i < n && text[i] !== '\n' && text[i] !== '\r') i += 1;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i = Math.min(i + 2, n);
+      continue;
+    }
+    if (ch === ',') {
+      // A trailing comma is dropped only when nothing but whitespace and
+      // comments separate it from a closing bracket.
+      let k = i + 1;
+      while (k < n) {
+        const lookahead = text[k];
+        if (lookahead === ' ' || lookahead === '\t' || lookahead === '\n' || lookahead === '\r') { k += 1; continue; }
+        if (lookahead === '/' && text[k + 1] === '/') { k += 2; while (k < n && text[k] !== '\n' && text[k] !== '\r') k += 1; continue; }
+        if (lookahead === '/' && text[k + 1] === '*') { k += 2; while (k < n && !(text[k] === '*' && text[k + 1] === '/')) k += 1; k = Math.min(k + 2, n); continue; }
+        break;
+      }
+      if (text[k] === '}' || text[k] === ']') { i += 1; continue; }
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+export function backupPathCandidates(path, kind, now = new Date()) {
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-');
+  return ['', '-2', '-3', '-4', '-5'].map(suffix => `${path}.${kind}-${stamp}${suffix}.bak`);
+}
+
+// Backups use exclusive creation (wx) so a repeated setup can never clobber
+// an earlier backup; identical timestamps walk a numeric suffix instead.
+// Failing to write the backup is fatal on purpose: healing must never risk
+// losing the only copy of the original file.
+export async function writeConfigBackup(path, buffer, { kind, now } = {}) {
+  let lastError;
+  for (const candidate of backupPathCandidates(path, kind, now)) {
+    try {
+      await writeFile(candidate, buffer, { flag: 'wx', mode: 0o600 });
+      return candidate;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw new Error(`Could not back up ${path} before healing (${error.message}); the original file was left untouched.`);
+      }
+      lastError = error;
+    }
+  }
+  throw new Error(`Could not back up ${path}: no unique backup name was available (${lastError?.message}).`);
+}
+
+function shapeFailures(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return [{ field: null, message: 'must contain a top-level JSON object' }];
+  }
+  const failures = [];
+  if (config.servers !== undefined && (!config.servers || typeof config.servers !== 'object' || Array.isArray(config.servers))) {
+    failures.push({ field: 'servers', message: 'has a non-object servers value' });
+  }
+  if (config.inputs !== undefined && config.inputs !== null && !Array.isArray(config.inputs)) {
+    failures.push({ field: 'inputs', message: 'has a non-array inputs value' });
+  }
+  return failures;
+}
+
+// Healing ladder (install/setup only; strict readers such as --doctor keep
+// rejecting): BOM/UTF-16 decode -> torn-write re-read -> JSONC recovery ->
+// field-level repair -> full reset. Every lossy step backs up the original
+// first; a backup failure aborts rather than risking data loss.
+async function readConfig(path, options = {}) {
+  const { recoverInvalid = false, warnings, retryDelayMs = 250, readFileImpl = readFile } = options;
+  let buffer;
   try {
-    raw = await readFile(path, 'utf8');
+    buffer = await readFileImpl(path);
   } catch (error) {
-    if (error?.code === 'ENOENT') return { servers: {}, inputs: [] };
+    if (error?.code === 'ENOENT') return freshConfig();
     throw new Error(`MCP config ${path} could not be read: ${error.message}`);
   }
-  let config;
-  try {
-    config = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`MCP config ${path} contains invalid JSON: ${error.message}`);
+  let text = decodeJsonFileBuffer(buffer);
+  if (!text.trim()) return freshConfig();
+  const tryParse = candidate => {
+    try { return { config: JSON.parse(candidate) }; } catch (error) { return { error }; }
+  };
+  let parsed = tryParse(text);
+  if (parsed.error && retryDelayMs > 0) {
+    // A torn read — setup racing an editor's non-atomic save — looks exactly
+    // like corruption; re-read once before healing so a transient state is
+    // never backed up and replaced.
+    await sleep(retryDelayMs);
+    const second = await readFileImpl(path).catch(() => null);
+    if (second && !second.equals(buffer)) {
+      buffer = second;
+      text = decodeJsonFileBuffer(second);
+      if (!text.trim()) return freshConfig();
+      parsed = tryParse(text);
+    }
   }
-  if (!config || typeof config !== 'object' || Array.isArray(config)) {
-    throw new Error(`MCP config ${path} must contain a top-level JSON object`);
+  let loosened = false;
+  if (parsed.error && recoverInvalid) {
+    const recovered = tryParse(loosenJsonText(text));
+    if (!recovered.error) {
+      parsed = recovered;
+      loosened = true;
+    }
   }
-  if (config.servers !== undefined && (!config.servers || typeof config.servers !== 'object' || Array.isArray(config.servers))) {
-    throw new Error(`MCP config ${path} has a non-object servers value`);
+  const failures = parsed.error ? [{ field: null, message: `contains invalid JSON: ${parsed.error.message}` }] : shapeFailures(parsed.config);
+  if (failures.some(failure => failure.field === null)) {
+    const detail = failures[0].message;
+    if (!recoverInvalid) throw new Error(`MCP config ${path} ${detail}`);
+    return recoverConfig(path, buffer, warnings, {
+      kind: 'invalid',
+      notes: [`was not usable as JSON (${detail.replace(/^contains invalid JSON: /, '')}) and was replaced with a fresh config`],
+      config: freshConfig()
+    });
   }
-  return { ...config, servers: config.servers || {} };
+  const blocking = failures.find(failure => failure.field !== 'inputs');
+  if (!recoverInvalid) {
+    if (blocking) throw new Error(`MCP config ${path} ${blocking.message}`);
+    return { ...parsed.config, servers: parsed.config.servers || {} };
+  }
+  const notes = [];
+  if (loosened) notes.push('contained comments or trailing commas (accepted by VS Code, not strict JSON)');
+  const healed = { ...parsed.config };
+  for (const failure of failures) {
+    if (failure.field === 'servers') { healed.servers = {}; notes.push('had a non-object "servers" value, which was reset'); }
+    if (failure.field === 'inputs') { delete healed.inputs; notes.push('had a non-array "inputs" value, which was removed'); }
+  }
+  if (!notes.length) return { ...parsed.config, servers: parsed.config.servers || {} };
+  return recoverConfig(path, buffer, warnings, {
+    kind: loosened ? 'healed' : 'repaired',
+    notes,
+    config: { ...healed, servers: healed.servers || {} }
+  });
+}
+
+async function recoverConfig(path, buffer, warnings, { kind, notes, config }) {
+  // Back up beside the real file (following symlinks) so a linked mcp.json
+  // keeps its link and the backup sits next to the actual target.
+  const backupBase = await realpath(path).catch(() => path);
+  const backup = await writeConfigBackup(backupBase, buffer, { kind });
+  warnings?.push(`The existing MCP config ${notes.join(' and ')}; the original was backed up to ${backup}.`);
+  return config;
 }
 
 async function writeConfig(path, config) {
-  const directory = dirname(path);
+  // Follow symlinks so a linked mcp.json (dotfiles managers) keeps its link
+  // while the real target is replaced atomically.
+  const target = await realpath(path).catch(() => path);
+  const directory = dirname(target);
   await mkdir(directory, { recursive: true });
-  const temporary = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+  const temporary = join(directory, `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`);
   try {
     await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-    await rename(temporary, path);
+    await rename(temporary, target);
   } catch (error) {
     await rm(temporary, { force: true }).catch(() => {});
     throw new Error(`MCP config ${path} could not be written: ${error.message}`);
@@ -380,7 +551,11 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   }
   const env = options.env || process.env;
   const path = options.path || await resolveMcpConfigPath(env);
-  const config = await readConfig(path);
+  const installWarnings = [];
+  // recoverInvalid: BOM/encoding damage, VS Code JSONC comments, torn writes
+  // racing an editor save, and corrupt configs are healed (with a backup)
+  // instead of failing the whole setup (self-healing).
+  const config = await readConfig(path, { recoverInvalid: true, warnings: installWarnings });
   const selfVersion = await runningPackageVersion();
   const companionVersions = selfVersion ? { 'sap-ai-dev-toolkit': selfVersion, 'hana-cloud-inspector': selfVersion } : {};
   const generated = {
@@ -434,7 +609,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     config.inputs = [...existingInputs, ...generatedInputs.values()];
   }
   await writeConfig(path, config);
-  return { path, servers: generated };
+  return { path, servers: generated, warnings: installWarnings };
 }
 
 export async function repairManagedMcpConfig(discoveredDestinations, { env = process.env, path, discoveryComplete = false, packageVersion } = {}) {
@@ -499,6 +674,6 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
   return { path: configPath, changed: true, repaired, managedEntries };
 }
 
-export async function readMcpConfig(path) {
-  return readConfig(path);
+export async function readMcpConfig(path, options = {}) {
+  return readConfig(path, options);
 }

package/src/setup.mjs

@@ -112,6 +112,167 @@ async function promptSapClients(destination, { input = stdin, output = stdout }
   return parseSapClientList(answer, fallback);
 }
 
+function validateAdtUrlCandidate(candidate) {
+  if (!candidate) return 'Enter an ADT base URL, for example https://host:44300.';
+  try {
+    const parsed = new URL(candidate);
+    if (!['http:', 'https:'].includes(parsed.protocol)) return 'Use an http:// or https:// URL.';
+    if (parsed.username || parsed.password) return 'Do not embed credentials in the ADT URL; use the login prompts.';
+    if (parsed.search || parsed.hash) return 'Enter an ADT base URL without a query or fragment.';
+    return true;
+  }
+  catch { return 'Enter a valid URL.'; }
+}
+
+function localAuthenticationLabel(authMode) {
+  return ['windows-sso', 'windows-credential-ui', 'windows-sso-basic-fallback'].includes(authMode) ? 'WindowsSSO' : 'Basic';
+}
+
+async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
+  const answer = await textPrompt({
+    message,
+    placeholder: 'y',
+    required: false,
+    validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
+  }, { input, output });
+  return !/^n(?:o)?$/i.test(String(answer || '').trim());
+}
+
+function buildLocalClientDestination(destination, client, authMode, { multipleClients = false, duplicateSystemName = false } = {}) {
+  const name = localClientDestinationName(destination, client, { multipleClients, duplicateSystemName });
+  const localDestination = { ...destination, name, serverName: name, client };
+  const userInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  const passwordInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  const credentialInputs = [
+    { id: userInputId, type: 'promptString', description: `SAP user for ${localDestination.name}` },
+    { id: passwordInputId, type: 'promptString', description: `SAP password for ${localDestination.name}`, password: true }
+  ];
+  if (authMode === 'windows-sso') {
+    localDestination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
+    localDestination.inputs = [];
+  } else if (authMode === 'windows-credential-ui') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'windows-sso',
+      SAP_AI_DEV_TOOLKIT_WINDOWS_CREDENTIAL_UI: 'true'
+    };
+    localDestination.inputs = [];
+  } else if (authMode === 'windows-sso-basic-fallback') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'windows-sso',
+      SAP_AUTH_FALLBACK_MODE: 'basic',
+      SAP_USER: `\${input:${userInputId}}`,
+      SAP_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  } else if (authMode === 'browser-saml') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'browser-saml',
+      SAP_BROWSER_AUTH: 'true',
+      SAP_SAML_AUTH: 'true'
+    };
+    localDestination.inputs = [];
+  } else if (authMode === 'saml-password') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'saml-password',
+      SAP_SAML_AUTH: 'true',
+      SAP_SAML_USER: `\${input:${userInputId}}`,
+      SAP_SAML_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  } else {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'basic',
+      SAP_USER: `\${input:${userInputId}}`,
+      SAP_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  }
+  return localDestination;
+}
+
+async function maybeConfigureTlsSelfHeal(destination, promptLabel, { input = stdin, output = stdout } = {}) {
+  const parsedAdtUrl = new URL(destination.url);
+  if (parsedAdtUrl.protocol !== 'https:' || !isIP(parsedAdtUrl.hostname)) return;
+  print(output, formatStatus('The ADT URL uses an IP address. Setup will inspect the SAP HTTPS certificate and can enable TLS self-healing automatically; certificate validation remains enabled.', 'warning', output, 'TLS self-heal'));
+  let discoveredNames = [];
+  try { discoveredNames = await discoverCertificateDnsNames(destination.url); }
+  catch { discoveredNames = []; }
+  if (!discoveredNames.length) {
+    print(output, formatStatus('No DNS subjectAltName entries could be read from the SAP HTTPS certificate. TLS self-healing was not configured automatically.', 'warning', output, 'TLS self-heal'));
+    return;
+  }
+  const preview = discoveredNames.slice(0, 5).join(', ');
+  const useDiscovered = await confirmPrompt(`Use discovered certificate DNS name${discoveredNames.length === 1 ? '' : 's'} for ${promptLabel}: ${preview}${discoveredNames.length > 5 ? ', ...' : ''}? (y/Enter=yes, n=no)`, { input, output });
+  if (useDiscovered) {
+    destination.tlsServerNames = discoveredNames;
+    destination.tlsServerName = discoveredNames[0];
+  }
+}
+
+// Manual MCP entry wizard: offered whenever discovery finds nothing to select
+// (no BAS destinations, no Cloud Foundry imports, no SAP GUI entries). It
+// collects the minimal ADT configuration directly from the user and produces
+// the same local destination shape as the SAP GUI flow, so installation,
+// credential inputs, and TLS handling stay identical.
+async function runManualEntryWizard({ env = process.env, input = stdin, output = stdout } = {}) {
+  print(output, '');
+  print(output, colorText('✍️  Manual system entry — skip discovery, add your SAP system directly', 'magenta', output));
+  print(output, colorText('   The ADT URL is the base URL that Eclipse ADT or VS Code ADT tools use, for example https://myhost.example:44300.', 'cyan', output));
+  print(output, colorText('   Setup writes one isolated MCP server per system/client pair, with login prompts and TLS self-healing like every other entry.', 'cyan', output));
+  const expanded = [];
+  const usedNames = new Set();
+  let addAnother = true;
+  while (addAnother) {
+    const name = (await textPrompt({
+      message: 'System name',
+      placeholder: 'S4H sandbox',
+      required: true,
+      validate: value => {
+        const trimmed = String(value || '').trim();
+        if (!trimmed) return 'Enter a name for the system.';
+        if (usedNames.has(trimmed.toLowerCase())) return 'A system with this name was already added; choose another name.';
+        return true;
+      }
+    }, { input, output })).trim();
+    usedNames.add(name.toLowerCase());
+    const url = await textPrompt({
+      message: `ADT URL for ${name}`,
+      placeholder: 'https://host:44300',
+      required: true,
+      validate: validateAdtUrlCandidate
+    }, { input, output });
+    let parsedUrl;
+    try { parsedUrl = new URL(url); }
+    catch { parsedUrl = null; }
+    const destination = {
+      source: 'sap-gui-local',
+      name,
+      serverName: name,
+      url,
+      host: parsedUrl?.hostname || '',
+      client: '001',
+      authentication: 'Basic',
+      authMode: 'basic',
+      proxyType: 'Internet',
+      // Marks wizard-configured systems so the discovery confirmation prompts
+      // (clients, ADT URL, login) skip them when they flow through the
+      // 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 });
+    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'));
+    addAnother = await confirmPrompt('Add another system? (y/Enter=yes, n=no)', { input, output });
+  }
+  return expanded;
+}
+
 function localSystemDiscriminator(destination) {
   return [destination.systemId, destination.host, destination.instance].map(value => String(value || '').trim()).filter(Boolean).join(' ');
 }
@@ -216,6 +377,90 @@ 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 } = {}) {
+  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);
+    return leftRank - rightRank || String(left.name).localeCompare(String(right.name));
+  });
+  const choices = orderedDestinations.map(destination => {
+    const probe = destination.probe?.status || 'unknown';
+    const source = destination.source === 'cloud-foundry'
+      ? `CF ${destination.cf.destinationInstanceName}`
+      : (destination.source === 'sap-gui-local' ? `SAP GUI ${destination.systemId || destination.host || ''}`.trim() : 'BAS');
+    const disabled = destination.disabledReason;
+    const state = disabled ? 'disabled' : (probe === 'needs-adt-url' ? probe : (destination.probe?.available === false ? `fail:${probe}` : `ok:${probe}`));
+    return {
+      value: destination,
+      name: `${destination.name} (${source}, client ${destination.client}, ${state})`,
+      ...(disabled ? { disabled } : {}),
+      checked: false
+    };
+  });
+  print(output, '');
+  print(output, formatStatus('Choose the destinations to add. Reachable destinations are shown first.', 'step', output, 'Setup'));
+  print(output, '');
+  print(output, colorText('  Space = select/deselect · a = toggle all · m = add a system manually · Enter = confirm.', 'cyan', output));
+  print(output, colorText('  💡 No system listed, or need an extra one? Press m to skip discovery and add any SAP system manually.', 'magenta', output));
+  print(output, '  Nothing selected removes this add-on’s MCP entries.');
+  print(output, '');
+  const addManually = async () => (await runManualEntryWizard({ env, input, output })).map(destination => ({
+    value: destination,
+    name: `${destination.name} (manual, client ${destination.client})`
+  }));
+  let selected = await checkboxPrompt({
+    message: colorText('🧭 Select destinations', 'cyan', output),
+    choices,
+    required: false,
+    shortcuts: { all: 'a' },
+    actions: { m: addManually }
+  }, { input, output });
+
+  if (!isBas && selected.length) {
+    print(output, '');
+    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
+    print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
+    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication (Negotiate/SPNEGO). It uses the current Windows logon session, including smart-card-backed Windows logon; the toolkit cannot prompt for or accept manual bearer/SAML tokens. Username/password remains the default.');
+    const selectedNameCounts = selected.reduce((counts, destination) => {
+      const key = String(destination.name).toLowerCase();
+      counts.set(key, (counts.get(key) || 0) + 1);
+      return counts;
+    }, new Map());
+    const expanded = [];
+    for (const destination of selected) {
+      // Wizard-configured systems are already complete; only discovered SAP
+      // GUI entries need their clients, ADT URL, and login confirmed here.
+      if (destination.configuredManually) {
+        expanded.push(destination);
+        continue;
+      }
+      const duplicateSystemName = (selectedNameCounts.get(String(destination.name).toLowerCase()) || 0) > 1;
+      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 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 });
+      const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
+      destination.authentication = localAuthenticationLabel(authMode);
+      destination.authMode = authMode;
+      for (const client of clients) {
+        expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1, duplicateSystemName }));
+      }
+    }
+    selected = expanded;
+  }
+  return selected;
+}
+
 export async function runSetup({
   env = process.env,
   input = stdin,
@@ -237,6 +482,7 @@ export async function runSetup({
     return { skipped: true, reason: 'non-tty' };
   }
   print(output, '');
+  print(output, colorText('💡 Tip: you can skip auto-discovery and add a system manually — press m in the destination picker, or take the wizard offer when nothing is found.', 'magenta', output));
   if (!isBas) print(output, formatStatus('Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
 
   let destinations = [];
@@ -349,160 +595,32 @@ export async function runSetup({
     return result.warnings || [];
   };
   const selectable = destinations.filter(destination => !destination.disabledReason);
-  if (!selectable.length) {
-    print(output, formatStatus(isBas ? 'No selectable BAS or Cloud Foundry destinations were found.' : 'No SAP GUI systems were found on this computer.', 'warning', output, 'Setup'));
-    print(output, isBas ? remediation : 'Install SAP GUI and create SAP Logon entries, or set SAP_AI_DEV_MCP_CONFIG and add systems manually. ADT still needs an HTTP(S) URL; SAP GUI files contain DIAG routing only.');
+  const exitWithoutDestinations = async () => {
     await reportWarnings(warnings);
     const cleanupWarnings = await cleanupNewKeysWithoutConfigChange();
     await reportWarnings(cleanupWarnings);
     return { skipped: true, reason: 'no-destinations', warnings: [...warnings, ...cleanupWarnings] };
-  }
-
-  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);
-    return leftRank - rightRank || String(left.name).localeCompare(String(right.name));
-  });
-  const choices = orderedDestinations.map(destination => {
-    const probe = destination.probe?.status || 'unknown';
-    const source = destination.source === 'cloud-foundry'
-      ? `CF ${destination.cf.destinationInstanceName}`
-      : (destination.source === 'sap-gui-local' ? `SAP GUI ${destination.systemId || destination.host || ''}`.trim() : 'BAS');
-    const disabled = destination.disabledReason;
-    const state = disabled ? 'disabled' : (probe === 'needs-adt-url' ? probe : (destination.probe?.available === false ? `fail:${probe}` : `ok:${probe}`));
-    return {
-      value: destination,
-      name: `${destination.name} (${source}, client ${destination.client}, ${state})`,
-      ...(disabled ? { disabled } : {}),
-      checked: false
-    };
-  });
-  print(output, '');
-  print(output, formatStatus('Choose the destinations to add. Reachable destinations are shown first.', 'step', output, 'Setup'));
-  print(output, '');
-  print(output, '  Space = select/deselect · a = toggle all · Enter = confirm.');
-  print(output, '  Nothing selected removes this add-on’s MCP entries.');
-  print(output, '');
-  let selected = await checkboxPrompt({
-    message: colorText('🧭 Select destinations', 'cyan', output),
-    choices,
-    required: false,
-    shortcuts: { all: 'a' }
-  }, { input, output });
-
-  if (!isBas && selected.length) {
+  };
+  let selected;
+  if (!selectable.length) {
+    // Nothing was detected — no BAS/CF destinations, or no SAP GUI entries.
+    // Offer the manual MCP entry wizard before giving up.
+    print(output, formatStatus(isBas ? 'No selectable BAS or Cloud Foundry destinations were found.' : 'No SAP GUI systems were found on this computer.', 'warning', output, 'Setup'));
+    print(output, isBas ? remediation : 'Install SAP GUI and create SAP Logon entries, or configure your system manually below. ADT still needs an HTTP(S) URL; SAP GUI files contain DIAG routing only.');
     print(output, '');
-    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
-    print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
-    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication (Negotiate/SPNEGO). It uses the current Windows logon session, including smart-card-backed Windows logon; the toolkit cannot prompt for or accept manual bearer/SAML tokens. Username/password remains the default.');
-    const selectedNameCounts = selected.reduce((counts, destination) => {
-      const key = String(destination.name).toLowerCase();
-      counts.set(key, (counts.get(key) || 0) + 1);
-      return counts;
-    }, new Map());
-    const expanded = [];
-    for (const destination of selected) {
-      const duplicateSystemName = (selectedNameCounts.get(String(destination.name).toLowerCase()) || 0) > 1;
-      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 url = await textPrompt({
-        message: `ADT URL for ${promptLabel}`,
-        placeholder: fallback || 'https://host:44300',
-        validate: value => {
-          const candidate = value || fallback;
-          if (!candidate) return 'Enter an ADT base URL, for example https://host:44300.';
-          try {
-            const parsed = new URL(candidate);
-            if (!['http:', 'https:'].includes(parsed.protocol)) return 'Use an http:// or https:// URL.';
-            if (parsed.username || parsed.password) return 'Do not embed credentials in the ADT URL; use the login prompts.';
-            if (parsed.search || parsed.hash) return 'Enter an ADT base URL without a query or fragment.';
-            return true;
-          }
-          catch { return 'Enter a valid URL.'; }
-        },
-        required: false
-      }, { input, output });
-      destination.url = url || fallback;
-      const parsedAdtUrl = new URL(destination.url);
-      if (parsedAdtUrl.protocol === 'https:' && isIP(parsedAdtUrl.hostname)) {
-        print(output, formatStatus('The ADT URL uses an IP address. Setup will inspect the SAP HTTPS certificate and can enable TLS self-healing automatically; certificate validation remains enabled.', 'warning', output, 'TLS self-heal'));
-        let discoveredNames = [];
-        try { discoveredNames = await discoverCertificateDnsNames(destination.url); }
-        catch { discoveredNames = []; }
-        if (discoveredNames.length) {
-          const preview = discoveredNames.slice(0, 5).join(', ');
-          const answer = await textPrompt({
-            message: `Use discovered certificate DNS name${discoveredNames.length === 1 ? '' : 's'} for ${promptLabel}: ${preview}${discoveredNames.length > 5 ? ', ...' : ''}? (y/Enter=yes, n=no)`,
-            placeholder: 'y',
-            required: false,
-            validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
-          }, { input, output });
-          if (!/^n(?:o)?$/i.test(String(answer || '').trim())) {
-            destination.tlsServerNames = discoveredNames;
-            destination.tlsServerName = discoveredNames[0];
-          }
-        } else {
-          print(output, formatStatus('No DNS subjectAltName entries could be read from the SAP HTTPS certificate. TLS self-healing was not configured automatically.', 'warning', output, 'TLS self-heal'));
-        }
-      }
-      const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
-      destination.authentication = ['windows-sso', 'windows-credential-ui', 'windows-sso-basic-fallback'].includes(authMode) ? 'WindowsSSO' : 'Basic';
-      destination.authMode = authMode;
-      for (const client of clients) {
-        const name = localClientDestinationName(destination, client, { multipleClients: clients.length > 1, duplicateSystemName });
-        const localDestination = { ...destination, name, serverName: name, client };
-        const userInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        const passwordInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        const credentialInputs = [
-          { id: userInputId, type: 'promptString', description: `SAP user for ${localDestination.name}` },
-          { id: passwordInputId, type: 'promptString', description: `SAP password for ${localDestination.name}`, password: true }
-        ];
-        if (authMode === 'windows-sso') {
-          localDestination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
-          localDestination.inputs = [];
-        } else if (authMode === 'windows-credential-ui') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'windows-sso',
-            SAP_AI_DEV_TOOLKIT_WINDOWS_CREDENTIAL_UI: 'true'
-          };
-          localDestination.inputs = [];
-        } else if (authMode === 'windows-sso-basic-fallback') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'windows-sso',
-            SAP_AUTH_FALLBACK_MODE: 'basic',
-            SAP_USER: `\${input:${userInputId}}`,
-            SAP_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        } else if (authMode === 'browser-saml') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'browser-saml',
-            SAP_BROWSER_AUTH: 'true',
-            SAP_SAML_AUTH: 'true'
-          };
-          localDestination.inputs = [];
-        } else if (authMode === 'saml-password') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'saml-password',
-            SAP_SAML_AUTH: 'true',
-            SAP_SAML_USER: `\${input:${userInputId}}`,
-            SAP_SAML_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        } else {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'basic',
-            SAP_USER: `\${input:${userInputId}}`,
-            SAP_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        }
-        expanded.push(localDestination);
-      }
-    }
-    selected = expanded;
+    const choice = await selectPrompt({
+      message: colorText('💡 No systems were detected. Configure an SAP system manually?', 'magenta', output),
+      defaultValue: 'manual',
+      choices: [
+        { name: '✍️  Start manual entry wizard (system name, ADT URL, client, login)', value: 'manual', shortcut: 'm' },
+        { name: 'Exit setup without changes', value: 'exit', shortcut: 'e' }
+      ]
+    }, { input, output });
+    if (choice !== 'manual') return await exitWithoutDestinations();
+    selected = await runManualEntryWizard({ env, input, output });
+    if (!selected.length) return await exitWithoutDestinations();
+  } else {
+    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env });
   }
 
   let sapDevelopmentServers = [];
@@ -531,6 +649,7 @@ export async function runSetup({
     const configuredCount = selected.length + sapDevelopmentServers.length;
     print(output, formatStatus(`Configured ${configuredCount} MCP server${configuredCount === 1 ? '' : 's'}${location}.`, 'success', output, isBas ? 'BAS setup' : 'Local setup'));
     printConnectionInstructions(output, result);
+    warnings.push(...(Array.isArray(result?.warnings) ? result.warnings.filter(message => typeof message === 'string') : []));
     let cleanupWarnings = [];
     const finalPath = result?.path || configPath;
     if (isBas) {

package/src/terminal-ui.mjs

@@ -213,8 +213,11 @@ export async function selectPrompt({ message, choices, defaultValue } = {}, { in
   });
 }
 
-export async function checkboxPrompt({ message, choices, required = false, shortcuts = { all: 'a' }, validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
-  if (!Array.isArray(choices) || !choices.length) return [];
+export async function checkboxPrompt({ message, choices: initialChoices, required = false, shortcuts = { all: 'a' }, actions = {}, validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
+  if (!Array.isArray(initialChoices) || !initialChoices.length) return [];
+  // Action shortcuts (for example 'm' → manual entry wizard) may append new
+  // choices while the picker is open, so the list itself stays mutable.
+  let choices = initialChoices;
   const selectable = enabledChoices(choices);
   const selected = new Set(choices.flatMap((choice, index) => choice.checked && !choice.disabled ? [index] : []));
   let cursor = firstEnabledIndex(choices);
@@ -261,6 +264,42 @@ export async function checkboxPrompt({ message, choices, required = false, short
   };
 
   return new Promise((resolve, reject) => {
+    const actionShortcuts = new Map(Object.entries(actions).filter(([shortcut, action]) => shortcut && typeof action === 'function'));
+    const actionShortcutFor = (chunk, key = {}) => {
+      if (!actionShortcuts.size) return undefined;
+      const typed = String(chunk ?? '').toLowerCase();
+      if (typed.length === 1 && actionShortcuts.has(typed)) return actionShortcuts.get(typed);
+      if (key.name && actionShortcuts.has(key.name)) return actionShortcuts.get(key.name);
+      return undefined;
+    };
+    // Running an action suspends the picker (listener detached, raw mode off),
+    // lets the action drive its own prompts on the same streams, and appends
+    // the produced items as pre-selected choices before redrawing. An aborted
+    // action (Ctrl+C in a sub-prompt) returns to the picker unchanged instead
+    // of tearing down the whole selection.
+    const runAction = async action => {
+      input.off('keypress', onKeypress);
+      if (typeof input.setRawMode === 'function') input.setRawMode(false);
+      clearRendered();
+      let appended = [];
+      try { appended = await action() || []; }
+      catch { appended = []; }
+      const added = (Array.isArray(appended) ? appended : []).filter(item => item && item.value !== undefined);
+      if (added.length) {
+        for (const item of added) {
+          choices.push({ checked: true, ...item });
+          selected.add(choices.length - 1);
+        }
+        cursor = choices.length - added.length;
+      }
+      if (typeof input.setRawMode === 'function') input.setRawMode(previousRawMode);
+      // Sub-prompts pause the stream on cleanup; resume so keypresses reach
+      // the re-attached picker listener.
+      if (typeof input.resume === 'function') input.resume();
+      input.on('keypress', onKeypress);
+      render();
+    };
+
     const cleanup = () => {
       input.off('keypress', onKeypress);
       if (typeof input.setRawMode === 'function' && previousRawMode !== undefined) input.setRawMode(previousRawMode);
@@ -289,9 +328,12 @@ export async function checkboxPrompt({ message, choices, required = false, short
         if (selected.has(cursor)) selected.delete(cursor);
         else selected.add(cursor);
       } else if (shortcuts?.all && key.name === shortcuts.all) {
-        const allSelected = selectable.every(choice => selected.has(choices.indexOf(choice)));
+        const allSelected = enabledChoices(choices).every(choice => selected.has(choices.indexOf(choice)));
         selected.clear();
-        if (!allSelected) for (const choice of selectable) selected.add(choices.indexOf(choice));
+        if (!allSelected) for (const choice of enabledChoices(choices)) selected.add(choices.indexOf(choice));
+      } else if (actionShortcutFor(_chunk, key)) {
+        void runAction(actionShortcutFor(_chunk, key));
+        return;
       } else if (key.name === 'return' || key.name === 'enter') {
         const values = [...selected].sort((a, b) => a - b).map(index => choices[index].value);
         const validation = typeof validate === 'function' ? validate(values) : true;