@saulwade/swl-ses 1.0.0

package/hooks/lib/mcp-health.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * MCP Health Tracker — Rastreo de salud de servidores MCP.
+ *
+ * Registra fallos de tool calls MCP y marca servidores como unhealthy
+ * cuando acumulan fallos consecutivos. Sugiere reconexion o alternativas.
+ *
+ * Inspirado en ECC mcp-health-check.js.
+ * Zero-dependencies: estado en memoria por sesion.
+ *
+ * Integracion:
+ *   - risk-scoring.js puede consultar getHealth() como factor de riesgo
+ *   - inyeccion-contexto.js puede reportar MCPs unhealthy al inicio
+ *
+ * @module hooks/lib/mcp-health
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Fallos consecutivos antes de marcar como unhealthy. */
+const FAILURE_THRESHOLD = 3;
+
+/** Tiempo en ms antes de reintentar un MCP unhealthy (5 minutos). */
+const RECOVERY_COOLDOWN_MS = 5 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Estado en memoria
+// ---------------------------------------------------------------------------
+
+/**
+ * Map<serverName, { failures: number, lastFailure: number, healthy: boolean, lastError: string }>
+ */
+const _mcpState = new Map();
+
+// ---------------------------------------------------------------------------
+// API publica
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra un fallo de un tool call MCP.
+ *
+ * @param {string} serverName - Nombre del servidor MCP (ej: "aidesigner", "context7").
+ * @param {string} toolName - Nombre de la herramienta que fallo.
+ * @param {string} [error=''] - Mensaje de error.
+ * @returns {{ healthy: boolean, failures: number, shouldRetry: boolean }}
+ */
+function recordFailure(serverName, toolName, error) {
+  if (!serverName) return { healthy: true, failures: 0, shouldRetry: false };
+
+  let state = _mcpState.get(serverName);
+  if (!state) {
+    state = { failures: 0, lastFailure: 0, healthy: true, lastError: '', tools: new Set() };
+    _mcpState.set(serverName, state);
+  }
+
+  state.failures++;
+  state.lastFailure = Date.now();
+  state.lastError = error || '';
+  state.tools.add(toolName);
+
+  if (state.failures >= FAILURE_THRESHOLD) {
+    state.healthy = false;
+  }
+
+  return {
+    healthy: state.healthy,
+    failures: state.failures,
+    shouldRetry: state.healthy, // solo reintentar si aun no es unhealthy
+  };
+}
+
+/**
+ * Registra un exito de un tool call MCP. Resetea el contador de fallos.
+ *
+ * @param {string} serverName
+ */
+function recordSuccess(serverName) {
+  if (!serverName) return;
+
+  let state = _mcpState.get(serverName);
+  if (!state) return;
+
+  state.failures = 0;
+  state.healthy = true;
+  state.lastError = '';
+}
+
+/**
+ * Verifica si un servidor MCP esta healthy antes de usarlo.
+ * Si esta unhealthy pero paso el cooldown, lo marca como half-open
+ * (permite un intento de recuperacion).
+ *
+ * @param {string} serverName
+ * @returns {{ healthy: boolean, reason?: string, cooldownRemaining?: number }}
+ */
+function checkHealth(serverName) {
+  if (!serverName) return { healthy: true };
+
+  const state = _mcpState.get(serverName);
+  if (!state) return { healthy: true };
+
+  if (state.healthy) return { healthy: true };
+
+  // Verificar si paso el cooldown para half-open recovery
+  const elapsed = Date.now() - state.lastFailure;
+  if (elapsed >= RECOVERY_COOLDOWN_MS) {
+    // Half-open: permitir un intento
+    state.failures = FAILURE_THRESHOLD - 1; // un fallo mas lo marca unhealthy de nuevo
+    state.healthy = true;
+    return { healthy: true, reason: 'half-open recovery' };
+  }
+
+  const remaining = Math.ceil((RECOVERY_COOLDOWN_MS - elapsed) / 1000);
+  return {
+    healthy: false,
+    reason: `MCP "${serverName}" marcado como unhealthy despues de ${state.failures} fallos consecutivos. Ultimo error: ${state.lastError}. Reintento en ${remaining}s.`,
+    cooldownRemaining: remaining,
+  };
+}
+
+/**
+ * Obtiene el estado de salud de todos los MCPs rastreados.
+ *
+ * @returns {Array<{ server: string, healthy: boolean, failures: number, lastError: string }>}
+ */
+function getHealthReport() {
+  const report = [];
+  for (const [server, state] of _mcpState) {
+    report.push({
+      server,
+      healthy: state.healthy,
+      failures: state.failures,
+      lastError: state.lastError,
+      tools: Array.from(state.tools),
+    });
+  }
+  return report;
+}
+
+/**
+ * Detecta servidores MCP configurados leyendo .mcp.json del proyecto.
+ *
+ * @param {string} [cwd] - Directorio del proyecto.
+ * @returns {string[]} Nombres de servidores MCP configurados.
+ */
+function detectConfiguredMCPs(cwd) {
+  const dir = cwd || process.cwd();
+  const mcpPath = path.join(dir, '.mcp.json');
+  try {
+    const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    return Object.keys(config.mcpServers || {});
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resetea todo el estado de salud.
+ */
+function resetAll() {
+  _mcpState.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  recordFailure,
+  recordSuccess,
+  checkHealth,
+  getHealthReport,
+  detectConfiguredMCPs,
+  resetAll,
+  FAILURE_THRESHOLD,
+  RECOVERY_COOLDOWN_MS,
+};

package/hooks/lib/mcp-pool.js

@@ -0,0 +1,436 @@
+'use strict';
+
+/**
+ * mcp-pool.js
+ *
+ * Pool de clientes MCP con lazy initialization y graceful/force close.
+ * Portado del patrón MCP client pool de rowboat con adaptación a
+ * Claude Code hooks (sin @modelcontextprotocol/sdk — solo JSON-RPC sobre stdio).
+ *
+ * Características:
+ *   - Lazy connection: se conecta al MCP server solo cuando se necesita
+ *   - State tracking: connected | connecting | error | closed
+ *   - Graceful close: cierra conexiones ordenadamente
+ *   - Force close: termina inmediatamente (usado desde abort-registry)
+ *   - Integración con mcp-health.js para tracking de fallos
+ *   - Zero-dependencies externas (solo child_process, fs, path nativos)
+ *
+ * Nota: este módulo NO reemplaza el cliente MCP nativo de Claude Code —
+ * Claude Code gestiona sus propias conexiones MCP internamente. Este pool
+ * es para uso programático desde scripts y hooks cuando se necesita llamar
+ * herramientas MCP directamente (ej: tool-cost-analyzer, scripts de admin).
+ *
+ * Uso:
+ *   const mcpPool = require('./mcp-pool');
+ *
+ *   // Registrar servidor
+ *   mcpPool.register('filesystem', { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] });
+ *
+ *   // Obtener conexión (lazy init)
+ *   const client = await mcpPool.getClient('filesystem');
+ *
+ *   // Listar herramientas
+ *   const tools = await mcpPool.listTools('filesystem');
+ *
+ *   // Ejecutar herramienta
+ *   const result = await mcpPool.execute('filesystem', 'read_file', { path: './CLAUDE.md' });
+ *
+ *   // Cleanup al finalizar sesión (desde Stop hook)
+ *   await mcpPool.closeAll();
+ */
+
+const { spawn }    = require('child_process');
+const fs           = require('fs');
+const path         = require('path');
+const EventEmitter = require('events');
+
+// ---------------------------------------------------------------------------
+// Estado del pool (singleton)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ command: string, args?: string[], env?: object, cwd?: string }} StdioConfig
+ * @typedef {{ url: string, headers?: object }} HttpConfig
+ * @typedef {{ state: 'idle'|'connecting'|'connected'|'error'|'closed', process?: any, error?: string, tools?: object[] }} PoolEntry
+ */
+
+/** @type {Map<string, { config: StdioConfig|HttpConfig, entry: PoolEntry }>} */
+const pool = new Map();
+
+/** @type {Map<string, EventEmitter>} Message bus por server (para JSON-RPC async) */
+const buses = new Map();
+
+/** @type {Map<string, number>} Contador de requests por server */
+const requestIds = new Map();
+
+/** @type {Map<string, object>} Credenciales por servidor — NUNCA exponer en código generado */
+const credVault = new Map();
+
+// ---------------------------------------------------------------------------
+// Registro de servidores
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra la configuración de un servidor MCP.
+ * No inicia la conexión (lazy).
+ *
+ * @param {string} name
+ * @param {StdioConfig|HttpConfig} config
+ */
+function register(name, config) {
+  pool.set(name, {
+    config,
+    entry: { state: 'idle' },
+  });
+}
+
+/**
+ * Registra todos los servidores MCP encontrados en `.claude/settings.json`.
+ * Permite auto-discovery del pool sin configuración manual.
+ */
+function autoRegisterFromSettings() {
+  try {
+    const settingsPath = path.join(process.cwd(), '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) return;
+
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    const mcpServers = settings.mcpServers || {};
+
+    for (const [name, config] of Object.entries(mcpServers)) {
+      if (!pool.has(name)) {
+        register(name, config);
+      }
+    }
+  } catch (_) { /* auto-discovery silencioso */ }
+}
+
+// ---------------------------------------------------------------------------
+// Credential Proxy (patrón Managed Agents)
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra credenciales para un servidor MCP.
+ * Las credenciales se inyectan como variables de entorno al conectar (spawn),
+ * y NUNCA aparecen en código generado ni en logs de herramientas.
+ *
+ * Patrón Managed Agents: "Credentials never reach generated code."
+ * Equivalente al proxy OAuth de MCP servers en el spec de Anthropic.
+ *
+ * @param {string} name     - Nombre del servidor MCP (debe coincidir con register()).
+ * @param {object} envVars  - Variables de entorno a inyectar: { VAR_NAME: 'valor' }
+ */
+function withCredentials(name, envVars) {
+  credVault.set(name, { ...(credVault.get(name) || {}), ...envVars });
+}
+
+/**
+ * Carga credenciales desde `.claude/mcp-credentials.json` si el archivo existe.
+ * Este archivo NUNCA debe commitearse — agregar a `.gitignore`.
+ *
+ * Formato:
+ * {
+ *   "github":     { "GITHUB_TOKEN": "ghp_..." },
+ *   "filesystem": { "API_KEY": "..." }
+ * }
+ *
+ * Se llama automáticamente al cargar el módulo y puede re-llamarse para recargar.
+ */
+function autoLoadCredentials() {
+  try {
+    const credsPath = path.join(process.cwd(), '.claude', 'mcp-credentials.json');
+    if (!fs.existsSync(credsPath)) return;
+    const creds = JSON.parse(fs.readFileSync(credsPath, 'utf8'));
+    for (const [serverName, envVars] of Object.entries(creds)) {
+      if (serverName && typeof envVars === 'object') {
+        withCredentials(serverName, envVars);
+      }
+    }
+  } catch (_) { /* carga silenciosa — credenciales opcionales */ }
+}
+
+// ---------------------------------------------------------------------------
+// Conexión lazy (stdio)
+// ---------------------------------------------------------------------------
+
+/**
+ * Conecta a un servidor MCP vía stdio si no está conectado ya.
+ * Implementa JSON-RPC 2.0 sobre stdin/stdout del proceso hijo.
+ *
+ * @param {string} name
+ * @returns {Promise<PoolEntry>}
+ */
+async function conectar(name) {
+  const item = pool.get(name);
+  if (!item) throw new Error(`MCP server no registrado: ${name}`);
+
+  // Ya conectado
+  if (item.entry.state === 'connected') return item.entry;
+
+  // Conexión en progreso — esperar
+  if (item.entry.state === 'connecting') {
+    return new Promise((resolve, reject) => {
+      const bus = buses.get(name) || new EventEmitter();
+      buses.set(name, bus);
+      bus.once('connected', () => resolve(item.entry));
+      bus.once('error', (err) => reject(err));
+    });
+  }
+
+  // Iniciar conexión
+  item.entry.state = 'connecting';
+
+  const config = item.config;
+  if (!('command' in config)) {
+    // HTTP/SSE — solo marcar como connected (Claude Code gestiona HTTP MCPs)
+    item.entry.state = 'connected';
+    return item.entry;
+  }
+
+  return new Promise((resolve, reject) => {
+    try {
+      // Inyectar credenciales del vault — nunca expuestas en código generado
+      const credEnv = credVault.get(name) || {};
+      const proc = spawn(config.command, config.args || [], {
+        cwd:   config.cwd  || process.cwd(),
+        env:   { ...process.env, ...(config.env || {}), ...credEnv },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      item.entry.process = proc;
+      let buffer = '';
+
+      proc.stdout.on('data', (chunk) => {
+        buffer += chunk.toString();
+        // Procesar líneas completas (JSON-RPC newline-delimited)
+        const lineas = buffer.split('\n');
+        buffer = lineas.pop(); // última línea incompleta
+        for (const linea of lineas) {
+          if (!linea.trim()) continue;
+          try {
+            const msg = JSON.parse(linea);
+            const bus = buses.get(name);
+            if (bus) bus.emit(`response:${msg.id}`, msg);
+          } catch (_) { /* línea no-JSON — ignorar */ }
+        }
+      });
+
+      proc.on('error', (err) => {
+        item.entry.state = 'error';
+        item.entry.error = err.message;
+        const bus = buses.get(name);
+        if (bus) bus.emit('error', err);
+        reject(err);
+      });
+
+      proc.on('exit', () => {
+        item.entry.state = 'closed';
+      });
+
+      // Enviar initialize (MCP protocol)
+      const initId = nextId(name);
+      const initMsg = JSON.stringify({
+        jsonrpc: '2.0',
+        id:      initId,
+        method:  'initialize',
+        params:  {
+          protocolVersion: '2024-11-05',
+          capabilities:    {},
+          clientInfo:      { name: 'swl-ses-mcp-pool', version: '1.0.0' },
+        },
+      });
+
+      proc.stdin.write(initMsg + '\n');
+
+      // Esperar respuesta de initialize
+      const bus = buses.get(name) || new EventEmitter();
+      buses.set(name, bus);
+      const timer = setTimeout(() => {
+        item.entry.state = 'error';
+        item.entry.error = 'initialize timeout';
+        reject(new Error(`MCP initialize timeout: ${name}`));
+      }, 10_000);
+
+      bus.once(`response:${initId}`, () => {
+        clearTimeout(timer);
+        // Enviar initialized notification
+        proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+        item.entry.state = 'connected';
+        bus.emit('connected');
+        resolve(item.entry);
+      });
+
+    } catch (err) {
+      item.entry.state = 'error';
+      item.entry.error = err.message;
+      reject(err);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Operaciones de cliente
+// ---------------------------------------------------------------------------
+
+/**
+ * Genera el siguiente ID de request JSON-RPC para un servidor.
+ */
+function nextId(name) {
+  const current = requestIds.get(name) || 0;
+  requestIds.set(name, current + 1);
+  return current + 1;
+}
+
+/**
+ * Envía una request JSON-RPC y espera la respuesta.
+ *
+ * @param {string} name
+ * @param {string} method
+ * @param {object} params
+ * @param {number} [timeout=15000]
+ * @returns {Promise<any>}
+ */
+async function rpcCall(name, method, params, timeout = 15_000) {
+  const entry = await conectar(name);
+  const item  = pool.get(name);
+
+  if (!item || !entry.process) {
+    throw new Error(`MCP server no disponible: ${name}`);
+  }
+
+  const id  = nextId(name);
+  const bus = buses.get(name) || new EventEmitter();
+  buses.set(name, bus);
+
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+  item.entry.process.stdin.write(msg + '\n');
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`MCP timeout (${method}): ${name}`));
+    }, timeout);
+
+    bus.once(`response:${id}`, (response) => {
+      clearTimeout(timer);
+      if (response.error) reject(new Error(response.error.message));
+      else resolve(response.result);
+    });
+  });
+}
+
+/**
+ * Lista las herramientas disponibles en un servidor MCP.
+ *
+ * @param {string} name
+ * @returns {Promise<Array<{ name, description, inputSchema }>>}
+ */
+async function listTools(name) {
+  const item = pool.get(name);
+  if (!item) return [];
+
+  // Cache de herramientas
+  if (item.entry.tools) return item.entry.tools;
+
+  const result = await rpcCall(name, 'tools/list', {});
+  item.entry.tools = result.tools || [];
+  return item.entry.tools;
+}
+
+/**
+ * Ejecuta una herramienta en un servidor MCP.
+ *
+ * @param {string} serverName
+ * @param {string} toolName
+ * @param {object} input
+ * @returns {Promise<any>}
+ */
+async function execute(serverName, toolName, input) {
+  return rpcCall(serverName, 'tools/call', { name: toolName, arguments: input });
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle: close
+// ---------------------------------------------------------------------------
+
+/**
+ * Cierra la conexión de un servidor MCP de forma ordenada (graceful).
+ *
+ * @param {string} name
+ */
+async function close(name) {
+  const item = pool.get(name);
+  if (!item || item.entry.state === 'closed') return;
+
+  try {
+    if (item.entry.process) {
+      item.entry.process.stdin.end();
+      item.entry.process.kill('SIGTERM');
+    }
+  } catch (_) { /* proceso ya terminado */ }
+
+  item.entry.state = 'closed';
+  buses.delete(name);
+}
+
+/**
+ * Cierra todos los servidores MCP. Llamar desde Stop hook.
+ * Usa timeout de 3 segundos por server para no bloquear el proceso.
+ */
+async function closeAll() {
+  const nombres = Array.from(pool.keys());
+  await Promise.allSettled(
+    nombres.map(name => Promise.race([
+      close(name),
+      new Promise(resolve => setTimeout(resolve, 3_000)), // timeout por server
+    ]))
+  );
+}
+
+/**
+ * Force close: termina todos los procesos MCP inmediatamente (SIGKILL).
+ * Usar cuando abort-registry detecta forceAbort.
+ */
+function forceCloseAll() {
+  for (const [name, item] of pool.entries()) {
+    try {
+      if (item.entry.process) {
+        item.entry.process.kill('SIGKILL');
+      }
+    } catch (_) { /* proceso ya terminado */ }
+    item.entry.state = 'closed';
+  }
+  buses.clear();
+}
+
+/**
+ * Estado del pool (para diagnóstico / mcp-health.js).
+ *
+ * @returns {Array<{ name: string, state: string, error?: string, toolCount: number }>}
+ */
+function poolStatus() {
+  return Array.from(pool.entries()).map(([name, item]) => ({
+    name,
+    state:     item.entry.state,
+    error:     item.entry.error,
+    toolCount: (item.entry.tools || []).length,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Inicialización al cargar el módulo
+// ---------------------------------------------------------------------------
+autoRegisterFromSettings();
+autoLoadCredentials();
+
+module.exports = {
+  register,
+  autoRegisterFromSettings,
+  withCredentials,
+  autoLoadCredentials,
+  getClient: conectar,
+  listTools,
+  execute,
+  close,
+  closeAll,
+  forceCloseAll,
+  poolStatus,
+};