sap-ai-dev-toolkit 0.9.1 → 0.9.3

package/README.md

@@ -41,6 +41,14 @@ 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
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+```
+
+Prefer a persistent global install instead?
+
 ```sh
 npm install --global sap-ai-dev-toolkit
 sap-ai-dev --setup
@@ -242,17 +250,33 @@ 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 --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx` | Runs the guided setup through npm and writes generated entries that launch the pinned package through `npx`. |
+
+### 🪟 Windows notes
+
+Everything works natively on Windows — PowerShell, cmd, and Windows Terminal are all supported:
+
+- `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:
 
@@ -312,9 +336,9 @@ The same postinstall offers the bundled agents and skills for several AI coding
 
 Some current npm versions also require install hooks to be approved. If npm reports that `sap-ai-dev-toolkit`'s `postinstall` was blocked, allow it during a fresh install with `npm install --global --allow-scripts=sap-ai-dev-toolkit sap-ai-dev-toolkit`, or run `sap-ai-dev --setup` from an interactive terminal after installation.
 
-The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
+The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. Long-running steps (BAS destination discovery, ADT probes, VSP runtime provisioning, `--doctor` checks) show an animated progress line so the terminal never looks stuck; it appears only on interactive terminals and is disabled automatically on CI — set `SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION=true` to turn it off. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
 
-Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Use `--npx` to make generated destination entries start the pinned package through npm instead of relying on a global `sap-ai-dev` command; companion tools already use `npx` with their own npm packages.
+Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH`; otherwise (for example after a pure npx setup) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
 
 If a setup step is skipped or fails, rerun it from an interactive terminal:
 
@@ -325,10 +349,10 @@ sap-ai-dev --setup
 To configure without a global install, run the guided setup directly through npm:
 
 ```sh
-npx --yes --ignore-scripts --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx
+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). It writes MCP entries that launch the selected servers through npx. The entries pin the package version used during setup, and `--ignore-scripts` avoids running the install-time wizard a second time. 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, 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**.
 
 For a non-interactive installation or a platform without a published VSP asset, provide a trusted binary override:
 
@@ -423,7 +447,7 @@ 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; add `--npx` 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, 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.
 
 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.
 
@@ -833,6 +857,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
@@ -857,7 +883,7 @@ NPM_PUBLISH_TOKEN=npm_...
 - To publish a patch bump, run `npm run publish:npm -- --patch`; it updates `package.json` and `package-lock.json` before publishing. If publishing fails after the bump, retry without `--patch`.
 - npm's `prepublishOnly` hook builds the pinned VSP binaries for all platforms (including the Go toolchain if missing) and refuses to ship a tarball whose `dist/checksums.txt` does not list all five assets; it guards `npm run publish:npm` and a plain `npm publish` alike. Pass `--skip-build` to republish an already-built `dist/` without rebuilding.
 - Preview the package without publishing, changing its version, or building with `npm run publish:npm -- --dry-run`.
-- GitHub Actions runs the test suite on pushes to `main` and pull requests. A push to `main` that changes the `package.json` version runs the same checks, builds the VSP binaries, and publishes that version to npm.
+- GitHub Actions runs the test suite on pushes to `main` and pull requests. A push to `main` that changes the `package.json` version runs the same checks, builds the VSP binaries, publishes that version to npm, and creates a `v<version>` GitHub release with generated notes.
 - The publish workflow uses the `NPM_PUBLISH_TOKEN` GitHub repository secret. Verify it with `gh secret list`; the token value is never stored in the repository.
 
 The token is not printed or stored in the repository.

package/dist/checksums.txt

