sap-ai-dev-toolkit 0.4.5 → 0.5.5

package/src/bas-discovery.mjs

@@ -122,7 +122,7 @@ function proxyDispatcher(target, env) {
   const url = new URL(target);
   const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
   const httpProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.http_proxy ?? env.HTTP_PROXY ?? '');
-  const httpsProxy = env.https_proxy ?? env.HTTPS_PROXY ?? '';
+  const httpsProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.https_proxy ?? env.HTTPS_PROXY ?? '');
   const proxy = url.protocol === 'https:' ? httpsProxy || httpProxy : httpProxy;
   const noProxy = env.no_proxy ?? env.NO_PROXY ?? '';
   if (!proxy || proxyBypasses(url, noProxy)) return undefined;
@@ -203,11 +203,21 @@ export async function discoverDestinations(options = {}) {
   const configuredProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.HTTP_PROXY ?? env.http_proxy);
   const proxyUrl = configuredProxy !== undefined ? configuredProxy : DEFAULT_PROXY;
   const skipProbe = String(brandedEnvValue(env, 'SKIP_PROBE') || '').toLowerCase() === 'true' || options.skipProbe;
-  const result = [];
-  for (const destination of normalized.sort((a, b) => a.name.localeCompare(b.name))) {
-    const probe = await probeADT(destination, { ...options, proxyUrl, skipProbe });
-    result.push({ ...destination, probe });
-  }
+  const sorted = normalized.sort((a, b) => a.name.localeCompare(b.name));
+  // Probes run in parallel so startup and setup pay one probe round trip
+  // instead of one per destination; the pool is capped to avoid saturating
+  // the BAS proxy with large destination counts. Workers claim destinations
+  // in index order (synchronously until the first await), which keeps the
+  // probe invocation and result order deterministic.
+  const result = new Array(sorted.length);
+  let cursor = 0;
+  const probeWorker = async () => {
+    while (cursor < sorted.length) {
+      const index = cursor++;
+      result[index] = { ...sorted[index], probe: await probeADT(sorted[index], { ...options, proxyUrl, skipProbe }) };
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(8, sorted.length) }, () => probeWorker()));
   return result;
 }
 

package/src/launcher.mjs

@@ -3,9 +3,9 @@ import { spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverDestinations, remediation, statusRows } from './bas-discovery.mjs';
+import { discoverDestinations, remediation, slugifyDestination, statusRows } from './bas-discovery.mjs';
 import { findBinary } from './binary.mjs';
