sap-ai-dev-toolkit 0.3.3 → 0.3.7

package/src/bas-destination-relay.mjs

@@ -97,16 +97,15 @@ async function readRequestBody(req) {
 export function createBasDestinationRelay(destination, { env = process.env, fetchImpl = undiciFetch, log = () => {} } = {}) {
   if (!destination?.url) throw new Error('Destination relay requires a BAS destination URL');
   const base = new URL(destination.url);
-  // Self-healing mode 5 (direct connect): the BAS .dest proxy strips
-  // Set-Cookie, which makes SAP CSRF session binding impossible. When the
-  // operator stored credentials for this destination (setup prompts for
-  // Internet destinations), the relay connects straight to the backend host
-  // with Basic auth — cookies survive, CSRF pairing works, and writes go
-  // through exactly like they do from Eclipse/ADT.
   const credentials = destination.credentials;
-  const directBase = credentials?.host ? new URL(String(credentials.host)) : null;
-  const effectiveBase = directBase || base;
+  const tunnelMode = credentials?.mode === 'bas-tunnel';
+  const directHost = tunnelMode ? '' : credentials?.host;
+  // Internet overrides retain the direct-backend path. OnPremise overrides
+  // must keep the BAS .dest route (and its Cloud Connector mapping), so they
+  // use HTTP CONNECT through the BAS proxy instead of credentials.host.
+  const directBase = directHost ? new URL(String(directHost)) : null;
   if (directBase) log(`[${destination.name}] BAS relay direct connect active (${directBase.origin}); BAS proxy cookie stripping bypassed`);
+  if (tunnelMode) log(`[${destination.name}] BAS relay using a BAS proxy tunnel for the OnPremise destination`);
   // Proxy resolution: an explicitly configured proxy wins (an explicit empty
   // value means "go direct"). Without configuration, BAS virtual .dest hosts
   // imply the default BAS proxy; any other host (tests, direct URLs) is
@@ -114,22 +113,23 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   // foreign proxy.
   const explicitProxy = env.HTTP_PROXY ?? env.http_proxy;
   const proxyUrl = directBase ? '' : (explicitProxy !== undefined ? String(explicitProxy) : (/\.dest$/i.test(base.hostname) ? DEFAULT_PROXY : ''));
+  if (tunnelMode && !proxyUrl) throw new Error('OnPremise credential overrides require the BAS destination proxy to preserve the Cloud Connector route');
   const dispatcher = proxyUrl ? new ProxyAgent({ uri: proxyUrl, proxyTunnel: false }) : undefined;
   // Self-healing mode 2: if the BAS proxy refuses absolute-form proxied
   // requests (its own 502/504), retry through a CONNECT tunnel so the relay
   // keeps working through the same egress.
   const tunnelDispatcher = proxyUrl ? new ProxyAgent({ uri: proxyUrl, proxyTunnel: true }) : undefined;
-  let tunneled = false;
+  let tunneled = tunnelMode;
   // Observable self-healing counters, surfaced by --doctor and tests.
-  const stats = { requests: 0, csrfFetches: 0, csrfRetries: 0, tunnelFallbacks: 0, direct: Boolean(directBase) };
+  const stats = { requests: 0, csrfFetches: 0, csrfRetries: 0, tunnelFallbacks: 0, direct: Boolean(directBase), proxyTunnel: tunnelMode };
   // Per-path CSRF sessions: { token, jar, fetchedAt } where jar holds the
   // Set-Cookie state SAP returned together with the token.
   const tokenCache = new Map();
 
-  function rememberSession(key, token, headers) {
+  function rememberSession(key, token, headers, httpStatus) {
     const jar = new Map();
     recordCookies(jar, headers);
-    tokenCache.set(key, { token, jar, fetchedAt: Date.now() });
+    tokenCache.set(key, { token, jar, fetchedAt: Date.now(), httpStatus });
   }
 
   async function send(target, method, headers, body) {
@@ -171,12 +171,22 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
     await response.arrayBuffer().catch(() => undefined);
     const token = response.headers.get('x-csrf-token');
     if (token && token.toLowerCase() !== 'required') {
-      rememberSession(key, token, response.headers);
+      rememberSession(key, token, response.headers, response.status);
       return tokenCache.get(key);
     }
     return null;
   }
 
+  async function probeCsrfSession(path = '/sap/bc/adt/discovery') {
+    const requestUrl = new URL(path, base);
+    const session = await fetchToken(requestUrl, { accept: 'application/xml,text/xml,*/*' });
+    return {
+      httpStatus: session?.httpStatus || 0,
+      tokenReceived: Boolean(session?.token),
+      cookieCount: session?.jar?.size || 0
+    };
+  }
+
   // Rewrite an incoming .dest target onto the direct backend host when
   // credentials are configured, keeping path and query intact.
   function resolveTarget(target) {
@@ -261,6 +271,7 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   return {
     ready,
     stats,
+    probeCsrfSession,
     close: async () => {
       await dispatcher?.close?.();
       await tunnelDispatcher?.close?.();

package/src/credential-overrides.mjs

@@ -0,0 +1,75 @@
+import { readCredentials, resolveCredentialsPath } from './credentials-store.mjs';
+
+const CLOUD_FOUNDRY_KEY_PREFIX = 'cloud-foundry:';
+
+function isBasicAuthentication(value) {
+  return /^basic(?:authentication)?$/i.test(String(value || '').replace(/\s+/g, ''));
+}
+
+export function credentialKeyForDestination(destination = {}) {
+  if (destination.source === 'cloud-foundry') {
+    const serverName = String(destination.serverName || '').trim();
+    return serverName ? `${CLOUD_FOUNDRY_KEY_PREFIX}${serverName}` : '';
+  }
+  return String(destination.name || '').trim();
+}
+
+export function credentialModeForDestination(destination = {}) {
+  if (!isBasicAuthentication(destination.authentication)) return null;
+  const proxyType = String(destination.proxyType || '').trim().toLowerCase();
+  if (destination.source === 'cloud-foundry') {
+    return proxyType === 'onpremise' ? 'cf-connectivity' : null;
+  }
+  if (proxyType === 'internet') return 'direct';
+  if (proxyType === 'onpremise') return 'bas-tunnel';
+  return null;
+}
+
+export function canPromptForCredentials(destination = {}) {
+  const mode = credentialModeForDestination(destination);
+  return Boolean(mode && (mode !== 'direct' || destination.backendUrl));
+}
+
+export async function enrichWithStoredCredentials(destinations, env = process.env, log = message => console.error(message)) {
+  const needingCredentials = destinations.filter(destination => {
+    const mode = credentialModeForDestination(destination);
+    if (!mode || !canPromptForCredentials(destination)) return false;
+    if (mode === 'cf-connectivity') return Boolean(destination.serverName);
+    return Boolean(destination.url && String(destination.url).includes('.dest'));
+  });
+  if (!needingCredentials.length) return destinations;
+  let stored;
+  try {
+    const path = await resolveCredentialsPath(env);
+    stored = await readCredentials(path);
+  } catch (error) {
+    log(`[sap-ai-dev] stored credentials could not be read: ${String(error.message).slice(0, 200)}`);
+    return destinations;
+  }
+  return destinations.map(destination => {
+    const mode = credentialModeForDestination(destination);
+    const key = credentialKeyForDestination(destination);
+    const entry = key ? stored.destinations?.[key] : undefined;
+    if (!mode || !entry?.user || !entry?.password) return destination;
+    if (mode === 'cf-connectivity') {
+      if (entry.mode !== mode || destination.source !== 'cloud-foundry') return destination;
+      return {
+        ...destination,
+        childEnv: {
+          ...(destination.childEnv || {}),
+          SAP_USER: entry.user,
+          SAP_PASSWORD: entry.password,
+          SAP_VERBOSE: 'false'
+        }
+      };
+    }
+    if (mode === 'bas-tunnel') {
+      if (entry.mode !== mode) return destination;
+      return { ...destination, credentials: { user: entry.user, password: entry.password, mode } };
+    }
+    if (!destination.backendUrl || !destination.url || !String(destination.url).includes('.dest')) return destination;
+    if (entry.mode && entry.mode !== 'direct') return destination;
+    const host = entry.host || destination.backendUrl;
+    return { ...destination, credentials: { host, user: entry.user, password: entry.password, mode: 'direct' } };
+  });
+}

package/src/credentials-store.mjs

@@ -4,10 +4,11 @@ import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { brandedEnvValue } from './branding.mjs';
 
-// Credentials for direct-connect destinations live next to the MCP config
-// (never inside it), with 0600 permissions and no tokens or cookies. The
-// file maps destination names to { host, user, password, updatedAt }.
+// Optional SAP backend credential overrides live next to the MCP config
+// (never inside it), with 0600 permissions and no tokens or cookies. Entries
+// are keyed by a stable destination identity and may include a route mode.
 const CREDENTIALS_FILENAME = 'sap-ai-dev-toolkit-credentials.json';
+const CREDENTIAL_MODES = new Set(['direct', 'bas-tunnel', 'cf-connectivity']);
 
 const SECRET_PATTERN = /(authorization|cookie|password|secret|token|bearer|credential)/i;
 
@@ -44,6 +45,7 @@ function sanitizeEntry(entry) {
   if (typeof entry?.host === 'string' && entry.host) result.host = entry.host;
   if (typeof entry?.user === 'string' && entry.user) result.user = entry.user;
   if (typeof entry?.password === 'string' && entry.password) result.password = entry.password;
+  if (CREDENTIAL_MODES.has(entry?.mode)) result.mode = entry.mode;
   if (typeof entry?.updatedAt === 'string') result.updatedAt = entry.updatedAt;
   return result;
 }
@@ -87,10 +89,17 @@ async function writeCredentials(path, destinations) {
   }
 }
 
-export async function storeDestinationCredentials(path, name, { host, user, password }) {
+export async function storeDestinationCredentials(path, name, { host, user, password, mode }) {
+  if (mode != null && !CREDENTIAL_MODES.has(mode)) throw new Error('Credential override route mode is unsupported');
   const current = await readCredentials(path).catch(error => { throw error; });
   const destinations = { ...current.destinations };
-  destinations[String(name)] = { host: String(host || ''), user: String(user || ''), password: String(password || ''), updatedAt: new Date().toISOString() };
+  destinations[String(name)] = {
+    host: String(host || ''),
+    user: String(user || ''),
+    password: String(password || ''),
+    ...(mode ? { mode } : {}),
+    updatedAt: new Date().toISOString()
+  };
   await writeCredentials(path, destinations);
   return { path, name };
 }

package/src/hana-config.mjs

@@ -0,0 +1,170 @@
+const EXPLICIT_CONNECTION_KEYS = [
+  'HANA_RO_HOST',
+  'HANA_RO_PORT',
+  'HANA_RO_USER',
+  'HANA_RO_PASSWORD',
+  'HANA_RO_SCHEMA'
+];
+
+const DEFAULT_SERVICE_TYPES = new Set(['hana', 'hana-cloud', 'hana-cloud-db', 'hanacloud', 'sap-hana-cloud']);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function normalizeServiceType(value) {
+  return String(value || '').trim().toLowerCase().replaceAll('_', '-');
+}
+
+function requiredText(value, label) {
+  if (typeof value !== 'string' || !value.trim()) fail(`HANA read-only connection is missing ${label}.`);
+  return value.trim();
+}
+
+function validateHost(value) {
+  const host = requiredText(value, 'host');
+  if (/[\s/@?#\\]/.test(host) || host.includes('://') || host.includes(':')) {
+    fail('HANA_RO_HOST must contain only a hostname; provide the port separately.');
+  }
+  return host;
+}
+
+function validatePort(value) {
+  const portText = requiredText(String(value ?? ''), 'port');
+  if (!/^\d{1,5}$/.test(portText)) fail('HANA_RO_PORT must be an integer between 1 and 65535.');
+  const port = Number(portText);
+  if (port < 1 || port > 65535) fail('HANA_RO_PORT must be an integer between 1 and 65535.');
+  return port;
+}
+
+function validateSchema(value) {
+  const schema = requiredText(value, 'schema');
+  if (schema.length > 127 || /[\u0000-\u001f\u007f]/.test(schema)) {
+    fail('The configured HANA schema name is invalid.');
+  }
+  return schema;
+}
+
+function hasExplicitConnection(env) {
+  return EXPLICIT_CONNECTION_KEYS.some(key => env[key] !== undefined && env[key] !== '');
+}
+
+function explicitConfig(env) {
+  const host = validateHost(env.HANA_RO_HOST);
+  const port = validatePort(env.HANA_RO_PORT);
+  const user = requiredText(env.HANA_RO_USER, 'read-only user');
+  const password = requiredText(env.HANA_RO_PASSWORD, 'read-only password');
+  const schema = validateSchema(env.HANA_RO_SCHEMA);
+  return {
+    source: 'environment',
+    bindingName: undefined,
+    serviceName: undefined,
+    host,
+    port,
+    user,
+    password,
+    schema,
+    trustStore: optionalTrustStore(env.HANA_RO_TRUST_STORE)
+  };
+}
+
+function optionalTrustStore(value) {
+  if (value === undefined || value === '') return undefined;
+  const trustStore = requiredText(value, 'TLS trust-store path');
+  if (/[\u0000-\u001f\u007f]/.test(trustStore)) fail('The configured HANA TLS trust-store path is invalid.');
+  return trustStore;
+}
+
+function parseVcapServices(raw) {
+  if (!raw) fail('Set HANA_RO_* read-only credentials or bind a selected HANA service in VCAP_SERVICES.');
+  let services;
+  try {
+    services = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    fail('VCAP_SERVICES is not valid JSON.');
+  }
+  if (!services || typeof services !== 'object' || Array.isArray(services)) {
+    fail('VCAP_SERVICES must contain a JSON object.');
+  }
+  return services;
+}
+
+function vcapCandidates(env) {
+  const services = parseVcapServices(env.VCAP_SERVICES);
+  const selectedType = env.HANA_RO_VCAP_SERVICE?.trim();
+  const bindingName = env.HANA_RO_BINDING?.trim();
+  const entries = Object.entries(services).filter(([serviceType]) => {
+    return selectedType
+      ? serviceType === selectedType
+      : DEFAULT_SERVICE_TYPES.has(normalizeServiceType(serviceType));
+  });
+
+  if (selectedType && !entries.length) fail('The selected HANA VCAP service type was not found.');
+
+  let candidates = entries.flatMap(([serviceName, instances]) => {
+    if (!Array.isArray(instances)) return [];
+    return instances
+      .filter(instance => instance && typeof instance === 'object' && !Array.isArray(instance))
+      .map(instance => ({ serviceName, instance }));
+  });
+
+  if (bindingName) {
+    candidates = candidates.filter(({ instance }) => {
+      return instance.name === bindingName || instance.binding_name === bindingName;
+    });
+    if (!candidates.length) fail('The selected HANA binding was not found in VCAP_SERVICES.');
+  }
+
+  if (candidates.length !== 1) {
+    fail(candidates.length === 0
+      ? 'No HANA VCAP binding was found; set HANA_RO_VCAP_SERVICE or explicit HANA_RO_* credentials.'
+      : 'Multiple HANA VCAP bindings were found; set HANA_RO_BINDING to select exactly one.');
+  }
+  return candidates[0];
+}
+
+function vcapConfig(env) {
+  const { serviceName, instance } = vcapCandidates(env);
+  const credentials = instance.credentials;
+  if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) {
+    fail('The selected HANA binding has no usable credentials object.');
+  }
+  if ((!credentials.user || !credentials.password) && (credentials.hdi_user || credentials.hdi_password)) {
+    fail('The selected HANA binding only exposes HDI deployment credentials; configure a separate read-only binding.');
+  }
+  if (credentials.user && credentials.hdi_user && credentials.user === credentials.hdi_user) {
+    fail('The selected HANA binding aliases its read-only and HDI deployment users; configure separate identities.');
+  }
+
+  return {
+    source: 'vcap-services',
+    bindingName: typeof instance.binding_name === 'string' ? instance.binding_name : instance.name,
+    serviceName,
+    host: validateHost(credentials.host),
+    port: validatePort(credentials.port),
+    user: requiredText(credentials.user, 'read-only user'),
+    password: requiredText(credentials.password, 'read-only password'),
+    schema: validateSchema(credentials.schema),
+    trustStore: optionalTrustStore(env.HANA_RO_TRUST_STORE)
+  };
+}
+
+/** Resolve only a read-only HANA identity; HDI deployment credentials are never a fallback. */
+export function resolveHanaReadOnlyConfig(env = process.env) {
+  if (!env || typeof env !== 'object') fail('HANA environment configuration is unavailable.');
+  const hasExplicit = hasExplicitConnection(env);
+  if (hasExplicit) {
+    const missing = EXPLICIT_CONNECTION_KEYS.filter(key => typeof env[key] !== 'string' || !env[key].trim());
+    if (missing.length) fail(`Explicit HANA read-only configuration is incomplete: ${missing.join(', ')}.`);
+    return Object.freeze(explicitConfig(env));
+  }
+  return Object.freeze(vcapConfig(env));
+}
+
+export function quoteHanaIdentifier(value) {
+  const identifier = requiredText(value, 'identifier');
+  if (identifier.length > 127 || /[\u0000-\u001f\u007f]/.test(identifier)) {
+    fail('The HANA identifier is invalid.');
+  }
+  return `"${identifier.replaceAll('"', '""')}"`;
+}

package/src/hana-database.mjs

@@ -0,0 +1,150 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const QUERY_TIMEOUT_MS = 15_000;
+
+function hanaFailure(operation, error) {
+  const code = typeof error?.code === 'string' || typeof error?.code === 'number'
+    ? String(error.code).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 24)
+    : '';
+  const failure = new Error(`${operation} failed${code ? ` (HANA error ${code})` : ''}; verify the selected read-only binding, schema, and privileges.`);
+  failure.name = 'HanaDatabaseError';
+  return failure;
+}
+
+function callbackPromise(invoke, operation) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (error, result) => {
+      if (settled) return;
+      settled = true;
+      if (error) reject(hanaFailure(operation, error));
+      else resolve(result);
+    };
+    try {
+      invoke(done);
+    } catch (error) {
+      done(error);
+    }
+  });
+}
+
+function executeWithTimeout(connection, sql, values, timeoutMs, onTimeout) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      onTimeout();
+      const error = new Error(`HANA read exceeded the ${timeoutMs / 1000} second time limit; the connection was retired. Narrow the request and retry.`);
+      error.name = 'HanaQueryTimeoutError';
+      reject(error);
+    }, timeoutMs);
+    const done = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(hanaFailure('HANA read', error));
+      else resolve(result);
+    };
+    try {
+      connection.exec(sql, values, {}, done);
+    } catch (error) {
+      done(error);
+    }
+  });
+}
+
+export function hanaConnectionOptions(config) {
+  return {
+    host: config.host,
+    port: config.port,
+    uid: config.user,
+    pwd: config.password,
+    currentSchema: config.schema,
+    encrypt: true,
+    sslValidateCertificate: true,
+    connectTimeout: 10_000,
+    ...(config.trustStore ? { sslTrustStore: config.trustStore } : {})
+  };
+}
+
+export class HanaDatabase {
+  constructor(connection, config, { queryTimeoutMs = QUERY_TIMEOUT_MS } = {}) {
+    this.connection = connection;
+    this.config = config;
+    this.queryTimeoutMs = queryTimeoutMs;
+    this.connected = false;
+    this.closed = false;
+    this.unusable = false;
+    this.queue = Promise.resolve();
+  }
+
+  async connect() {
+    if (this.closed) throw new Error('HANA connection is closed.');
+    if (this.connected) return this;
+    await callbackPromise(
+      callback => this.connection.connect(hanaConnectionOptions(this.config), callback),
+      'HANA connection'
+    );
+    this.connected = true;
+    return this;
+  }
+
+  async query(sql, values = []) {
+    if (!this.connected || this.closed || this.unusable) throw new Error('HANA connection is not available.');
+    if (typeof sql !== 'string' || !sql.trim() || !Array.isArray(values)) {
+      throw new Error('Invalid internal HANA query request.');
+    }
+    const result = this.queue.then(() => executeWithTimeout(
+      this.connection,
+      sql,
+      values,
+      this.queryTimeoutMs,
+      () => {
+        this.unusable = true;
+        try { this.connection.cancel?.(); } catch {}
+      }
+    ));
+    this.queue = result.then(() => undefined, () => undefined);
+    try {
+      return await result;
+    } catch (error) {
+      if (this.unusable) await this.close();
+      throw error;
+    }
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    await this.queue.catch(() => {});
+    if (!this.connected) return;
+    this.connected = false;
+    await callbackPromise(callback => this.connection.disconnect(callback), 'HANA disconnect').catch(() => {});
+  }
+}
+
+export async function connectReadOnlyHana(config, { driver } = {}) {
+  let selectedDriver = driver;
+  if (!selectedDriver) {
+    try {
+      selectedDriver = require('@sap/hana-client');
+    } catch {
+      throw new Error('The SAP HANA Node.js driver could not be loaded for this platform.');
+    }
+  }
+  if (typeof selectedDriver?.createConnection !== 'function') {
+    throw new Error('The configured SAP HANA Node.js driver is unavailable.');
+  }
+
+  const connection = selectedDriver.createConnection();
+  const database = new HanaDatabase(connection, config);
+  try {
+    await database.connect();
+    return database;
+  } catch (error) {
+    await database.close();
+    throw error;
+  }
+}