@@ -1,5 +1,5 @@
-a5b602573f54ce3d03d161aaaeb78559fd73bd51f2ae9a3b7549cee1ddc3fbf6  vsp-linux-x64
-2e336e2999c3654e5eb1e3a8bb42616eb5d5e422ab7ae74ffbff4634be45189d  vsp-linux-arm64
-afc7fd0f2e40ae5ebfcd3ddb8ac3cb7e7501b2b66d76ac96e3b6054b09366bb5  vsp-darwin-x64
-2d28a870c4a006900eec245384b4bbc2e84651e0ba911cca6107c132ace73575  vsp-darwin-arm64
-7d0189aa7ff936a145b0e3f15bffce8de5aebc252465a720edc3a9b122bd2a28  vsp-win32-x64.exe
+85333f1ac7cbc25bc10a938cea5712b43d1c7b241911f19c6794f897dbcb589c  vsp-linux-x64
+68cd2b79e7cda145135f9f516b6ba76f33839bc9226bbf58ea015ff2442b4b2d  vsp-linux-arm64
+62fd8cd8eba8d61e36813c098938a2479af68047fd2fa1c85782edb4d4b5261b  vsp-darwin-x64
+71eb9e64e292e3ac83a2ab6a630367cfb0d79fe465d62ad1cfb05ef8c6c2b6e7  vsp-darwin-arm64
+952a6d5a90265fb6a6b3494d01a5d143fd7c471f7ce560bed200c399522b180f  vsp-win32-x64.exe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",
@@ -17,6 +17,7 @@
   },
   "bin": {
     "sap-ai-dev": "src/launcher.mjs",
+    "sap-ai-dev-toolkit": "src/launcher.mjs",
     "sap-ai-hana": "src/hana-inspector.mjs"
   },
   "scripts": {

package/scripts/postinstall.mjs

@@ -9,7 +9,7 @@ import { installMcpServersForHarnesses } from '../src/harness-mcp-config.mjs';
 import { DEFAULT_HARNESS_IDS, HARNESSES, HARNESS_ENV_VAR, NON_INTERACTIVE_HARNESS_IDS, envHarnessSelection, harnessRoot } from '../src/harnesses.mjs';
 import { ReadStream as TTYReadStream, WriteStream as TTYWriteStream } from 'node:tty';
 import { homedir } from 'node:os';
-import { checkboxPrompt, colorText, formatStatus } from '../src/terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, startProgress } from '../src/terminal-ui.mjs';
 import { brandedEnvValue, withBrandedEnvironment } from '../src/branding.mjs';
 import { generatedServerName } from '../src/mcp-config.mjs';
 import { redactText } from '../src/redact.mjs';
@@ -232,7 +232,7 @@ async function announceSetup(result) {
     return;
   }
   if (result?.reason === 'non-tty') {
-    await announce('Destination selection was skipped because npm did not provide an interactive terminal.\nMCP config was not changed.\nRun sap-ai-dev --setup from an interactive BAS terminal, or run npx --yes --ignore-scripts --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx.', 'warning');
+    await announce('Destination selection was skipped because npm did not provide an interactive terminal.\nMCP config was not changed.\nRun sap-ai-dev --setup from an interactive terminal, or run npx --yes --ignore-scripts sap-ai-dev-toolkit --setup from any terminal.', 'warning');
     return;
   }
   if (result?.reason === 'no-destinations') {
@@ -304,11 +304,15 @@ async function main() {
     if (brandedEnvValue(runtimeEnv, 'BINARY')) {
       await announce('Using the SAP_AI_DEV_TOOLKIT_BINARY override.', 'info');
     } else {
-      await announce('Preparing the pinned VSP runtime for this platform.', 'progress');
+      // 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 });
+        stopBinaryProgress();
         await announce('Pinned VSP binary installed and ready.', 'success');
       } catch (error) {
+        stopBinaryProgress();
         throw new Error(`VSP binary provisioning failed: ${error.message}`);
       }
     }

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/launcher.mjs

@@ -7,13 +7,14 @@ import { discoverDestinations, remediation, slugifyDestination, statusRows } fro
 import { discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig, repairManagedMcpConfig } from './mcp-config.mjs';
+import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createWindowsSsoAdtProxy } from './windows-sso-adt-proxy.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
 import { withBrandedEnvironment } from './branding.mjs';
 import { redactText } from './redact.mjs';
+import { startProgress } from './terminal-ui.mjs';
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
 const runtimeEnv = withBrandedEnvironment(process.env);
@@ -53,7 +54,9 @@ function doctorRow(name, stage, status, detail) {
 
 async function runDoctor(destinations) {
   const checks = [];
+  const stopProgress = startProgress(destinations.length === 1 ? `Checking ${destinations[0]?.name || 'destination'}` : `Checking ${destinations.length} destinations`, { output: process.stderr, label: 'Doctor' });
   if (!destinations.length) {
+    stopProgress();
     return { ok: false, destinations: 0, checks: [doctorRow('-', 'destination discovery', 'failed', 'No destinations were found. Check H2O_URL or the configured Cloud Foundry destination.')] };
   }
   let binary;
@@ -76,6 +79,7 @@ async function runDoctor(destinations) {
     checks.push(doctorRow('-', 'MCP config repair', 'failed', redactText(error.message || error).slice(0, 300)));
   }
   for (const destination of destinations) {
+    stopProgress.update(`Checking ${destination.name}: ADT probe, VSP startup, tools/list`);
     const probe = destination.probe;
     const probeStatus = !probe || probe.status === 'skipped' ? 'skipped' : (probe.available === true ? 'passed' : 'failed');
     checks.push(doctorRow(destination.name, 'ADT probe', probeStatus, probe?.status || 'No BAS ADT probe was supplied; GetSystemInfo will check the route.'));
@@ -126,6 +130,7 @@ async function runDoctor(destinations) {
     }
   }
   const required = checks.filter(check => check.status !== 'skipped');
+  stopProgress();
   return { ok: required.every(check => check.status === 'passed'), destinations: destinations.length, checks };
 }
 
@@ -253,11 +258,17 @@ async function main() {
   if (doctor) {
     let report;
     try {
-      const destinations = runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry'
-        ? [await resolveConfiguredCloudFoundryDestination({ env: runtimeEnv })]
-        : (runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'sap-gui-local'
-          ? [await configuredLocalSapGuiDestination(runtimeEnv)]
-          : await discoverForCommand());
+      const stopDiscoveryProgress = startProgress('Discovering SAP destinations', { output: process.stderr, env: runtimeEnv, label: 'Doctor' });
+      let destinations;
+      try {
+        destinations = runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry'
+          ? [await resolveConfiguredCloudFoundryDestination({ env: runtimeEnv })]
+          : (runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'sap-gui-local'
+            ? [await configuredLocalSapGuiDestination(runtimeEnv)]
+            : await discoverForCommand());
+      } finally {
+        stopDiscoveryProgress();
+      }
       report = await runDoctor(destinations);
     } catch (error) {
       report = { ok: false, destinations: 0, checks: [doctorRow('-', 'destination discovery', 'failed', redactText(error.message || error).slice(0, 300))] };
@@ -272,17 +283,26 @@ async function main() {
       includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools')
     };
     if (hasFlag('--npx')) {
+      // Windows has no npx.exe, so generated entries there launch through
+      // `cmd /c npx`; other platforms use npx directly.
+      const launcher = npxMcpLauncher();
       setupOptions.install = (selected, options) => installMcpConfig(selected, {
         ...options,
-        command: 'npx',
-        args: ['--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
+        command: launcher.command,
+        args: [...launcher.prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
       });
     }
     await runSetup(setupOptions);
     return;
   }
   if (check || list) {
-    const destinations = await discoverForCommand();
+    const stopProgress = startProgress('Discovering SAP destinations and probing ADT endpoints', { output: process.stderr, env: runtimeEnv });
+    let destinations;
+    try {
+      destinations = await discoverForCommand();
+    } finally {
+      stopProgress();
+    }
     const statuses = statusRows(destinations);
     if (list && hasFlag('--json')) json(statuses);
     else for (const row of statuses) console.error(`${row.name}: client=${row.client} authentication=${row.authentication} probe=${row.probe}`);
@@ -319,11 +339,15 @@ async function main() {
       return;
     }
     const binary = await binaryOrError();
-    // Windows cannot exec a .js/.mjs file directly; route JavaScript entries
+    // Windows cannot exec .js/.mjs files directly; route JavaScript entries
     // (test fixtures) through the current Node binary like MCPProxy does.
+    // Windows .cmd/.bat shims (e.g. a SAP_AI_DEV_TOOLKIT_BINARY override)
+    // must go through cmd /c; Node refuses to spawn batch files directly.
     const spawnTarget = /\.(?:mjs|cjs|js)$/i.test(binary)
       ? { command: process.execPath, prefixArgs: [binary] }
-      : { command: binary, prefixArgs: [] };
+      : (/\.(?:cmd|bat)$/i.test(binary)
+        ? { command: 'cmd', prefixArgs: ['/c', binary] }
+        : { command: binary, prefixArgs: [] });
     const child = spawn(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], { env: runtimeEnv, stdio: 'inherit' });
     process.once('SIGINT', () => child.kill('SIGINT'));
     process.once('SIGTERM', () => child.kill('SIGTERM'));
@@ -336,7 +360,13 @@ async function main() {
     return;
   }
 
-  const discovered = await discoverDestinations({ env: runtimeEnv });
+  const stopProgress = startProgress('Discovering BAS destinations and probing ADT endpoints', { output: process.stderr, env: runtimeEnv });
+  let discovered;
+  try {
+    discovered = await discoverDestinations({ env: runtimeEnv });
+  } finally {
+    stopProgress();
+  }
   for (const destination of discovered) logLine(probeDiagnostic(destination));
   const destinations = discovered;
   if (!destinations.length) {

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']
@@ -98,6 +119,44 @@ export async function resolveMcpServerCommand(env = process.env) {
   return 'sap-ai-dev';
 }
 
+// Windows ships npx as npx.cmd, not npx.exe: MCP hosts spawn the configured
+// command directly without shell PATH resolution, so npx-launched servers
+// must route through `cmd /c npx` there (the form VS Code, Claude Code, and
+// Cursor document for Windows). Other platforms run npx directly.
+export function npxMcpLauncher(platform = process.platform) {
+  return platform === 'win32'
+    ? { command: 'cmd', prefixArgs: ['/c', 'npx'] }
+    : { command: 'npx', prefixArgs: [] };
+}
+
+// Normalizes the argument list of npx-launched entries, whether written as
+// `npx ...` or the Windows `cmd /c npx ...` form; returns null when the entry
+// is not npx-launched.
+function npxLaunchArgs(entry) {
+  const args = Array.isArray(entry?.args) ? entry.args.map(String) : [];
+  if (entry?.command === 'npx') return args;
+  const commandName = typeof entry?.command === 'string'
+    ? entry.command.slice(Math.max(entry.command.lastIndexOf('/'), entry.command.lastIndexOf('\\')) + 1)
+    : '';
+  if (/^cmd(?:\.exe)?$/i.test(commandName) && args[0]?.toLowerCase() === '/c' && /^npx(?:\.cmd)?$/i.test(args[1] || '')) {
+    return args.slice(2);
+  }
+  return null;
+}
+
+// Resolves how generated destination entries launch the toolkit: the global
+// sap-ai-dev command when it is on PATH, otherwise the pinned package
+// through npx (routed through cmd /c on Windows) so entries written by a
+// pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
+async function resolveLauncherInstallCommand(env) {
+  const resolved = await resolveMcpServerCommand(env);
+  if (resolved !== 'sap-ai-dev') return { command: resolved, args: null };
+  const { command, prefixArgs } = npxMcpLauncher();
+  const selfVersion = await runningPackageVersion();
+  const packageSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : 'sap-ai-dev-toolkit';
+  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=${packageSpec}`, 'sap-ai-dev'] };
+}
+
 export async function resolveMcpConfigPath(env = process.env) {
   const configuredPath = [env.SAP_AI_DEV_MCP_CONFIG, brandedEnvValue(env, 'MCP_CONFIG')]
     .find(value => typeof value === 'string' && value.length > 0);
@@ -138,16 +197,17 @@ export function generatedDestinationServerName(destination) {
   return generatedServerName(destination?.source === 'cloud-foundry' ? destination.serverName : destination?.name);
 }
 
-export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx' } = {}) {
+export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx', platform = process.platform } = {}) {
   const selected = new Set(serverIds);
   const entries = Object.create(null);
+  const launcher = packageManager === 'npx' ? npxMcpLauncher(platform) : { command: packageManager, prefixArgs: [] };
   for (const server of SAP_DEVELOPMENT_MCP_SERVERS) {
     if (!selected.has(server.id)) continue;
     const packageSpec = packageVersions[server.id] || packageVersions[server.packageName] || server.packageName;
     entries[server.id] = {
       type: 'stdio',
-      command: packageManager,
-      args: ['--yes', ...(server.ignoreScripts ? ['--ignore-scripts'] : []), `--package=${packageSpec}`, server.bin],
+      command: launcher.command,
+      args: [...launcher.prefixArgs, '--yes', ...(server.ignoreScripts ? ['--ignore-scripts'] : []), `--package=${packageSpec}`, server.bin],
       BAS_EXT: 'true',
       BAS_EXT_KIND: COMPANION_SERVER_KIND,
       displayName: server.name,
@@ -232,16 +292,14 @@ function isPackageLauncher(entry) {
   const legacyCommand = legacyCommands.has(entry?.command) || legacyCommands.has(commandName);
   const currentPackages = [/^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/];
   const legacyPackages = [/^--package=bas-mcp-addon(?:@[^/]+)?$/];
-  const hasPackage = patterns => Array.isArray(entry?.args)
-    && entry.args.some(argument => typeof argument === 'string' && patterns.some(pattern => pattern.test(argument)));
-  const currentNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => currentCommands.has(argument))
-    && hasPackage(currentPackages);
-  const legacyNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => legacyCommands.has(argument))
-    && hasPackage(legacyPackages);
+  const hasPackage = (arguments_, patterns) => arguments_.some(argument => patterns.some(pattern => pattern.test(argument)));
+  const npxArgs = npxLaunchArgs(entry);
+  const currentNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => currentCommands.has(argument))
+    && hasPackage(npxArgs, currentPackages);
+  const legacyNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => legacyCommands.has(argument))
+    && hasPackage(npxArgs, legacyPackages);
   // Current launchers are treated as managed only when tagged by this add-on.
   // Some early bas-mcp-addon entries were not tagged with BAS_EXT, though, and
   // leaving them behind keeps advertising the old full VSP surface (~159 tools).
@@ -264,10 +322,10 @@ function isManagedBasDestinationEntry(entry) {
     ? entry.command.slice(Math.max(entry.command.lastIndexOf('/'), entry.command.lastIndexOf('\\')) + 1).replace(/\.(?:cmd|exe)$/i, '')
     : '';
   const currentCommand = currentCommands.has(entry?.command) || currentCommands.has(commandName);
-  const currentNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => currentCommands.has(argument))
-    && entry.args.some(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument));
+  const npxArgs = npxLaunchArgs(entry);
+  const currentNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => currentCommands.has(argument))
+    && npxArgs.some(argument => /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument));
   return entry?.BAS_EXT === 'true'
     && (currentCommand || currentNpxLauncher)
     && typeof destinationValue(entry?.env) === 'string'
@@ -299,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()
+    });
+  }
+  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'); }
   }
-  return { ...config, servers: config.servers || {} };
+  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}`);
@@ -343,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 = {
@@ -356,12 +568,18 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
       if (input?.id) generatedInputs.set(input.id, input);
     }
   }
-  const launcherCommand = options.command || (destinations.length ? await resolveMcpServerCommand(env) : null);
+  let launcherCommand = options.command || null;
+  let launcherArgs = options.command ? options.args : null;
+  if (!launcherCommand && destinations.length) {
+    const resolved = await resolveLauncherInstallCommand(env);
+    launcherCommand = resolved.command;
+    launcherArgs = resolved.args;
+  }
   if (launcherCommand) {
     for (const entry of Object.values(generated)) {
       if (isCompanionServer(entry)) continue;
       entry.command = launcherCommand;
-      if (options.command && options.args?.length) entry.args = [...options.args];
+      if (launcherArgs?.length) entry.args = [...launcherArgs];
     }
   }
   const servers = Object.create(null);
@@ -391,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 } = {}) {
@@ -406,7 +624,7 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
   const config = await readConfig(configPath);
   const managedEntries = Object.values(config.servers).filter(isManagedBasDestinationEntry).length;
   if (!basDestinations.size) return { path: configPath, changed: false, repaired: 0, managedEntries };
-  const localCommand = await resolveMcpServerCommand(env);
+  const localLauncher = await resolveLauncherInstallCommand(env);
   let repaired = 0;
   for (const [serverName, entry] of Object.entries(config.servers)) {
     if (!isManagedBasDestinationEntry(entry)) continue;
@@ -430,14 +648,16 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
     delete nextEnvironment.BAS_VSP_DESTINATION;
     delete nextEnvironment.BAS_VSP_DESTINATION_SOURCE;
     const nextEntry = { ...entry, type: 'stdio', env: nextEnvironment, BAS_EXT: 'true' };
-    if (entry.command === 'npx') {
+    if (npxLaunchArgs(entry) !== null) {
       if (packageVersion && Array.isArray(entry.args)) {
         nextEntry.args = entry.args.map(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument)
           ? `--package=sap-ai-dev-toolkit@${packageVersion}`
           : argument);
       }
     } else {
-      nextEntry.command = localCommand;
+      nextEntry.command = localLauncher.command;
+      if (localLauncher.args) nextEntry.args = [...localLauncher.args];
+      else delete nextEntry.args;
     }
     if (expectedName === serverName) {
       if (JSON.stringify(nextEntry) === JSON.stringify(entry)) continue;
@@ -454,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/mcp-proxy.mjs

@@ -200,9 +200,12 @@ export function childArguments(destination, env = process.env) {
 
 // Windows cannot exec a .js/.mjs file directly (no shebang support), so test
 // fixtures written in JavaScript are launched through the current Node binary.
-// The production VSP binary is a native executable and is unaffected.
+// The production VSP binary is a native executable and is unaffected; a
+// Windows .cmd/.bat override needs cmd /c because Node refuses to spawn
+// batch files directly (EINVAL since the CVE-2024-27980 hardening).
 function spawnCommand(binary) {
   if (/\.(?:mjs|cjs|js)$/i.test(binary)) return [process.execPath, binary];
+  if (/\.(?:cmd|bat)$/i.test(binary) && process.platform === 'win32') return ['cmd', '/c', binary];
   return [binary];
 }
 

package/src/setup.mjs

@@ -2,7 +2,7 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { platform } from 'node:os';
 import { isIP } from 'node:net';
-import { checkboxPrompt, colorText, formatStatus, selectPrompt, textPrompt } from './terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, selectPrompt, startProgress, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { defaultAdtUrl, discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
@@ -237,15 +237,21 @@ export async function runSetup({
     return { skipped: true, reason: 'non-tty' };
   }
   print(output, '');
-  print(output, formatStatus(isBas ? 'Contacting BAS to discover destinations; this may take a moment.' : 'Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
+  if (!isBas) print(output, formatStatus('Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
 
   let destinations = [];
   if (isBas) {
     let basDestinations;
+    // BAS discovery probes every destination's ADT endpoint (up to a 5s
+    // timeout each); the animated progress line keeps the terminal visibly
+    // alive from the first moment instead of looking stuck.
+    const stopDiscoveryProgress = startProgress('Contacting BAS to discover destinations', { output, env, label: 'Setup' });
     try {
       basDestinations = await discover({ env: { ...env, SAP_AI_DEV_TOOLKIT_DESTINATION: '' } });
     } catch (error) {
       throw new Error(`BAS discovery failed: ${error.message}`);
+    } finally {
+      stopDiscoveryProgress();
     }
     destinations = basDestinations.map(safeBasDestination);
   } else {
@@ -525,6 +531,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

@@ -401,3 +401,43 @@ export async function textPrompt({ message, secret = false, required = true, pla
     }
   });
 }
+
+// Animated progress line for long-running steps (destination discovery,
+// ADT probes, VSP binary provisioning). TTY outputs get spinner frames on an
+// unref'd timer that starts after a short delay, so steps that finish quickly
+// never flash anything. Non-TTY outputs (pipes, MCP hosts, --json callers,
+// CI) stay completely silent so machine consumers never see progress noise.
+// Returns stop(); on a TTY, stop() clears the line so it never pollutes
+// scrollback. stop.update(message) retargets the label while running (for
+// example per destination during --doctor).
+export function startProgress(initialMessage, { output = process.stdout, env = process.env, label = 'sap-ai-dev-toolkit' } = {}) {
+  const noop = Object.assign(() => {}, { update: () => {} });
+  if (!output || typeof output.write !== 'function') return noop;
+  const animationDisabled = env.TERM === 'dumb' || env.CI || env.SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION === 'true';
+  if (!output.isTTY || !Number.isFinite(output.columns) || animationDisabled) return noop;
+  let message = String(initialMessage);
+  let index = 0;
+  let active = false;
+  let interval;
+  const render = () => {
+    active = true;
+    index += 1;
+    const columns = Math.max(20, output.columns || 80);
+    const dots = `.${'.'.repeat(index % 3)}${' '.repeat(2 - index % 3)}`;
+    const line = `${label}: ${message} ${dots}`.slice(0, Math.max(1, columns - 1));
+    output.write(`\r\u001b[2K${line}`);
+  };
+  const delay = setTimeout(() => {
+    render();
+    interval = setInterval(render, 120);
+    if (typeof interval.unref === 'function') interval.unref();
+  }, 150);
+  if (typeof delay.unref === 'function') delay.unref();
+  const stop = () => {
+    clearTimeout(delay);
+    if (interval) clearInterval(interval);
+    if (active) output.write('\r\u001b[2K');
+  };
+  stop.update = next => { message = String(next); };
+  return stop;
+}