-import { MCPProxy } from './mcp-proxy.mjs';
+import { MCPProxy, TOOL_NAME_PREFIX } from './mcp-proxy.mjs';
 import { installMcpConfig, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
@@ -17,6 +17,9 @@ const runtimeEnv = withBrandedEnvironment(process.env);
 
 function hasFlag(name) { return process.argv.slice(2).includes(name); }
 function json(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
+// Timestamped stderr lines so MCP server output shows when each event
+// happened, not just that it did.
+function logLine(message) { console.error(`[${new Date().toISOString()}] ${message}`); }
 
 function usage() {
   return [
@@ -60,7 +63,11 @@ async function runDoctor(destinations) {
 
 
   try {
-    const repair = await repairManagedMcpConfig(destinations, { env: runtimeEnv, discoveryComplete: true });
+    const repair = await repairManagedMcpConfig(destinations, {
+      env: runtimeEnv,
+      discoveryComplete: true,
+      packageVersion: pkg.version
+    });
     const detail = repair.skipped
       ? repair.skipped
       : `${repair.repaired} managed BAS entr${repair.repaired === 1 ? 'y' : 'ies'} repaired; ${repair.managedEntries || 0} managed BAS entries recognized`;
@@ -104,10 +111,11 @@ async function runDoctor(destinations) {
       const listed = await proxy.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
       if (listed?.error) throw new Error(listed.error.message || 'MCP tools/list failed');
       const tools = listed.result?.tools || [];
-      const localNames = new Set(['LintABAP', 'GetApplicationLog', 'PrepareABAPChangeSet', 'ApplyABAPChangeSet', 'CheckTransportReadiness', 'PlanABAPCloudMigration', 'GenerateRAPRegressionSuite', 'RunRAPRegressionSuite']);
-      const upstreamCount = tools.filter(tool => !localNames.has(tool.name.slice(tool.name.indexOf('__') + 2))).length;
+      const toolPrefix = `${TOOL_NAME_PREFIX}${slugifyDestination(destination.name)}_`;
+      const localSegments = new Set(['lint_abap', 'get_application_log', 'prepare_abap_change_set', 'apply_abap_change_set', 'check_transport_readiness', 'plan_abap_cloud_migration', 'generate_rap_regression_suite', 'run_rap_regression_suite']);
+      const upstreamCount = tools.filter(tool => tool.name.startsWith(toolPrefix) && !localSegments.has(tool.name.slice(toolPrefix.length))).length;
       checks.push(doctorRow(destination.name, 'MCP tools/list', upstreamCount ? 'passed' : 'failed', `${upstreamCount} VSP tools and ${tools.length} total MCP tools returned; chat-picker binding is host-managed`));
-      const systemInfo = tools.find(tool => tool.name.endsWith('__GetSystemInfo'));
+      const systemInfo = tools.find(tool => tool.name === `${toolPrefix}get_system_info`);
       if (!systemInfo) {
         checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'GetSystemInfo is not exposed by this VSP mode.'));
       } else {
@@ -116,7 +124,7 @@ async function runDoctor(destinations) {
           let session;
           let preflightError;
           try {
-            session = await relayedDestination.relay.probeCsrfSession('/sap/bc/adt/datapreview/freestyle');
+            session = await relayedDestination.relay.probeCsrfSession();
           } catch (error) {
             preflightError = redactText(error.message || error).slice(0, 250);
           }
@@ -254,7 +262,7 @@ async function main() {
     let proxy;
     try {
       const binary = await binaryOrError();
-      proxy = new MCPProxy({ binary, destinations: [destination], env: runtimeEnv, log: message => console.error(message) });
+      proxy = new MCPProxy({ binary, destinations: [destination], env: runtimeEnv, log: logLine });
       const shutdown = signal => { void proxy.close().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143)); };
       process.once('SIGINT', () => shutdown('SIGINT'));
       process.once('SIGTERM', () => shutdown('SIGTERM'));
@@ -279,19 +287,21 @@ async function main() {
   }
 
   const discovered = await discoverDestinations({ env: runtimeEnv });
-  for (const destination of discovered) console.error(probeDiagnostic(destination));
+  for (const destination of discovered) logLine(probeDiagnostic(destination));
   const destinations = await enrichWithStoredCredentials(discovered, runtimeEnv);
   if (!destinations.length) {
-    console.error('[sap-ai-dev] destination discovery returned no named BAS destinations');
+    logLine('[sap-ai-dev] destination discovery returned no named BAS destinations');
     throw new Error(remediation);
   }
   const binary = await binaryOrError();
+  logLine(`[sap-ai-dev] sap-ai-dev-toolkit v${pkg.version} (node ${process.version}, pid ${process.pid})`);
+  logLine(`[sap-ai-dev] VSP binary: ${binary}`);
   for (const destination of destinations) {
-    if (destination.credentials?.mode === 'bas-tunnel') console.error(`[sap-ai-dev] ${destination.name}: Basic credentials enabled through the BAS proxy tunnel`);
-    else if (destination.credentials?.host) console.error(`[sap-ai-dev] ${destination.name}: direct connect enabled through stored credentials`);
+    if (destination.credentials?.mode === 'bas-tunnel') logLine(`[sap-ai-dev] ${destination.name}: Basic credentials enabled through the BAS proxy tunnel`);
+    else if (destination.credentials?.host) logLine(`[sap-ai-dev] ${destination.name}: direct connect enabled through stored credentials`);
   }
-  console.error(`[sap-ai-dev] starting MCP proxy for ${destinations.map(destination => `${destination.name} (client=${destination.client})`).join(', ')}`);
-  const proxy = new MCPProxy({ binary, destinations, env: process.env, log: message => console.error(message) });
+  logLine(`[sap-ai-dev] starting MCP proxy for ${destinations.map(destination => `${destination.name} (client=${destination.client})`).join(', ')}`);
+  const proxy = new MCPProxy({ binary, destinations, env: process.env, log: logLine });
   const shutdown = signal => { void proxy.close().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143)); };
   process.once('SIGINT', () => shutdown('SIGINT'));
   process.once('SIGTERM', () => shutdown('SIGTERM'));

package/src/mcp-config.mjs

@@ -4,6 +4,7 @@ import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/pr
 import { homedir } from 'node:os';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { brandedEnvValue } from './branding.mjs';
+import { slugifyDestination } from './bas-discovery.mjs';
 
 const LEGACY_MCP_SERVER_PREFIXES = ['sapAiDev_', 'basVspMcp_'];
 const COMPANION_SERVER_KIND = 'sap-development-companion';
@@ -95,8 +96,10 @@ export async function resolveMcpConfigPath(env = process.env) {
   return candidates[0];
 }
 
+// Server entry names are lowercase slugs: VS Code/BAS derive chat tool
+// references from the server name and only bind lowercase identifiers.
 export function generatedServerName(destinationName) {
-  return String(destinationName);
+  return slugifyDestination(destinationName);
 }
 
 export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx' } = {}) {
@@ -128,7 +131,7 @@ export function buildMcpEntries(destinations, env = process.env) {
   for (const destination of selected) {
     const isCf = destination.source === 'cloud-foundry';
     const name = generatedServerName(isCf ? destination.serverName : destination.name);
-    if (Object.hasOwn(entries, name)) throw new Error(`Duplicate MCP destination server name: ${name}`);
+    if (Object.hasOwn(entries, name)) throw new Error(`Duplicate MCP destination server name: ${name} (two destination names normalize to the same lowercase server name)`);
     const entryEnv = {
       H2O_URL: String(h2oUrl),
       SAP_ALLOW_TRANSPORTABLE_EDITS: 'true'
@@ -322,7 +325,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   return { path, servers: generated };
 }
 
-export async function repairManagedMcpConfig(discoveredDestinations, { env = process.env, path, discoveryComplete = false } = {}) {
+export async function repairManagedMcpConfig(discoveredDestinations, { env = process.env, path, discoveryComplete = false, packageVersion } = {}) {
   const configPath = path || await resolveMcpConfigPath(env);
   if (!discoveryComplete) {
     return { path: configPath, changed: false, repaired: 0, skipped: 'Destination discovery was incomplete.' };
@@ -334,20 +337,46 @@ 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);
   let repaired = 0;
   for (const [serverName, entry] of Object.entries(config.servers)) {
     if (!isManagedBasDestinationEntry(entry)) continue;
     const destinationName = destinationValue(entry.env);
-    if (generatedServerName(destinationName) !== serverName) continue;
+    const expectedName = generatedServerName(destinationName);
     const destination = basDestinations.get(destinationName);
     if (!destination) continue;
-    const expected = buildMcpEntries([destination], env)[serverName];
+    if (expectedName !== serverName) {
+      // Legacy mixed-case entries migrate to the normalized lowercase key.
+      // A user-owned entry on the target key blocks the rename; merging is
+      // only safe onto another managed entry for the same destination.
+      const target = config.servers[expectedName];
+      const targetMergable = isManagedBasDestinationEntry(target) && destinationValue(target.env) === destinationName;
+      if (Object.hasOwn(config.servers, expectedName) && !targetMergable) continue;
+    }
+    const expected = buildMcpEntries([destination], env)[expectedName];
     const nextEnvironment = { ...entry.env, ...expected.env };
+    if (Object.hasOwn(entry.env, 'SAP_ALLOW_TRANSPORTABLE_EDITS')) {
+      nextEnvironment.SAP_ALLOW_TRANSPORTABLE_EDITS = entry.env.SAP_ALLOW_TRANSPORTABLE_EDITS;
+    }
     delete nextEnvironment.BAS_VSP_DESTINATION;
     delete nextEnvironment.BAS_VSP_DESTINATION_SOURCE;
     const nextEntry = { ...entry, type: 'stdio', env: nextEnvironment, BAS_EXT: 'true' };
-    if (JSON.stringify(nextEntry) === JSON.stringify(entry)) continue;
-    config.servers[serverName] = nextEntry;
+    if (entry.command === 'npx') {
+      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;
+    }
+    if (expectedName === serverName) {
+      if (JSON.stringify(nextEntry) === JSON.stringify(entry)) continue;
+      config.servers[serverName] = nextEntry;
+    } else {
+      delete config.servers[serverName];
+      config.servers[expectedName] = nextEntry;
+    }
     repaired += 1;
   }
 

package/src/mcp-proxy.mjs

@@ -8,6 +8,9 @@ import { createBasDestinationRelay } from './bas-destination-relay.mjs';
 
 const JSONRPC = '2.0';
 const FORWARDED_METHODS = new Set(['ping', 'resources/list', 'resources/read', 'resources/templates/list', 'prompts/list', 'completion/complete', 'logging/setLevel']);
+// MCP log levels in spec order; a notification is emitted when its level is
+// at or above the client's logging/setLevel choice (default info).
+const MCP_LOG_LEVELS = ['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'];
 const APPLICATION_LOG_PARAMETERS = [
   'program',
   'user',
@@ -94,6 +97,25 @@ function exposeVspTool(tool) {
   return PUBLIC_VSP_TOOLS.has(tool?.name);
 }
 
+// Public tool names are lowercase snake_case. BAS/VS Code chat tool references
+// are lowercase-only, so mixed-case names never bind in the tools picker even
+// when the server itself starts and lists tools.
+export function snakeCaseName(value) {
+  return String(value)
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+// Every generated tool is prefixed with the destination it targets:
+// sap_system_<destination-slug>_<tool>, for example
+// sap_system_actions4d_get_table_contents.
+export const TOOL_NAME_PREFIX = 'sap_system_';
+
+function publicToolSegment(name) {
+  return snakeCaseName(name) || String(name).toLowerCase();
+}
+
 function applicationLogArguments(arguments_ = {}) {
   const filters = arguments_ && typeof arguments_ === 'object' && !Array.isArray(arguments_) ? arguments_ : {};
   const params = { type: 'application_log' };
@@ -200,6 +222,9 @@ class Child {
   onMessage(message) {
     if (message.id === undefined || message.id === null) {
       if (message.method?.startsWith('notifications/')) {
+        // An upstream tool-surface change invalidates this child's cached
+        // listing; the proxy also drops its merged cache when forwarding.
+        if (message.method === 'notifications/tools/list_changed') this.toolsPromise = undefined;
         try { this.options.onNotification?.(message); }
         catch (error) { this.options.log?.(`[${this.destination.name}] child notification forwarding failed: ${diagnosticText(error.message)}`); }
       }
@@ -215,6 +240,8 @@ class Child {
   fail(error) {
     if (this.exited) return;
     this.exited = true;
+    // A dead child must not keep serving its last successful tool listing.
+    this.toolsPromise = undefined;
     for (const pending of this.pending.values()) pending.reject(error);
     this.pending.clear();
   }
@@ -251,6 +278,19 @@ class Child {
     return tools;
   }
 
+  // The VSP tool surface is fixed for the process lifetime (--mode is a
+  // launch argument), so listings are memoized per child. The memo is
+  // cleared on failure, on child exit, and on upstream list_changed.
+  listToolsCached() {
+    if (!this.toolsPromise) {
+      this.toolsPromise = this.listTools().catch(error => {
+        this.toolsPromise = undefined;
+        throw error;
+      });
+    }
+    return this.toolsPromise;
+  }
+
   async close() {
     if (this.exited) return;
     this.closing = true;
@@ -285,18 +325,41 @@ export class MCPProxy {
     this.clientInitialized = false;
     this.pendingNotifications = [];
     this.shuttingDown = false;
-    this.usedSlugs = new Map();
+    this.toolsCache = null;
+    this.mergedToolsPromise = undefined;
+    this.mcpLogLevel = 'info';
+  }
+
+  mcpLogEnabled(level) {
+    return MCP_LOG_LEVELS.indexOf(level) >= MCP_LOG_LEVELS.indexOf(this.mcpLogLevel);
+  }
+
+  // Every observable proxy event lands on stderr and, as a standard
+  // notifications/message log event, in the host's MCP server output channel
+  // (VS Code/BAS and Claude Code both render these). Events raised before the
+  // client initializes are buffered so the channel still shows the full
+  // startup picture once it opens.
+  eventSink(message, level = 'info', logger = 'sap-ai-dev-toolkit') {
+    this.log(message);
+    if (!this.mcpLogEnabled(level)) return;
+    const notification = { jsonrpc: JSONRPC, method: 'notifications/message', params: { level, logger, data: message } };
+    if (this.clientInitialized) this.output(JSON.stringify(notification));
+    else this.pendingNotifications.push(notification);
   }
 
   start() {
     if (this.started) return this;
     this.started = true;
     this.starting = (async () => {
-      for (const originalDestination of this.destinations) {
+      // Destinations start concurrently (relay bind + child spawn); children
+      // are assembled in destination order, which keeps serverInfo's
+      // children[0] fallback and merged slug numbering deterministic.
+      const started = await Promise.all(this.destinations.map(originalDestination => (async () => {
         let destination = originalDestination;
+        let relay;
         try {
           if (useBasDestinationRelay(originalDestination, this.env)) {
-            const relay = createBasDestinationRelay(originalDestination, { env: this.env, log: this.log });
+            relay = createBasDestinationRelay(originalDestination, { env: this.env, log: message => this.eventSink(message) });
             const originalClose = originalDestination.close;
             const relayUrl = await relay.ready;
             destination = {
@@ -311,27 +374,32 @@ export class MCPProxy {
                 await relay.close();
               }
             };
-            this.log(`[${originalDestination.name}] BAS destination relay enabled (${relayUrl})`);
+            this.eventSink(`[${originalDestination.name}] BAS destination relay enabled (${relayUrl})`);
           }
-          this.log(`[${destination.name}] starting VSP child (client=${destination.client || '001'})`);
-          this.children.push({
+          this.eventSink(`[${destination.name}] starting VSP child (client=${destination.client || '001'})`);
+          return {
             destination,
             child: new Child(this.binary, destination, {
               env: this.env,
               spawn: this.spawn,
               args: this.childArgs?.(destination),
-              log: this.log,
+              log: message => this.eventSink(message),
               onNotification: notification => {
+                if (notification.method === 'notifications/tools/list_changed') this.toolsCache = null;
                 if (this.clientInitialized) this.output(JSON.stringify(notification));
                 else this.pendingNotifications.push(notification);
               }
             })
-          });
+          };
         } catch (error) {
-          this.log(`[${destination.name}] failed to start child: ${diagnosticText(error.message)}`);
+          this.eventSink(`[${destination.name}] failed to start child: ${diagnosticText(error.message)}`, 'error');
+          // A relay whose ready promise rejected still owns dispatchers.
+          if (relay && destination === originalDestination) await relay.close().catch(() => {});
           void closeDestinationRoute(destination);
+          return null;
         }
-      }
+      })()));
+      this.children = started.filter(Boolean);
       if (!this.children.length) {
         this.started = false;
         for (const destination of this.destinations) void closeDestinationRoute(destination);
@@ -353,68 +421,123 @@ export class MCPProxy {
   async restartChild(entry) {
     if (this.shuttingDown) throw new Error('MCP proxy is shutting down');
     const name = entry.destination.name;
-    this.log(`[${name}] VSP child crashed; self-healing restart in progress`);
+    this.eventSink(`[${name}] VSP child crashed; self-healing restart in progress`, 'warning');
     await entry.child.close().catch(() => {});
     const child = new Child(this.binary, entry.destination, {
       env: this.env,
       spawn: this.spawn,
       args: this.childArgs?.(entry.destination),
-      log: this.log,
+      log: message => this.eventSink(message),
       onNotification: notification => {
+        if (notification.method === 'notifications/tools/list_changed') this.toolsCache = null;
         if (this.clientInitialized) this.output(JSON.stringify(notification));
         else this.pendingNotifications.push(notification);
       }
     });
     entry.child = child;
     entry.server = await child.initialize(this.lastInitializeParams || {});
-    await child.listTools().catch(() => {});
-    this.log(`[${name}] VSP child self-healing restart complete`);
+    this.toolsCache = null;
+    await child.listToolsCached().catch(() => {});
+    this.eventSink(`[${name}] VSP child self-healing restart complete`);
+    this.emitToolsListChanged();
     return entry;
   }
 
+  emitToolsListChanged() {
+    // Emitted only after the replacement child's tool surface is warm so a
+    // client re-list sees fresh data; buffered until the client initialized.
+    const notification = { jsonrpc: JSONRPC, method: 'notifications/tools/list_changed' };
+    if (this.clientInitialized) this.output(JSON.stringify(notification));
+    else this.pendingNotifications.push(notification);
+  }
+
   async initializeChildren(params) {
     await this.starting;
     this.lastInitializeParams = params;
-    const healthy = [];
-    for (const entry of this.children) {
-      this.log(`[${entry.destination.name}] initializing VSP MCP session`);
+    // Children initialize concurrently; healthy entries keep destination
+    // order so tool naming stays deterministic.
+    const initialized = await Promise.all(this.children.map(async entry => {
+      const startedAt = Date.now();
+      this.eventSink(`[${entry.destination.name}] initializing VSP MCP session`);
       try {
         entry.server = await entry.child.initialize(params);
-        this.log(`[${entry.destination.name}] VSP MCP session initialized`);
-        healthy.push(entry);
+        this.eventSink(`[${entry.destination.name}] VSP MCP session initialized (${Date.now() - startedAt}ms)`);
+        return entry;
       } catch (error) {
-        this.log(`[${entry.destination.name}] initialization failed: ${diagnosticText(error.message)}`);
+        this.eventSink(`[${entry.destination.name}] initialization failed: ${diagnosticText(error.message)}`, 'error');
         await entry.child.close();
         await closeDestinationRoute(entry.destination);
+        return null;
       }
-    }
+    }));
+    const healthy = initialized.filter(Boolean);
     this.children = healthy;
     if (!healthy.length) throw new Error('No destination child initialized successfully');
     this.initialized = true;
+    // Warm the merged tool cache so the client's first tools/list after
+    // initialize resolves without a child round trip.
+    const warmedAt = Date.now();
+    void this.mergedTools()
+      .then(tools => this.eventSink(`[MCP] tools cache warmed (${tools.length} tools, ${Date.now() - warmedAt}ms)`))
+      .catch(() => {});
     return healthy;
   }
 
-  async mergedTools() {
-    this.namespace.clear();
-    this.usedSlugs.clear();
+  toolsCacheValid() {
+    const cached = this.toolsCache;
+    if (!cached) return false;
+    if (cached.children.length !== this.children.length) return false;
+    return this.children.every((entry, index) => entry.child === cached.children[index] && !entry.child.exited);
+  }
+
+  mergedTools() {
+    if (this.mergedToolsPromise) return this.mergedToolsPromise;
+    if (this.toolsCacheValid()) return Promise.resolve([...this.toolsCache.tools]);
+    const childrenAtBuild = this.children.map(entry => entry.child);
+    this.mergedToolsPromise = this.buildMergedTools()
+      .then(tools => {
+        // Cache only when the child set is unchanged; a restart that landed
+        // mid-build invalidates the result and the next list rebuilds.
+        if (!this.shuttingDown && this.children.length === childrenAtBuild.length
+          && this.children.every((entry, index) => entry.child === childrenAtBuild[index])) {
+          this.toolsCache = { children: childrenAtBuild, tools };
+        }
+        return [...tools];
+      })
+      .finally(() => { this.mergedToolsPromise = undefined; });
+    return this.mergedToolsPromise;
+  }
+
+  async buildMergedTools() {
+    const namespace = new Map();
+    const usedSlugs = new Map();
     const merged = [];
+    const publish = (name, mapping, definition) => {
+      // A duplicate public name must not shadow the first registration: the
+      // namespace map would keep the first handler while advertising both.
+      if (namespace.has(name)) {
+        this.eventSink(`[MCP] skipped duplicate public tool name: ${name}`, 'warning');
+        return;
+      }
+      namespace.set(name, mapping);
+      merged.push(definition);
+    };
     for (const entry of this.children) {
-      const slug = slugifyDestination(entry.destination.name, this.usedSlugs);
-      const lintName = `${slug}__${ABAP_LINT_TOOL.name}`;
-      this.namespace.set(lintName, { handler: runABAPLint });
-      merged.push({ ...ABAP_LINT_TOOL, name: lintName });
+      const slug = slugifyDestination(entry.destination.name, usedSlugs);
+      const publicName = name => `${TOOL_NAME_PREFIX}${slug}_${publicToolSegment(name)}`;
+      const lintName = publicName(ABAP_LINT_TOOL.name);
+      publish(lintName, { handler: runABAPLint }, { ...ABAP_LINT_TOOL, name: lintName });
       try {
-        const upstreamTools = await entry.child.listTools();
+        const upstreamTools = await entry.child.listToolsCached();
         for (const tool of upstreamTools) {
           if (tool.name === 'SAP') {
-            const applicationLogName = `${slug}__GetApplicationLog`;
-            this.namespace.set(applicationLogName, {
+            const applicationLogName = publicName('GetApplicationLog');
+            publish(applicationLogName, {
               entry,
               upstream: 'SAP',
               publicName: 'GetApplicationLog',
               transformArguments: applicationLogArguments
-            });
-            merged.push({
+            }, {
               name: applicationLogName,
               description: `${APPLICATION_LOG_DESCRIPTION} [destination: ${entry.destination.name}]`,
               inputSchema: APPLICATION_LOG_SCHEMA
@@ -422,24 +545,24 @@ export class MCPProxy {
           }
 
           if (!exposeVspTool(tool)) continue;
-          const name = `${slug}__${tool.name}`;
-          this.namespace.set(name, { entry, upstream: tool.name });
-          merged.push({ ...tool, name, description: `${tool.description || tool.name} [destination: ${entry.destination.name}]` });
+          const name = publicName(tool.name);
+          publish(name, { entry, upstream: tool.name }, { ...tool, name, description: `${tool.description || tool.name} [destination: ${entry.destination.name}]` });
         }
         for (const localTool of createEngineeringTools(entry, upstreamTools, { env: this.env, log: this.log })) {
-          const name = `${slug}__${localTool.definition.name}`;
-          this.namespace.set(name, { handler: localTool.handler });
-          merged.push({
+          const name = publicName(localTool.definition.name);
+          publish(name, { handler: localTool.handler }, {
             ...localTool.definition,
             name,
             description: `${localTool.definition.description} [destination: ${entry.destination.name}]`
           });
         }
       } catch (error) {
-        this.log(`[${entry.destination.name}] tools/list failed: ${redactText(error.message)}`);
+        this.eventSink(`[${entry.destination.name}] tools/list failed: ${redactText(error.message)}`, 'error');
       }
     }
     if (!merged.length && this.children.length) throw new Error('No destination child provided tools');
+    // Swap atomically so a concurrent tools/call never sees a partial map.
+    this.namespace = namespace;
     return merged;
   }
 
@@ -449,13 +572,24 @@ export class MCPProxy {
       return null;
     }
     if (message.id === undefined) return null;
+    const receivedAt = Date.now();
     try {
+      this.eventSink(`[MCP] request ${message.method || '?'} (id=${message.id})`, 'debug');
       if (message.method === 'initialize') {
         await this.initializeChildren(message.params || {});
-        return rpcResult(message.id, { protocolVersion: message.params?.protocolVersion || '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: brandedEnvValue(this.env, 'DESTINATION') || this.children[0].destination.name, version: '0.1.0' } });
+        this.eventSink('[MCP] initialize complete; server ready', 'info');
+        return rpcResult(message.id, { protocolVersion: message.params?.protocolVersion || '2024-11-05', capabilities: { tools: { listChanged: true } }, serverInfo: { name: slugifyDestination(brandedEnvValue(this.env, 'DESTINATION') || this.children[0].destination.name), version: '0.1.0' } });
       }
       if (!this.initialized) return rpcError(message.id, -32002, 'MCP proxy is not initialized');
-      if (message.method === 'tools/list') return rpcResult(message.id, { tools: await this.mergedTools() });
+      if (message.method === 'logging/setLevel' && MCP_LOG_LEVELS.includes(message.params?.level)) {
+        this.mcpLogLevel = message.params.level;
+        this.eventSink(`[MCP] log level set to ${this.mcpLogLevel}`);
+      }
+      if (message.method === 'tools/list') {
+        const tools = await this.mergedTools();
+        this.eventSink(`[MCP] tools/list returned ${tools.length} tools in ${Date.now() - receivedAt}ms`, 'debug');
+        return rpcResult(message.id, { tools });
+      }
       if (message.method === 'tools/call') {
         const name = message.params?.name;
         const mapped = this.namespace.get(name);
@@ -465,31 +599,31 @@ export class MCPProxy {
         const upstreamParams = { ...message.params, name: mapped.upstream };
         if (mapped.transformArguments) upstreamParams.arguments = mapped.transformArguments(message.params?.arguments);
         const startedAt = Date.now();
-        this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} started`);
+        this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} started`);
         try {
           const response = await mapped.entry.child.request('tools/call', upstreamParams);
           if (response.result?.isError) {
             const detail = Array.isArray(response.result.content)
               ? response.result.content.filter(item => item.type === 'text').map(item => item.text).join(' ')
               : '';
-            this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} returned an error in ${Date.now() - startedAt}ms${detail ? `: ${diagnosticText(detail)}` : ''}`);
+            this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} returned an error in ${Date.now() - startedAt}ms${detail ? `: ${diagnosticText(detail)}` : ''}`, 'warning');
           } else {
-            this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} completed in ${Date.now() - startedAt}ms`);
+            this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} completed in ${Date.now() - startedAt}ms`);
           }
           return response.error ? { ...response, id: message.id } : rpcResult(message.id, response.result);
         } catch (error) {
-          this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} failed after ${Date.now() - startedAt}ms: ${diagnosticText(error.rpcError?.message || error.message)}`);
+          this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} failed after ${Date.now() - startedAt}ms: ${diagnosticText(error.rpcError?.message || error.message)}`, 'error');
           // Self-healing: a dead child (crash, OOM, transient pipe break) is
           // restarted and the call retried once before surfacing the error.
           const childBroken = mapped.entry.child.exited || !mapped.entry.child.process.stdin.writable;
           if (childBroken && !this.shuttingDown) {
             try {
               await this.restartChild(mapped.entry);
-              this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} retried after self-healing restart`);
+              this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} retried after self-healing restart`);
               const retried = await mapped.entry.child.request('tools/call', upstreamParams);
               return retried.error ? { ...retried, id: message.id } : rpcResult(message.id, retried.result);
             } catch (restartError) {
-              this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} self-healing restart failed: ${diagnosticText(restartError.message)}`);
+              this.eventSink(`[${mapped.entry.destination.name}] tools/call ${toolName} self-healing restart failed: ${diagnosticText(restartError.message)}`, 'error');
             }
           }
           return error.rpcError ? rpcError(message.id, error.rpcError.code || -32001, error.rpcError.message || error.message, error.rpcError.data) : rpcError(message.id, -32001, `Destination ${mapped.entry.destination.name} failed: ${error.message}`);
@@ -498,11 +632,11 @@ export class MCPProxy {
       if (!FORWARDED_METHODS.has(message.method)) return rpcError(message.id, -32601, `Method not found: ${message.method}`);
       const responses = [];
       for (const entry of this.children) {
-        try { responses.push((await entry.child.request(message.method, message.params)).result); } catch (error) { this.log(`[${entry.destination.name}] ${message.method} failed: ${redactText(error.message)}`); }
+        try { responses.push((await entry.child.request(message.method, message.params)).result); } catch (error) { this.eventSink(`[${entry.destination.name}] ${message.method} failed: ${redactText(error.message)}`, 'warning'); }
       }
       return rpcResult(message.id, responses.length === 1 ? responses[0] : responses);
     } catch (error) {
-      this.log(`[MCP] ${message.method || 'request'} failed: ${diagnosticText(error.message)}`);
+      this.eventSink(`[MCP] ${message.method || 'request'} failed: ${diagnosticText(error.message)}`, 'error');
       return rpcError(message.id, -32000, redactText(error.message));
     }
   }
@@ -529,7 +663,7 @@ export class MCPProxy {
               this.pendingNotifications.length = 0;
             }
           }
-        } catch (error) { this.log(redactText(error.message)); }
+        } catch (error) { this.eventSink(`[MCP] invalid client message dropped: ${redactText(error.message)}`, 'error'); }
       }
     };
     input.setEncoding('utf8');