abap-local-client 1.4.14 → 1.4.17

package/adt-manage-systems-handoff.md

@@ -0,0 +1,278 @@
+# Handoff — implementar `add_system` / `list_systems` / `remove_system` / `update_system` no `abap-local-client`
+
+> Este documento é para o agente/dev que vai alterar o repositório **`abap-local-client`**
+> (pacote npm separado, não faz parte do repo `abap-mcp`). O lado do servidor MCP (`abap-mcp`)
+> já está implementado e pronto — falta só o cliente local saber responder a estes comandos.
+>
+> **`add_system`**: spec confirmado diretamente pelo agente do `abap-local-client` — os 5 modos
+> de autenticação e seus parâmetros abaixo refletem exatamente o CLI `add-system` atual.
+>
+> **`list_systems` / `remove_system` / `update_system`**: comandos **novos, propostos pelo lado
+> do servidor** — ainda não confirmados/implementados no `abap-local-client`. Precisam de spec
+> equivalente (ex.: `list-systems`, `remove-system`, `update-system` no CLI) antes de ativar essas
+> operações em produção. Até lá, chamadas com essas operações vão falhar como qualquer comando
+> desconhecido (ver seção "Comando desconhecido" abaixo).
+
+## Contexto
+
+Hoje, para adicionar um ambiente SAP, o usuário roda manualmente algo como:
+
+```bash
+npx abap-local-client@1.4.14 add-system PIRA_S4D snc --host vhlbvs4dci.sap.piracanjuba.com.br --sysnr 00 --client 100 --snc-partner-name "p:CN=svc.ssoS4D" --language PT
+```
+
+O objetivo é permitir que o **agente de IA no Cursor/chat** faça isso por ele — adicionar, listar,
+remover e atualizar ambientes — sem o usuário precisar abrir terminal. Do lado do servidor, todas
+essas operações estão unificadas em uma única tool MCP: `adt_manage_systems({ operation: "add" | "list" | "remove" | "update", ... })`.
+A tool já manda o comando certo pelo WebSocket — só falta o cliente local **escutar e tratar** cada
+`action`.
+
+O padrão de protocolo é **exatamente o mesmo** já usado por `switch_system` e `refresh_systems`
+(que o cliente já implementa hoje) — são só novos `action`/`command` a mais. Cada operação da tool
+MCP vira um `action` diferente no envelope WebSocket (`add_system`, `list_systems`,
+`remove_system`, `update_system`) — não é um único action compartilhado.
+
+## Operação `add` — os 5 modos de autenticação (spec confirmado)
+
+| Modo | Obrigatórios | Opcionais |
+|---|---|---|
+| `basic` | `--host`, `--port`, `--client`, `--username`, `--password` | `--saprouter`, `--language` |
+| `spnego` | `--host`, `--port`, `--client` | `--service-principal`, `--language` |
+| `x509` | `--host`, `--port`, `--client`, `--ca-cert`, `--ca-key`, `--login-id` | `--language` |
+| `saml` | `--base-url`, `--client` | `--headless`, `--timeout-ms`, `--language` |
+| `snc` (usado no Piracanjuba/Vale) | `--host`, `--sysnr`, `--client`, `--snc-partner-name` | `--snc-my-name`, `--snc-qop`, `--snc-lib`, `--username`, `--saprouter`, `--language` |
+
+**Pontos importantes:**
+- Só `basic` e `snc` aceitam `--saprouter`. Nos outros 3 modos (`spnego`, `x509`, `saml`) esse flag
+  não existe.
+- `basic`/`spnego`/`x509` usam `--port` (porta HTTP/HTTPS); só `snc` usa `--sysnr` (número do
+  sistema SAP). Não são a mesma coisa — a tool MCP manda os dois como campos separados
+  (`port` vs `sysnr`) e nunca os dois juntos no mesmo comando.
+- `saml` é o único modo que não usa `--host`/`--port` — usa `--base-url` direto.
+
+### O que a tool MCP envia (`operation: "add"`)
+
+Mensagem recebida pelo cliente local via WebSocket (mesmo canal/autenticação já existentes).
+Exemplo real (modo `snc`, igual ao uso no Piracanjuba):
+
+```json
+{
+  "action": "add_system",
+  "callspecs": [
+    {
+      "command": "add_system",
+      "systemId": "PIRA_S4D",
+      "connectionType": "snc",
+      "host": "vhlbvs4dci.sap.piracanjuba.com.br",
+      "sysnr": "00",
+      "client": "100",
+      "sncPartnerName": "p:CN=svc.ssoS4D",
+      "language": "PT"
+    }
+  ],
+  "requestId": "req_1730900000000_abc123xyz",
+  "timestamp": "2026-07-06T19:57:00.000Z"
+}
+```
+
+Ou seja: o payload relevante está em `callspecs[0]` (sempre um array de 1 elemento neste comando —
+o servidor nunca manda mais de um por vez para este action). O cliente deve:
+1. Ler `message.action === "add_system"`.
+2. Pegar `message.callspecs[0]` como o comando real.
+3. Executar o equivalente ao CLI `add-system` com esses parâmetros.
+4. Responder usando o `requestId` recebido (ver formato de resposta abaixo).
+
+### Mapeamento completo de campos → flags do CLI
+
+| Campo no JSON | Flag do CLI | Modo(s) |
+|---|---|---|
+| `systemId` | 1º posicional (`SYSTEM_ID`) | todos — já vem em UPPERCASE do servidor |
+| `connectionType` | 2º posicional (`basic`\|`spnego`\|`x509`\|`saml`\|`snc`) | todos |
+| `host` | `--host` | basic, spnego, x509, snc |
+| `port` | `--port` | basic, spnego, x509 |
+| `sysnr` | `--sysnr` | snc |
+| `client` | `--client` | todos |
+| `language` | `--language` | todos (opcional) |
+| `username` | `--username` | basic (obrigatório), snc (opcional) |
+| `password` | `--password` | basic |
+| `saprouter` | `--saprouter` | basic, snc (opcional) |
+| `servicePrincipal` | `--service-principal` | spnego (opcional) |
+| `caCert` | `--ca-cert` | x509 |
+| `caKey` | `--ca-key` | x509 |
+| `loginId` | `--login-id` | x509 |
+| `baseUrl` | `--base-url` | saml |
+| `headless` | `--headless` | saml (opcional, boolean) |
+| `timeoutMs` | `--timeout-ms` | saml (opcional, number) |
+| `sncPartnerName` | `--snc-partner-name` | snc |
+| `sncMyName` | `--snc-my-name` | snc (opcional) |
+| `sncQop` | `--snc-qop` | snc (opcional) |
+| `sncLib` | `--snc-lib` | snc (opcional) |
+| `extraParams` | objeto `{ "flag-name": "valor" }` | qualquer flag futuro não mapeado — repassar como está |
+
+## Operação `list` — proposta
+
+### O que a tool MCP envia (`operation: "list"`)
+
+```json
+{
+  "action": "list_systems",
+  "callspecs": [ { "command": "list_systems" } ],
+  "requestId": "req_...",
+  "timestamp": "..."
+}
+```
+
+Nenhum parâmetro além do `command`. O cliente deve devolver todos os sistemas atualmente
+disponíveis para `switch_system` (tanto os vindos do admin portal via `refresh_systems`, quanto os
+adicionados localmente via `add_system`).
+
+### Resposta esperada
+
+```json
+{
+  "type": "response",
+  "requestId": "req_...",
+  "success": true,
+  "data": {
+    "systems": [
+      { "systemId": "PIRA_S4D", "connectionType": "snc", "host": "vhlbvs4dci.sap.piracanjuba.com.br", "client": "100" },
+      { "systemId": "S4H_100", "connectionType": "basic", "host": "...", "client": "100" }
+    ]
+  }
+}
+```
+
+**Nunca incluir `password`/`caKey`/segredos no retorno** — só metadados de conexão (host,
+connectionType, client, etc.).
+
+## Operação `remove` — proposta
+
+### O que a tool MCP envia (`operation: "remove"`)
+
+```json
+{
+  "action": "remove_system",
+  "callspecs": [ { "command": "remove_system", "systemId": "PIRA_S4D" } ],
+  "requestId": "req_...",
+  "timestamp": "..."
+}
+```
+
+Se `systemId` não existir, responder `success: false` com erro claro (não travar). Se for o
+sistema ativo no momento, o cliente decide a política (ex.: bloquear remoção do sistema ativo, ou
+remover e cair para "nenhum sistema selecionado") — documentar a escolha feita.
+
+## Operação `update` — proposta
+
+### O que a tool MCP envia (`operation: "update"`)
+
+Mesmo formato de `add_system`, mas com `action: "update_system"` e apenas os campos que mudaram
+(mais `systemId` e, se estiver trocando o modo de autenticação, `connectionType` + todos os campos
+obrigatórios do novo modo):
+
+```json
+{
+  "action": "update_system",
+  "callspecs": [
+    {
+      "command": "update_system",
+      "systemId": "PIRA_S4D",
+      "host": "novo-host.sap.piracanjuba.com.br"
+    }
+  ],
+  "requestId": "req_...",
+  "timestamp": "..."
+}
+```
+
+Semântica esperada: **patch parcial** — só os campos presentes são alterados; os demais mantêm o
+valor já salvo. Se `systemId` não existir, responder `success: false` com erro claro.
+
+## O que o cliente deve responder (todas as operações)
+
+Mesmo formato de resposta que `switch_system`/`refresh_systems` já usam hoje — uma mensagem com
+`type: "response"` e o **mesmo `requestId`** recebido na requisição:
+
+**Sucesso (`add`/`remove`/`update`):**
+```json
+{
+  "type": "response",
+  "requestId": "req_1730900000000_abc123xyz",
+  "success": true,
+  "data": { "systemId": "PIRA_S4D", "message": "Sistema adicionado com sucesso" }
+}
+```
+
+**Falha (ex.: sistema já existe, host inválido, flag faltando, sistema não encontrado):**
+```json
+{
+  "type": "response",
+  "requestId": "req_1730900000000_abc123xyz",
+  "success": false,
+  "error": "Sistema PIRA_S4D já existe. Use update_system ou remova-o primeiro."
+}
+```
+
+**Importante:** para `add`/`remove`/`update`, `data` deve ser um **objeto simples, não um array** —
+o lado do servidor (`tool-wrapper.ts`) só faz parsing item-a-item quando `data` é array (usado
+pelas ações de ADT REST callspecs); para estes comandos o servidor apenas repassa a mensagem de
+sucesso fixa (`successMessage`) e ignora o conteúdo de `data` quando ele não é array — mas ainda
+assim mantenha `data` como objeto (nunca `null`/`undefined` em caso de sucesso) para consistência.
+Para `list`, `data.systems` deve ser um array (ver seção da operação `list` acima).
+
+## Regras de negócio a implementar
+
+1. **Idempotência clara (`add`):** se `systemId` já existir na config local, retornar
+   `success: false` com `error` explicando isso (não sobrescrever silenciosamente, e não
+   travar/crashar).
+2. **Validação por `connectionType` (`add`/`update`):** usar a tabela de obrigatórios/opcionais
+   acima. Se faltar campo obrigatório, responder `success: false` com `error` claro dizendo qual
+   campo falta — não travar o processo do cliente.
+3. **Rejeitar `saprouter` fora de `basic`/`snc`** — se vier em `spnego`/`x509`/`saml`, é um uso
+   indevido (a tool MCP já bloqueia isso do lado do servidor, mas validar de novo no cliente é
+   defesa em profundidade).
+4. **Nunca logar `password`/`caKey` em texto puro** (nem em stdout/console, nem no arquivo de
+   config em texto simples se possível).
+5. **Nunca ecoar `password`/`caKey` de volta** — nem no campo `data` da resposta de sucesso de
+   `add`/`update`, nem na listagem de `list`.
+6. **Comando desconhecido:** se o cliente ainda não tiver essa versão implementada e receber
+   `action` desconhecido (`add_system`, `list_systems`, `remove_system` ou `update_system`),
+   responder `success: false, error: "Comando '<action>' não suportado nesta versão do cliente. Atualize com: npx abap-local-client@latest"`
+   em vez de travar/ignorar silenciosamente — dá um erro legível no chat em vez de timeout
+   genérico.
+7. **`remove`/`update` de sistema inexistente:** responder `success: false` com erro claro
+   ("Sistema X não encontrado"), nunca criar um novo registro como efeito colateral.
+
+## Como testar de ponta a ponta
+
+1. Atualizar o `abap-local-client` local para a versão com os handlers novos, já conectado ao MCP
+   server (`abap-mcp`) com uma API key válida.
+2. No chat/Cursor, chamar a tool MCP (exemplo `add`, modo `snc`):
+   ```json
+   {
+     "operation": "add",
+     "system_id": "PIRA_S4D",
+     "connection_type": "snc",
+     "host": "vhlbvs4dci.sap.piracanjuba.com.br",
+     "sysnr": "00",
+     "client": "100",
+     "snc_partner_name": "p:CN=svc.ssoS4D",
+     "language": "PT"
+   }
+   ```
+3. Confirmar que o sistema aparece disponível para `adt_switch_system({ system: "PIRA_S4D" })`.
+4. Chamar `{ "operation": "list" }` e confirmar que `PIRA_S4D` aparece na lista.
+5. Repetir a chamada de `add` — deve retornar erro claro de "já existe", não duplicar nem quebrar.
+6. Chamar `{ "operation": "update", "system_id": "PIRA_S4D", "language": "EN" }` e confirmar via
+   `list` que só `language` mudou.
+7. Chamar `{ "operation": "remove", "system_id": "PIRA_S4D" }` e confirmar via `list` que sumiu.
+8. Repetir o teste de `add` para os outros 4 modos (`basic`, `spnego`, `x509`, `saml`) com dados de
+   exemplo.
+
+## Referência — arquivos do lado do servidor (abap-mcp, já implementado)
+
+- `src/tools/system/manage-systems.ts` — definição e handler da tool MCP `adt_manage_systems`
+  (operations: add, list, remove, update)
+- `src/websocket/tool-wrapper.ts` — `executeWithWebSocketFallback()`, monta o envelope `{ action, callspecs }`
+- `src/websocket/connection-manager.ts` — `sendRequest()` adiciona `requestId`/`timestamp` e espera resposta com `type: "response"`
+- `src/tools/system/switch-system.ts` / `refresh-systems.ts` — exemplos já funcionando do mesmo padrão de comando (ficam como tools separadas, não fazem parte de `adt_manage_systems`)