package/src/hana-inspector.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { resolveHanaReadOnlyConfig } from './hana-config.mjs';
+import { connectReadOnlyHana } from './hana-database.mjs';
+import { registerHanaTools } from './hana-tools.mjs';
+
+const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+function publicConnectionSummary(config) {
+  return Object.freeze({
+    source: config.source,
+    serviceName: config.serviceName,
+    bindingName: config.bindingName,
+    host: config.host,
+    port: config.port,
+    schema: config.schema
+  });
+}
+
+/** Create an injectable server runtime for tests and the stdio executable. */
+export function createHanaInspector({ env = process.env, driver, databaseFactory = connectReadOnlyHana } = {}) {
+  const config = resolveHanaReadOnlyConfig(env);
+  const summary = publicConnectionSummary(config);
+  let databasePromise;
+  let database;
+
+  const getDatabase = async () => {
+    if (!databasePromise) {
+      databasePromise = databaseFactory(config, { driver })
+        .then(connected => {
+          database = connected;
+          return connected;
+        })
+        .catch(error => {
+          databasePromise = undefined;
+          throw error;
+        });
+    }
+    return databasePromise;
+  };
+
+  const server = new McpServer({
+    name: 'sap-ai-hana-inspector',
+    version: packageMetadata.version
+  }, { capabilities: { tools: {} } });
+  registerHanaTools(server, getDatabase, { connectionSummary: summary });
+
+  let closing;
+  const close = () => {
+    if (!closing) {
+      closing = (async () => {
+        await server.close().catch(() => {});
+        if (!database && databasePromise) database = await databasePromise.catch(() => undefined);
+        if (database) await database.close().catch(() => {});
+      })();
+    }
+    return closing;
+  };
+
+  return { server, close, connectionSummary: summary };
+}
+
+export async function runHanaInspector({ env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, driver } = {}) {
+  if (process.argv.slice(2).some(argument => argument === '--help' || argument === '-h')) {
+    stdout.write([
+      'Usage: sap-ai-hana',
+      '',
+      'Starts a read-only stdio MCP server for the HANA service selected by HANA_RO_* or VCAP_SERVICES.',
+      'Required explicit variables: HANA_RO_HOST, HANA_RO_PORT, HANA_RO_USER, HANA_RO_PASSWORD, HANA_RO_SCHEMA.',
+      'VCAP selection: HANA_RO_VCAP_SERVICE and HANA_RO_BINDING are optional when exactly one HANA binding exists.',
+      'TLS certificate validation is always enabled. Deployment credentials are never used as a fallback.',
+      ''
+    ].join('\n'));
+    return;
+  }
+  let runtime;
+  try {
+    runtime = createHanaInspector({ env, driver });
+  } catch (error) {
+    stderr.write(`[sap-ai-hana] ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const transport = new StdioServerTransport(stdin, stdout, { maxBufferSize: 1024 * 1024 });
+  let closing;
+  const shutdown = () => {
+    if (!closing) closing = runtime.close().catch(() => {});
+    return closing;
+  };
+  const onStdinEnd = () => { void shutdown(); };
+  const onSignal = signal => {
+    void shutdown().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+  };
+  stdin.once('end', onStdinEnd);
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  transport.onerror = () => stderr.write('[sap-ai-hana] MCP stdio transport failed.\n');
+
+  try {
+    await runtime.server.connect(transport);
+  } catch {
+    stderr.write('[sap-ai-hana] MCP server startup failed.\n');
+    await shutdown();
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  await runHanaInspector();
+}