package/config-cli.mjs

@@ -151,73 +151,13 @@ switch (command) {
             process.exit(1);
         }
 
-        const validModes = ['basic', 'spnego', 'x509', 'saml', 'snc'];
-        if (!validModes.includes(authMode)) {
-            console.error(`Invalid auth mode: ${authMode}. Use: ${validModes.join(', ')}`);
+        if (!config.VALID_AUTH_MODES.includes(authMode)) {
+            console.error(`Invalid auth mode: ${authMode}. Use: ${config.VALID_AUTH_MODES.join(', ')}`);
             process.exit(1);
         }
 
         const opts = parseKeyValue(args.slice(3));
-
-        // Build connection object based on auth mode
-        let connection = {};
-        switch (authMode) {
-            case 'basic':
-                connection = {
-                    host: opts.host || 'localhost',
-                    port: opts.port || '44301',
-                    client: opts.client || '100',
-                    username: opts.username || '',
-                    password: opts.password || '',
-                    saprouter: opts.saprouter || '',
-                    language: opts.language || 'EN',
-                };
-                break;
-            case 'spnego':
-                connection = {
-                    host: opts.host || '',
-                    port: opts.port || '44301',
-                    client: opts.client || '100',
-                    servicePrincipal: opts.service_principal || '',
-                    language: opts.language || 'EN',
-                };
-                break;
-            case 'x509':
-                connection = {
-                    host: opts.host || '',
-                    port: opts.port || '44301',
-                    client: opts.client || '100',
-                    caCertPem: opts.ca_cert || '',
-                    caKeyPem: opts.ca_key || '',
-                    loginIdentifier: opts.login_id || '',
-                    validityMinutes: parseInt(opts.validity_minutes || '5', 10),
-                    language: opts.language || 'EN',
-                };
-                break;
-            case 'saml':
-                connection = {
-                    baseUrl: opts.base_url || '',
-                    client: opts.client || '100',
-                    headless: opts.headless === 'true',
-                    loginTimeoutMs: parseInt(opts.timeout_ms || '600000', 10),
-                    language: opts.language || 'EN',
-                };
-                break;
-            case 'snc':
-                connection = {
-                    host: opts.host || '',
-                    sysnr: opts.sysnr || '00',
-                    client: opts.client || '100',
-                    username: opts.username || '',
-                    saprouter: opts.saprouter || '',
-                    sncPartnerName: opts.snc_partner_name || '',
-                    sncMyName: opts.snc_my_name || '',
-                    sncQop: opts.snc_qop || '3',
-                    sncLib: opts.snc_lib || '',
-                    language: opts.language || 'EN',
-                };
-                break;
-        }
+        const connection = config.buildConnection(authMode, opts);
 
         config.addOrUpdateSystem(systemId, { authMode, connection, enabled: true });
         console.log(`✅ System "${systemId}" (${authMode}) saved.`);

package/config-manager.mjs

@@ -207,6 +207,133 @@ export function addOrUpdateSystem(systemId, systemConfig) {
     saveConfig(config);
 }
 
+/**
+ * Auth-mode metadata: required/optional connection fields.
+ * Keys match the internal `opts` naming used by buildConnection() (snake_case,
+ * mirroring the CLI's --flag-name → flag_name convention).
+ */
+export const AUTH_MODE_FIELDS = {
+    basic:  { required: ['host', 'port', 'client', 'username', 'password'], optional: ['saprouter', 'language'] },
+    spnego: { required: ['host', 'port', 'client'], optional: ['service_principal', 'language'] },
+    x509:   { required: ['host', 'port', 'client', 'ca_cert', 'ca_key', 'login_id'], optional: ['language'] },
+    saml:   { required: ['base_url', 'client'], optional: ['headless', 'timeout_ms', 'language'] },
+    snc:    { required: ['host', 'sysnr', 'client', 'snc_partner_name'], optional: ['snc_my_name', 'snc_qop', 'snc_lib', 'username', 'saprouter', 'language'] },
+};
+
+export const VALID_AUTH_MODES = Object.keys(AUTH_MODE_FIELDS);
+
+/**
+ * Build a `connection` object for a system from raw options, honoring the
+ * same defaults for every auth mode. Shared by config-cli.mjs (CLI) and
+ * sso-sap-client.mjs (WebSocket `add_system` command) so both entry points
+ * behave identically.
+ * @param {string} authMode - basic|spnego|x509|saml|snc
+ * @param {object} opts - snake_case keys (host, port, sysnr, client, username,
+ *   password, saprouter, language, service_principal, ca_cert, ca_key,
+ *   login_id, validity_minutes, base_url, headless, timeout_ms,
+ *   snc_partner_name, snc_my_name, snc_qop, snc_lib)
+ * @returns {object} connection
+ */
+export function buildConnection(authMode, opts = {}) {
+    const isTrue = (v) => v === true || v === 'true';
+    switch (authMode) {
+        case 'basic':
+            return {
+                host: opts.host || 'localhost',
+                port: opts.port || '44301',
+                client: opts.client || '100',
+                username: opts.username || '',
+                password: opts.password || '',
+                saprouter: opts.saprouter || '',
+                language: opts.language || 'EN',
+            };
+        case 'spnego':
+            return {
+                host: opts.host || '',
+                port: opts.port || '44301',
+                client: opts.client || '100',
+                servicePrincipal: opts.service_principal || '',
+                language: opts.language || 'EN',
+            };
+        case 'x509':
+            return {
+                host: opts.host || '',
+                port: opts.port || '44301',
+                client: opts.client || '100',
+                caCertPem: opts.ca_cert || '',
+                caKeyPem: opts.ca_key || '',
+                loginIdentifier: opts.login_id || '',
+                validityMinutes: parseInt(opts.validity_minutes || '5', 10),
+                language: opts.language || 'EN',
+            };
+        case 'saml':
+            return {
+                baseUrl: opts.base_url || '',
+                client: opts.client || '100',
+                headless: isTrue(opts.headless),
+                loginTimeoutMs: parseInt(opts.timeout_ms || '600000', 10),
+                language: opts.language || 'EN',
+            };
+        case 'snc':
+            return {
+                host: opts.host || '',
+                sysnr: opts.sysnr || '00',
+                client: opts.client || '100',
+                username: opts.username || '',
+                saprouter: opts.saprouter || '',
+                sncPartnerName: opts.snc_partner_name || '',
+                sncMyName: opts.snc_my_name || '',
+                sncQop: opts.snc_qop || '3',
+                sncLib: opts.snc_lib || '',
+                language: opts.language || 'EN',
+            };
+        default:
+            return {};
+    }
+}
+
+/**
+ * Validate that all required fields for an auth mode are present (non-empty)
+ * in opts. Returns an array of missing field names (snake_case), empty if OK.
+ */
+export function getMissingRequiredFields(authMode, opts = {}) {
+    const spec = AUTH_MODE_FIELDS[authMode];
+    if (!spec) return [`unknown authMode: ${authMode}`];
+    return spec.required.filter((f) => {
+        const v = opts[f];
+        return v === undefined || v === null || v === '';
+    });
+}
+
+// Fields that must never be exposed outside the encrypted local store
+// (e.g. in list_systems responses sent back to the MCP server).
+const SENSITIVE_CONNECTION_FIELDS = ['password', 'caKeyPem'];
+
+/**
+ * Return a copy of a connection object with secrets stripped out.
+ * @param {object} connection
+ */
+export function sanitizeConnection(connection = {}) {
+    const clean = { ...connection };
+    for (const f of SENSITIVE_CONNECTION_FIELDS) delete clean[f];
+    return clean;
+}
+
+/**
+ * List all systems with sanitized connection metadata (no secrets).
+ * Used by the WebSocket `list_systems` command.
+ * @returns {object[]} [{ systemId, connectionType, enabled, host, client, ... }]
+ */
+export function listSystemsDetailed() {
+    const cfg = loadConfig();
+    return Object.entries(cfg.systems).map(([id, sys]) => ({
+        systemId: id,
+        connectionType: sys.authMode || 'basic',
+        enabled: sys.enabled !== false,
+        ...sanitizeConnection(sys.connection || {}),
+    }));
+}
+
 /**
  * Remove a system by ID.
  * @param {string} systemId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abap-local-client",
-  "version": "1.4.14",
+  "version": "1.4.17",
   "description": "SAP Local Client — WebSocket bridge with Basic, SPNEGO, X.509, SAML & SNC authentication",
   "main": "sso-sap-client.mjs",
   "type": "module",

package/sso-sap-client.mjs

@@ -21,6 +21,196 @@ function resolveUsername(conn) {
     return (conn.username || '').toUpperCase();
 }
 
+// ════════════════════════════════════════════════════════════════════════════
+// add_system — handles the MCP `add_system` WebSocket command
+// ════════════════════════════════════════════════════════════════════════════
+
+// Maps the camelCase JSON fields sent by the MCP server to the snake_case
+// `opts` keys expected by config.buildConnection()/getMissingRequiredFields().
+const ADD_SYSTEM_FIELD_MAP = {
+    host: 'host',
+    port: 'port',
+    sysnr: 'sysnr',
+    client: 'client',
+    language: 'language',
+    username: 'username',
+    password: 'password',
+    saprouter: 'saprouter',
+    servicePrincipal: 'service_principal',
+    caCert: 'ca_cert',
+    caKey: 'ca_key',
+    loginId: 'login_id',
+    baseUrl: 'base_url',
+    headless: 'headless',
+    timeoutMs: 'timeout_ms',
+    sncPartnerName: 'snc_partner_name',
+    sncMyName: 'snc_my_name',
+    sncQop: 'snc_qop',
+    sncLib: 'snc_lib',
+};
+const OPTS_TO_FIELD_MAP = Object.fromEntries(Object.entries(ADD_SYSTEM_FIELD_MAP).map(([k, v]) => [v, k]));
+
+function kebabToCamel(str) {
+    return str.replace(/[-_]([a-z0-9])/gi, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Handle the `add_system` command: validate the payload and persist a new
+ * SAP system into the encrypted local config, using the same connection
+ * builder as the `add-system` CLI command.
+ * @param {object} spec - callspecs[0] payload from the MCP server
+ * @returns {{ success: boolean, data?: object, error?: string }}
+ */
+function handleAddSystem(spec = {}) {
+    const systemId = String(spec.systemId || '').trim().toUpperCase();
+    const authMode = String(spec.connectionType || spec.authMode || '').trim().toLowerCase();
+
+    if (!systemId) return { success: false, error: 'systemId é obrigatório.' };
+    if (!config.VALID_AUTH_MODES.includes(authMode)) {
+        return { success: false, error: `connectionType inválido: "${spec.connectionType || ''}". Use um de: ${config.VALID_AUTH_MODES.join(', ')}.` };
+    }
+    if (config.getSystem(systemId)) {
+        return { success: false, error: `Sistema "${systemId}" já existe. Remova-o primeiro (remove-system) ou use outro systemId.` };
+    }
+    if (spec.saprouter && !['basic', 'snc'].includes(authMode)) {
+        return { success: false, error: `"saprouter" não é suportado no modo "${authMode}" (apenas basic/snc).` };
+    }
+
+    const opts = {};
+    for (const [jsonKey, optsKey] of Object.entries(ADD_SYSTEM_FIELD_MAP)) {
+        if (spec[jsonKey] !== undefined && spec[jsonKey] !== null) opts[optsKey] = spec[jsonKey];
+    }
+
+    const missing = config.getMissingRequiredFields(authMode, opts);
+    if (missing.length > 0) {
+        const friendly = missing.map(f => OPTS_TO_FIELD_MAP[f] || f);
+        return { success: false, error: `Campo(s) obrigatório(s) faltando para o modo "${authMode}": ${friendly.join(', ')}.` };
+    }
+
+    const connection = config.buildConnection(authMode, opts);
+
+    // Pass through any future/unmapped flags verbatim (kebab-case → camelCase)
+    if (spec.extraParams && typeof spec.extraParams === 'object') {
+        for (const [k, v] of Object.entries(spec.extraParams)) connection[kebabToCamel(k)] = v;
+    }
+
+    config.addOrUpdateSystem(systemId, { authMode, connection, enabled: true });
+    console.log(`   ✅ System "${systemId}" (${authMode}) added via add_system command`);
+    return { success: true, data: { systemId, message: 'Sistema adicionado com sucesso' } };
+}
+
+/**
+ * Handle the `list_systems` command: return all configured systems with
+ * sanitized connection metadata (no password/caKey).
+ * @returns {{ success: boolean, data: { systems: object[] } }}
+ */
+function handleListSystems() {
+    return { success: true, data: { systems: config.listSystemsDetailed() } };
+}
+
+/**
+ * Handle the `remove_system` command.
+ * @param {object} spec - callspecs[0] payload from the MCP server
+ * @returns {{ success: boolean, data?: object, error?: string }}
+ */
+function handleRemoveSystem(spec = {}) {
+    const systemId = String(spec.systemId || '').trim().toUpperCase();
+    if (!systemId) return { success: false, error: 'systemId é obrigatório.' };
+    if (!config.getSystem(systemId)) {
+        return { success: false, error: `Sistema "${systemId}" não encontrado.` };
+    }
+    config.removeSystem(systemId);
+    console.log(`   🗑️  System "${systemId}" removed via remove_system command`);
+    return { success: true, data: { systemId, message: 'Sistema removido com sucesso' } };
+}
+
+// Maps the camelCase JSON fields sent by the MCP server directly to the
+// `connection` object's own key names (used for partial-patch merges in
+// update_system — different from ADD_SYSTEM_FIELD_MAP, which maps to the
+// snake_case `opts` keys consumed by buildConnection()).
+const CONNECTION_FIELD_MAP = {
+    host: 'host',
+    port: 'port',
+    sysnr: 'sysnr',
+    client: 'client',
+    language: 'language',
+    username: 'username',
+    password: 'password',
+    saprouter: 'saprouter',
+    servicePrincipal: 'servicePrincipal',
+    caCert: 'caCertPem',
+    caKey: 'caKeyPem',
+    loginId: 'loginIdentifier',
+    baseUrl: 'baseUrl',
+    headless: 'headless',
+    sncPartnerName: 'sncPartnerName',
+    sncMyName: 'sncMyName',
+    sncQop: 'sncQop',
+    sncLib: 'sncLib',
+};
+
+/**
+ * Handle the `update_system` command.
+ * - If `connectionType` is absent (or unchanged), applies a partial patch:
+ *   only the provided fields are overwritten, everything else is preserved.
+ * - If `connectionType` differs from the stored mode, treats the payload like
+ *   a fresh `add_system` for the new mode (full required-field validation,
+ *   connection rebuilt from scratch — old mode's fields don't carry over).
+ * @param {object} spec - callspecs[0] payload from the MCP server
+ * @returns {{ success: boolean, data?: object, error?: string }}
+ */
+function handleUpdateSystem(spec = {}) {
+    const systemId = String(spec.systemId || '').trim().toUpperCase();
+    if (!systemId) return { success: false, error: 'systemId é obrigatório.' };
+    const existing = config.getSystem(systemId);
+    if (!existing) return { success: false, error: `Sistema "${systemId}" não encontrado.` };
+
+    let newMode = null;
+    if (spec.connectionType !== undefined && spec.connectionType !== null && String(spec.connectionType).trim() !== '') {
+        newMode = String(spec.connectionType).trim().toLowerCase();
+        if (!config.VALID_AUTH_MODES.includes(newMode)) {
+            return { success: false, error: `connectionType inválido: "${spec.connectionType}". Use um de: ${config.VALID_AUTH_MODES.join(', ')}.` };
+        }
+    }
+    const switchingMode = newMode !== null && newMode !== existing.authMode;
+    const effectiveMode = newMode || existing.authMode;
+
+    if (spec.saprouter && !['basic', 'snc'].includes(effectiveMode)) {
+        return { success: false, error: `"saprouter" não é suportado no modo "${effectiveMode}" (apenas basic/snc).` };
+    }
+
+    let connection;
+    if (switchingMode) {
+        const opts = {};
+        for (const [jsonKey, optsKey] of Object.entries(ADD_SYSTEM_FIELD_MAP)) {
+            if (spec[jsonKey] !== undefined && spec[jsonKey] !== null) opts[optsKey] = spec[jsonKey];
+        }
+        const missing = config.getMissingRequiredFields(effectiveMode, opts);
+        if (missing.length > 0) {
+            const friendly = missing.map(f => OPTS_TO_FIELD_MAP[f] || f);
+            return { success: false, error: `Campo(s) obrigatório(s) faltando para o modo "${effectiveMode}": ${friendly.join(', ')}.` };
+        }
+        connection = config.buildConnection(effectiveMode, opts);
+    } else {
+        connection = { ...(existing.connection || {}) };
+        for (const [jsonKey, connKey] of Object.entries(CONNECTION_FIELD_MAP)) {
+            if (spec[jsonKey] === undefined || spec[jsonKey] === null) continue;
+            connection[connKey] = jsonKey === 'headless' ? (spec[jsonKey] === true || spec[jsonKey] === 'true') : spec[jsonKey];
+        }
+        if (spec.timeoutMs !== undefined && spec.timeoutMs !== null && effectiveMode === 'saml') {
+            connection.loginTimeoutMs = parseInt(spec.timeoutMs, 10);
+        }
+    }
+
+    if (spec.extraParams && typeof spec.extraParams === 'object') {
+        for (const [k, v] of Object.entries(spec.extraParams)) connection[kebabToCamel(k)] = v;
+    }
+
+    config.addOrUpdateSystem(systemId, { authMode: effectiveMode, connection, enabled: existing.enabled !== false });
+    console.log(`   ✅ System "${systemId}" updated via update_system command${switchingMode ? ` (mode: ${existing.authMode} → ${effectiveMode})` : ''}`);
+    return { success: true, data: { systemId, message: 'Sistema atualizado com sucesso' } };
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // Multi-system auth session cache
 // ════════════════════════════════════════════════════════════════════════════
@@ -327,10 +517,11 @@ class LockManager {
 // ════════════════════════════════════════════════════════════════════════════
 
 class SAPClient {
-  constructor(sessionEntry) {
+  constructor(sessionEntry, onSessionCleared) {
     this.session = sessionEntry;
     this.csrfToken = null;
     this.cookies = new Map();
+    this.onSessionCleared = onSessionCleared || null;
 
     const conn = sessionEntry.sysConfig?.connection || {};
     const baseUrl = `https://${conn.host}:${conn.port || '44301'}`;
@@ -386,8 +577,20 @@ class SAPClient {
         return response;
       },
       error => {
-        if (error.response?.status === 401 || error.response?.status === 403) {
-          console.error(`   ⚠️  Session error (${error.response.status}) - clearing...`);
+        // NOTE: only 401 (true auth/session failure) wipes the session here.
+        // 403 is deliberately NOT treated as "session invalid" — SAP ADT also
+        // returns 403 for business-logic errors that have nothing to do with
+        // the HTTP session (e.g. "object locked by another user", missing
+        // authorization for a specific object, or "CSRF token required").
+        // Blindly clearing cookies/CSRF on every 403 used to nuke a perfectly
+        // valid stateful session in the middle of a lock/save/activate flow,
+        // orphaning any lock the client held (SAP kept the enqueue tied to the
+        // now-discarded session/cookie, while the client silently opened a
+        // brand-new anonymous session for the next call). CSRF-required 403s
+        // are instead handled locally with a scoped refresh+retry in
+        // _executeCallspecViaHTTP.
+        if (error.response?.status === 401) {
+          console.error(`   ⚠️  Session error (401) - clearing...`);
           this.clearSession();
         }
         return Promise.reject(error);
@@ -487,7 +690,7 @@ class SAPClient {
     }
   }
 
-  async _executeCallspecViaHTTP(callspec) {
+  async _executeCallspecViaHTTP(callspec, isCsrfRetry = false) {
     const { method, url, headers, extract_from_response } = callspec;
     let finalUrl = url;
     let finalHeaders = { ...headers };
@@ -578,6 +781,22 @@ class SAPClient {
       return { success: !hasErrors && response.status >= 200 && response.status < 300, status: response.status, statusText: response.statusText, headers: response.headers, data: { raw: response.data, ...extractedData }, ...(errorMessages.length > 0 && { error: `SAP validation failed: ${errorMessages.join('; ')}`, errorDetails: errorMessages }) };
     } catch (error) {
       const status = error.response?.status;
+
+      // ── CSRF-required retry (scoped, one-shot) ──────────────────────────
+      // SAP responds 403 with `x-csrf-token: Required` when the cached token
+      // is stale/missing — this is NOT a session-invalidating error, it just
+      // means we need a fresh token. Refresh it and retry this one request
+      // exactly once, instead of relying on the (now-removed) blanket
+      // session wipe that used to happen for every 403 in the interceptor.
+      const csrfHeader = (error.response?.headers?.['x-csrf-token'] || '').toLowerCase();
+      if (status === 403 && csrfHeader === 'required' && !isCsrfRetry) {
+        console.warn('   🔄 CSRF token rejected (Required) — refreshing token and retrying once...');
+        this.csrfToken = null;
+        await this.fetchCsrfToken();
+        if (this.csrfToken) return this._executeCallspecViaHTTP(callspec, true);
+        console.error('   ❌ CSRF refresh failed — no token obtained, giving up on retry');
+      }
+
       console.error(`   ❌ HTTP ${status || 'network error'}: ${error.message}`);
       if (error.response?.headers) {
         console.error(`   ❌ RESPONSE HEADERS:`);
@@ -613,7 +832,17 @@ class SAPClient {
     catch (error) { if (error.response?.headers['x-csrf-token']) this.csrfToken = error.response.headers['x-csrf-token']; }
   }
 
-  clearSession() { this.csrfToken = null; this.cookies.clear(); console.log('   🧹 Session cleared'); }
+  clearSession() {
+    this.csrfToken = null;
+    this.cookies.clear();
+    console.log('   🧹 Session cleared');
+    // The stateful ADT session that owned any cached locks is gone — a lock
+    // handle cached against it is now orphaned, so tell the caller to drop it
+    // too (mirrors the RFC-side stale-lock cleanup on 423).
+    if (this.onSessionCleared) {
+      try { this.onSessionCleared(); } catch { /* best-effort */ }
+    }
+  }
 
   async ping() {
     try { const r = await this.client.get('/sap/bc/adt/compatibility/graph', { timeout: 5000 }); return { success: true, status: r.status }; }
@@ -631,6 +860,8 @@ class WebSocketClient {
     this.sapClient = null;
     this.reconnectTimer = null;
     this.keepAliveTimer = null;
+    this.wsPingTimer = null;
+    this.isAlive = false;
     this.isReconnecting = false;
     this.lockManager = new LockManager();
     this.currentSystemId = null;
@@ -641,7 +872,10 @@ class WebSocketClient {
     if (!sid) { console.error('❌ No system selected'); return false; }
     try {
         const sessionEntry = await getSessionForSystem(sid);
-        this.sapClient = new SAPClient(sessionEntry);
+        this.sapClient = new SAPClient(sessionEntry, () => {
+          this.lockManager.clearAll();
+          console.log('   🗑️  Lock cache cleared (HTTP session was reset — cached locks are now orphaned)');
+        });
         console.log(`✅ SAPClient initialized for ${sid}`);
         return true;
     } catch (err) {
@@ -659,10 +893,12 @@ class WebSocketClient {
     console.log(`\n🔌 Connecting to MCP Cloud...`);
     console.log(`   URL: ${WS_URL}`);
     this.ws = new WebSocket(WS_URL, { headers: { 'Authorization': `Bearer ${MCP_API_KEY}` } });
+    this.isAlive = true;
     this.ws.on('open', () => this.onOpen());
     this.ws.on('message', (data) => this.onMessage(data));
     this.ws.on('error', (error) => this.onError(error));
     this.ws.on('close', () => this.onClose());
+    this.ws.on('pong', () => { this.isAlive = true; });
   }
 
   onOpen() {
@@ -670,6 +906,7 @@ class WebSocketClient {
     if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
     this.isReconnecting = false;
     this.startKeepAlive();
+    this.startWsPing();
   }
 
   startKeepAlive() {
@@ -682,6 +919,24 @@ class WebSocketClient {
 
   stopKeepAlive() { if (this.keepAliveTimer) { clearInterval(this.keepAliveTimer); this.keepAliveTimer = null; } }
 
+  // WebSocket-frame-level heartbeat (independent of the SAP keepalive above).
+  // Tunnels/proxies (e.g. ngrok) silently drop idle connections that have no
+  // traffic for a while. Sending a ping every WS_PING_INTERVAL ms keeps the
+  // tunnel alive and — if a pong doesn't come back in time — proactively
+  // terminates the dead socket so reconnection kicks in immediately instead
+  // of waiting for the OS to notice the broken connection.
+  startWsPing() {
+    if (this.wsPingTimer) clearInterval(this.wsPingTimer);
+    this.wsPingTimer = setInterval(() => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+      if (!this.isAlive) { console.log('   💔 No pong received — terminating stale connection'); this.ws.terminate(); return; }
+      this.isAlive = false;
+      this.ws.ping();
+    }, parseInt(env.WS_PING_INTERVAL || '20000', 10));
+  }
+
+  stopWsPing() { if (this.wsPingTimer) { clearInterval(this.wsPingTimer); this.wsPingTimer = null; } }
+
   async onMessage(data) {
     let message;
     try { message = JSON.parse(data.toString()); } catch { return; }
@@ -712,6 +967,84 @@ class WebSocketClient {
         return;
       }
 
+      // ── add_system ─────────────────────────────────────────────────────
+      if (action === 'add_system') {
+        const spec = Array.isArray(callspecs) ? (callspecs[0] || {}) : (callspecs || {});
+        try {
+          const result = handleAddSystem(spec);
+          if (result.success) this.sendResponse(requestId, true, result.data);
+          else this.sendResponse(requestId, false, { error: result.error });
+        } catch (err) {
+          console.error(`❌ add_system error: ${err.message}`);
+          this.sendResponse(requestId, false, { error: err.message });
+        }
+        return;
+      }
+
+      // ── list_systems ───────────────────────────────────────────────────
+      if (action === 'list_systems') {
+        try {
+          const result = handleListSystems();
+          this.sendResponse(requestId, true, result.data);
+        } catch (err) {
+          console.error(`❌ list_systems error: ${err.message}`);
+          this.sendResponse(requestId, false, { error: err.message });
+        }
+        return;
+      }
+
+      // ── remove_system ──────────────────────────────────────────────────
+      if (action === 'remove_system') {
+        const spec = Array.isArray(callspecs) ? (callspecs[0] || {}) : (callspecs || {});
+        try {
+          const result = handleRemoveSystem(spec);
+          if (result.success) {
+            const removedId = result.data.systemId;
+            sessions.delete(removedId);
+            // Policy: removing the currently active system clears the active
+            // session (falls back to "no system selected") instead of leaving
+            // a dangling stale sapClient pointed at a config that no longer exists.
+            if (this.currentSystemId === removedId) {
+              this.sapClient = null;
+              this.currentSystemId = null;
+              this.lockManager.clearAll();
+              console.log(`   ⚠️  Active system "${removedId}" was removed — session cleared, no system selected.`);
+            }
+            this.sendResponse(requestId, true, result.data);
+          } else {
+            this.sendResponse(requestId, false, { error: result.error });
+          }
+        } catch (err) {
+          console.error(`❌ remove_system error: ${err.message}`);
+          this.sendResponse(requestId, false, { error: err.message });
+        }
+        return;
+      }
+
+      // ── update_system ──────────────────────────────────────────────────
+      if (action === 'update_system') {
+        const spec = Array.isArray(callspecs) ? (callspecs[0] || {}) : (callspecs || {});
+        try {
+          const result = handleUpdateSystem(spec);
+          if (result.success) {
+            const updatedId = result.data.systemId;
+            // Invalidate any cached session so the next call re-reads the
+            // fresh config instead of reusing stale connection details.
+            if (this.currentSystemId === updatedId) {
+              sessions.delete(updatedId);
+              this.sapClient = null;
+            }
+            this.sendResponse(requestId, true, result.data);
+          } else {
+            this.sendResponse(requestId, false, { error: result.error });
+          }
+        } catch (err) {
+          console.error(`❌ update_system error: ${err.message}`);
+          this.sendResponse(requestId, false, { error: err.message });
+        }
+        return;
+      }
+
       // ── invoke_rfc ─────────────────────────────────────────────────────
       if (action === 'invoke_rfc') {
         if (!this.sapClient?.rfcClient) { this.sendResponse(requestId, false, { error: 'No RFC session' }); return; }
@@ -879,19 +1212,20 @@ class WebSocketClient {
 
   onClose() {
     console.log(`\n⚠️  Disconnected`);
-    this.ws = null; this.stopKeepAlive();
+    this.ws = null; this.stopKeepAlive(); this.stopWsPing();
     if (this.sapClient) this.sapClient.clearSession();
     this.lockManager.clearAll();
     if (!this.isReconnecting && !this.reconnectTimer) {
-      console.log(`   Reconnecting in 5s...`);
+      const delayMs = parseInt(env.WS_RECONNECT_DELAY || '2000', 10);
+      console.log(`   Reconnecting in ${(delayMs / 1000).toFixed(1)}s...`);
       this.isReconnecting = true;
-      this.reconnectTimer = setTimeout(() => { this.isReconnecting = false; this.connect(); }, 5000);
+      this.reconnectTimer = setTimeout(() => { this.isReconnecting = false; this.connect(); }, delayMs);
     }
   }
 
   disconnect() {
     if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
-    this.isReconnecting = false; this.stopKeepAlive();
+    this.isReconnecting = false; this.stopKeepAlive(); this.stopWsPing();
     if (this.ws) { this.ws.close(); this.ws = null; }
   }
 }