@saulwade/swl-ses 1.4.2 → 1.5.0

package/scripts/mcp-server/README.md

@@ -1,128 +1,170 @@
-# swl-mcp-server — STUB EXPERIMENTAL
-
-> ⚠ **NO USAR EN PRODUCCIÓN**. Este es un stub experimental que demuestra
-> el patrón de exponer la memoria de swl-ses a clientes MCP externos. La
-> implementación completa requiere trabajo adicional (auth, observabilidad,
-> tests de integración, schema migration). Ver sección "Limitaciones" más
-> abajo.
-
-## Qué hace
-
-`bin/swl-mcp-server.js` es un servidor MCP en modo stdio que expone 3
-endpoints de solo lectura:
-
-1. **`swl_memory_search`** — búsqueda hybrid sobre memoria SWL
-   (aprendizajes + sesiones + instintos) usando `hooks/lib/memory-search`
-   con RRF fusion.
-2. **`swl_aprendizajes_recientes`** — últimos N aprendizajes de
-   `.planning/APRENDIZAJES.md`.
-3. **`swl_instintos_activos`** — instintos con `effective_confidence ≥
-   umbral`.
-
-El server lee el estado file-based de swl-ses tal como existe en `cwd`
-(o el directorio especificado por `SWL_MCP_BASE_DIR`). NO escribe — solo
-lectura.
-
-## Cómo arrancar (para testing)
-
-```bash
-# Modo standalone (smoke test)
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node bin/swl-mcp-server.js
-
-# Output esperado en stdout:
-# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"swl-mcp-server","version":"0.1.0-experimental"}}}
-
-# Listar herramientas
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node bin/swl-mcp-server.js
-
-# Buscar memoria
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"swl_memory_search","arguments":{"query":"RRF fusion","limit":3}}}' | node bin/swl-mcp-server.js
-```
-
-## Cómo configurar en clientes MCP (NO recomendado en producción)
-
-### Cursor (~/.cursor/mcp.json)
-
-```json
-{
-  "mcpServers": {
-    "swl-memory": {
-      "command": "node",
-      "args": ["/ruta/absoluta/a/swl-ses/bin/swl-mcp-server.js"],
-      "env": {
-        "SWL_MCP_BASE_DIR": "/ruta/al/proyecto/que/quiero/recuperar"
-      }
-    }
-  }
-}
-```
-
-### Gemini CLI
-
-Similar, agregando el server a la config del cliente que soporte MCP stdio.
-
-### Claude Code (NO necesario)
-
-Claude Code ya tiene acceso directo a los archivos de swl-ses dentro de
-su propio runtime. NO usar el MCP server desde Claude Code en el mismo
-proyecto — sería redundante y agregaría latencia.
-
-## Limitaciones (lo que NO se hace en este stub)
-
-| Limitación | Impacto | Cuándo se debe arreglar |
-|---|---|---|
-| **Sin auth** | Cualquier proceso con acceso al stdio puede leer toda la memoria | Antes de exponer en redes públicas o multi-usuario |
-| **Sin rate limiting** | Cliente malicioso/buggy puede saturar lectura de archivos | Cuando se observen ≥1 incidentes de saturación |
-| **Sin HTTP transport** | Solo stdio; no se puede conectar remotamente | Cuando el caso de uso requiera servidor de red |
-| **Sin tests de integración** | Solo smoke tests manuales | Antes de v1.0 del MCP server |
-| **Sin observabilidad / métricas** | Logs JSON a stderr son lo único que hay | Cuando se use en >1 cliente simultáneo |
-| **Sin hot-reload** | Cambios en swl-ses no se reflejan hasta restart del server | Ya — el server lee files en cada call, así que SÍ se reflejan; documentado por completitud |
-| **Sin caching** | Cada call lee files de disco | Cuando latencia sea problema (~10ms hoy) |
-| **Sin schema versioning** | Si cambia formato de APRENDIZAJES.md, los handlers pueden romper | Cuando se introduzca breaking change en el formato |
-| **Sin support de resources/prompts** | Solo tools | Cuando el caso de uso lo demande |
-| **Sin paginación** | Resultados grandes se truncan a `limit` | Cuando se requiera browse de >50 entries |
-| **Single-tenant** | Asume un solo proyecto por instancia | Multi-tenancy necesita rediseño |
-
-## Trigger para implementación completa
-
-**Hoy**: 0 instalaciones reportadas. Mantener como stub.
-
-**Trigger para invertir esfuerzo en implementación robusta**: el usuario
-reporta uso real consistente de ≥2 runtimes distintos (Cursor + Claude
-Code, o Gemini + Claude Code, etc.) sobre el mismo proyecto SWL durante
-≥1 mes. Sin esto, la inversión de ~25 horas en hardening del server
-no se justifica.
-
-## Diseño futuro (cuando se implemente completo)
-
-1. **Auth**: API key estática + bearer token con scopes:
-   - `swl:memory:read` (búsqueda y lectura)
-   - `swl:memory:write` (crear aprendizajes desde MCP — requiere validación)
-   - `swl:instintos:write` (modificar confidence — alto riesgo)
-2. **HTTP transport opcional**: además de stdio, ofrecer servidor HTTP/SSE
-   con TLS y CORS configurable.
-3. **Telemetría**: requests por handler, latencia p50/p95, errores por
-   tipo. Persistir en `.planning/evolucion/mcp-metrics.jsonl`.
-4. **Caching invalidable**: caché en memoria de las lecturas de
-   APRENDIZAJES.md / instintos con `mtime`-based invalidation.
-5. **Schema versioning**: cada handler declara `schema_version`. El
-   cliente puede pedir un version range. Breaking changes bumpan major.
-6. **Tests de integración**: arrancar el server contra una fixture y
-   ejecutar 50+ scenarios. Smoke en CI.
-
-## Estado de seguridad (auditoría rápida del stub)
-
-- ✓ NO expone credenciales ni archivos fuera de `baseDir`.
-- ✓ NO ejecuta código (solo lee files y devuelve JSON).
-- ✓ NO modifica archivos.
-- ✗ NO valida que `baseDir` sea un proyecto SWL válido — un cliente
-  podría apuntarlo a un directorio arbitrario y leer cualquier
-  archivo `*.md` que llamemos `APRENDIZAJES.md`.
-- ✗ NO sanitiza queries de búsqueda (los regex en `instintos.yaml` parser
-  son seguros, pero falta hardening).
-- ✗ NO hay timeout — un proyecto enorme con miles de sesiones podría
-  hacer colgar el server.
-
-Estos puntos son ACEPTABLES para un stub experimental usado por el
-mantenedor en un proyecto propio. NO ACEPTABLES para uso multi-usuario
-o expuesto a la red.
+# swl-mcp-server v1.0.0
+
+Servidor MCP de solo lectura para exponer la memoria de swl-ses
+(aprendizajes, sesiones, instintos) a clientes MCP externos como Cursor,
+Codex CLI y Gemini CLI.
+
+Promovido de stub experimental (v0.1.x) a v1.0.0 en ADR-0019 Sub-fase 3.
+
+## Qué hace
+
+Expone 5 endpoints sobre stdio JSON-RPC:
+
+1. **`swl_memory_search`** — búsqueda hybrid sobre memoria SWL
+   (aprendizajes + sesiones + instintos) usando `hooks/lib/memory-search`
+   con RRF fusion.
+2. **`swl_aprendizajes_recientes`** — últimos N aprendizajes de
+   `.planning/APRENDIZAJES.md`.
+3. **`swl_instintos_activos`** — instintos con `effective_confidence ≥
+   umbral`.
+4. **`swl_list_skills`** (Sub-fase 9 v1.5.0) — lista skills SWL
+   disponibles con nombre + descripción del frontmatter. Útil para
+   descubrir conocimiento operacional antes de invocar uno.
+5. **`swl_invoke_skill`** (Sub-fase 9 v1.5.0) — devuelve el SKILL.md
+   completo de un skill por nombre. Para clientes MCP que no cargan
+   skills filesystem nativamente (Codex `--local`, Gemini CLI, otros) —
+   el cliente recibe el cuerpo del SKILL.md como texto y lo usa como
+   contexto en su próxima llamada.
+
+El server lee el estado file-based de swl-ses tal como existe en `cwd`
+(o el directorio especificado por `SWL_MCP_BASE_DIR`). NO escribe — solo
+lectura. NO ejecuta scripts referenciados desde un skill.
+
+### Resolución del directorio de skills
+
+Para `swl_list_skills` y `swl_invoke_skill`, el server busca skills en
+el primer directorio que exista, en este orden:
+
+1. `<baseDir>/habilidades/` — repo SWL como project root.
+2. `<baseDir>/.claude/skills/` — proyecto consumidor con SWL instalado
+   en Claude Code.
+3. `<baseDir>/.cursor/skills/` — proyecto con SWL instalado en Cursor.
+
+## Features v1.0.0
+
+| Feature | Cómo activar | Default |
+|---|---|---|
+| Auth opt-in (Bearer en `params._auth`) | `SWL_MCP_API_KEY=<token>` en el env del server | sin auth (backward-compat) |
+| Caching mtime-based con TTL | Siempre activo | 60 segundos |
+| Override TTL del cache | `SWL_MCP_CACHE_TTL_MS=<ms>` | 60000 |
+| Telemetría JSONL por call | `SWL_MCP_METRICS=1` | sin telemetría |
+| Schema versioning por handler | Siempre presente en `tools/list` | `1.0.0` |
+
+## Cómo arrancar (testing)
+
+```bash
+# Smoke standalone
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node bin/swl-mcp-server.js
+
+# Output esperado (sin auth):
+# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{"name":"swl-mcp-server","version":"1.0.0","authRequired":false,"telemetryEnabled":false}}}
+
+# Con auth opt-in
+SWL_MCP_API_KEY="secret-123" node bin/swl-mcp-server.js
+
+# Cliente debe enviar params._auth:
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"_auth":"secret-123","name":"swl_aprendizajes_recientes","arguments":{"limit":5}}}' | SWL_MCP_API_KEY=secret-123 node bin/swl-mcp-server.js
+```
+
+## Configuración en clientes MCP
+
+### Cursor (autoconfig disponible)
+
+Desde v1.5.0 el instalador puede registrar el server automáticamente:
+
+```bash
+npx @saulwade/swl-ses@latest install --target cursor --with-mcp
+```
+
+Esto genera `.cursor/mcp.json` (per-proyecto) o `~/.cursor/mcp.json`
+(con `--global`) preservando otros mcpServers configurados.
+
+Configuración manual:
+
+```json
+{
+  "mcpServers": {
+    "swl-memory": {
+      "command": "node",
+      "args": ["/path/to/swl-ses/bin/swl-mcp-server.js"],
+      "env": {
+        "SWL_MCP_BASE_DIR": "/path/to/proyecto",
+        "SWL_MCP_API_KEY": "opcional-token-secreto"
+      }
+    }
+  }
+}
+```
+
+### Codex CLI (autoconfig disponible)
+
+```bash
+npx @saulwade/swl-ses@latest install --target codex --global --with-mcp
+```
+
+Esto inserta `[mcp_servers.swl-memory]` en `~/.codex/config.toml`
+preservando otros servers configurados. Verificar con `codex mcp list`.
+
+### Gemini CLI
+
+Manualmente similar a Cursor — el server expone stdio JSON-RPC estándar.
+
+### Claude Code (NO necesario)
+
+Claude Code ya tiene acceso directo a los archivos de swl-ses dentro de
+su propio runtime. NO usar el MCP server desde Claude Code en el mismo
+proyecto — sería redundante.
+
+## Cambios v0.1.x → v1.0.0
+
+| Aspecto | v0.1.x (stub) | v1.0.0 |
+|---|---|---|
+| Auth | sin auth | opt-in con `SWL_MCP_API_KEY` + Bearer en `params._auth` |
+| Caching | sin caching | mtime-based con TTL configurable |
+| Telemetría | logs stderr | JSONL en `.planning/evolucion/mcp-metrics.jsonl` (opt-in) |
+| Schema versioning | implícito | `_schemaVersion` en cada tool de `tools/list` |
+| Tests | smoke manual | 38 tests unitarios (`tests/mcp-server/*.test.js`) |
+| Estado | "NO usar en producción" | apto para los proyectos del usuario |
+
+## Backward compatibility
+
+v1.0.0 es 100% backward-compatible con clientes que conectan sin auth.
+Si `SWL_MCP_API_KEY` no está set en el env del server, el comportamiento
+es idéntico al stub v0.1.x — no se requiere ningún cambio en clientes
+configurados antes.
+
+## Diseño futuro (cuando aparezca demanda real)
+
+- **HTTP transport opcional**: además de stdio, ofrecer servidor HTTP/SSE
+  con TLS y CORS configurable.
+- **Handlers de escritura** (`swl:memory:write`, `swl:instintos:write`)
+  fuera de scope v1.0 — requerirían scopes en el token y validación
+  semántica de cada mutación.
+- **Rate limiting** por API key cuando aparezca un caso multi-cliente.
+- **OpenTelemetry** para latencias p95 distribuidas si el server se
+  consume desde múltiples editores en paralelo.
+
+## Estado de seguridad
+
+- ✓ Read-only — no ejecuta código ni modifica archivos.
+- ✓ Auth opt-in con comparación constante para defender contra timing
+  attacks.
+- ✓ Caching con invalidación correcta (mtime + TTL).
+- ✓ Telemetría con error silencioso — nunca rompe el server.
+- ✗ `baseDir` no se valida contra patrón "proyecto SWL válido". Un
+  cliente con acceso al stdio puede apuntarlo a cualquier directorio
+  con `APRENDIZAJES.md`. Mitigación: el operador configura el server
+  con `SWL_MCP_BASE_DIR` explícito.
+- ✗ Sin límite de tamaño de query — un cliente malicioso podría enviar
+  una query gigante. Mitigación parcial: `limit` está clampeado a 50/100.
+
+Para casos de uso single-user en máquinas confiables del operador, los
+puntos restantes son aceptables. Para uso multi-usuario o exposición a
+red, evaluar primero el alcance del riesgo y considerar las features
+de "diseño futuro" arriba.
+
+## Referencias
+
+- ADR-0019 Sub-fase 3: `.planning/adrs/0019-integracion-codex-y-cursor-completa.md`.
+- Tests: `tests/mcp-server/*.test.js` (auth, cache, telemetry, rutear).
+- Configuración Cursor: `docs/MCP-SERVER-CURSOR-NOTAS.md`.

package/scripts/mcp-server/auth.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * Auth opt-in para swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * El stub experimental v0.1.x corría sin auth. Cualquier proceso con acceso al
+ * stdio podía leer toda la memoria SWL. Esa decisión era aceptable solo en
+ * single-user local — no en multi-usuario, no expuesto a red, no compartido.
+ *
+ * v1.0.0 introduce auth **opt-in**:
+ *   - Si `SWL_MCP_API_KEY` NO está definida en el entorno del server, el comportamiento
+ *     es idéntico al stub (sin auth). Compatibilidad total con clientes existentes.
+ *   - Si `SWL_MCP_API_KEY` ESTÁ definida, cada `tools/call` debe incluir
+ *     `params._auth = "<api-key>"`. Sin el token o con token incorrecto, se devuelve
+ *     `-32001 Unauthorized`.
+ *
+ * Decisión deliberada de NO usar header `Authorization: Bearer ...`:
+ *   - El protocolo MCP sobre stdio NO transporta headers HTTP.
+ *   - Inventar un campo en `initialize.capabilities` específico para swl-ses
+ *     rompería la spec del protocolo.
+ *   - `_auth` como campo en `params` es el patrón de menor fricción.
+ *
+ * Limitaciones aceptadas:
+ *   - Token estático sin rotación automática — el operador rota manualmente
+ *     cambiando la env var del proceso.
+ *   - Sin scopes (read/write) porque v1 sigue siendo read-only.
+ *
+ * @module scripts/mcp-server/auth
+ */
+
+const ENV_VAR_NAME = 'SWL_MCP_API_KEY';
+const ERROR_CODE_UNAUTHORIZED = -32001;
+const ERROR_CODE_FORBIDDEN = -32002;
+
+/**
+ * Construye un validador de auth desde el entorno actual.
+ *
+ * Pattern de "construct once, use many": leer la env var una sola vez al arranque
+ * y devolver una función pura que valida cada request. Evita race conditions con
+ * tests que mutan process.env.
+ *
+ * @param {object} [opciones] - { env: NodeJS.ProcessEnv } sustituible para tests.
+ * @returns {{ requerida: boolean, validar: (request: object) => { ok: boolean, code?: number, message?: string } }}
+ */
+function construirValidador(opciones = {}) {
+  const env = opciones.env || process.env;
+  const apiKey = env[ENV_VAR_NAME];
+  const requerida = typeof apiKey === 'string' && apiKey.length > 0;
+
+  return {
+    requerida,
+    validar: (request) => {
+      if (!requerida) return { ok: true };
+      // Solo validar tools/call — initialize, ping, tools/list son metadata pública.
+      const metodo = request && request.method;
+      if (metodo !== 'tools/call') return { ok: true };
+
+      const params = request.params || {};
+      const tokenCliente = params._auth;
+
+      if (typeof tokenCliente !== 'string' || tokenCliente.length === 0) {
+        return {
+          ok: false,
+          code: ERROR_CODE_UNAUTHORIZED,
+          message: 'swl-mcp-server requiere autenticación: SWL_MCP_API_KEY está configurada en el server. El cliente debe enviar params._auth con el API key.',
+        };
+      }
+      if (!comparacionConstante(tokenCliente, apiKey)) {
+        return {
+          ok: false,
+          code: ERROR_CODE_FORBIDDEN,
+          message: 'Token inválido.',
+        };
+      }
+      return { ok: true };
+    },
+  };
+}
+
+/**
+ * Comparación de strings en tiempo constante para evitar timing attacks
+ * sobre el API key. Implementación zero-deps simple.
+ *
+ * Si las longitudes difieren, igual se itera la longitud máxima para no filtrar
+ * información sobre el largo del secreto vía duración de la comparación.
+ */
+function comparacionConstante(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    const ca = i < a.length ? a.charCodeAt(i) : 0;
+    const cb = i < b.length ? b.charCodeAt(i) : 0;
+    diff |= ca ^ cb;
+  }
+  return diff === 0;
+}
+
+module.exports = {
+  construirValidador,
+  comparacionConstante,
+  ENV_VAR_NAME,
+  ERROR_CODE_UNAUTHORIZED,
+  ERROR_CODE_FORBIDDEN,
+};

package/scripts/mcp-server/cache.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Cache mtime-based para handlers del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * El stub experimental leía disco en cada call (latencia medida ~10ms con
+ * APRENDIZAJES.md de 1172 líneas). Para datasets más grandes (>10k líneas) o
+ * múltiples clientes concurrentes, el caching reduce sustancialmente la carga.
+ *
+ * Patrón:
+ *   - Key = path absoluto del archivo.
+ *   - Value = { mtime, contenido, parsed }.
+ *   - Invalidación: si fs.stat().mtime > value.mtime → recargar y reparsear.
+ *   - TTL opcional vía `SWL_MCP_CACHE_TTL_MS` (default 60000 ms): aunque mtime no
+ *     haya cambiado, recargar tras TTL para defensa contra clock skew o ediciones
+ *     que no actualizan mtime (raras pero posibles en filesystems exóticos).
+ *
+ * Zero-deps. NO usar para escritura — sigue read-only.
+ *
+ * @module scripts/mcp-server/cache
+ */
+
+const fs = require('fs');
+
+const DEFAULT_TTL_MS = 60 * 1000;
+
+/**
+ * Crea una instancia de cache mtime-based.
+ *
+ * @param {object} [opciones]
+ * @param {number} [opciones.ttlMs] - TTL en milisegundos. Default 60000.
+ * @param {object} [opciones.env] - Para leer SWL_MCP_CACHE_TTL_MS en tests.
+ * @returns {{ get: Function, invalidate: Function, stats: Function, _store: Map }}
+ */
+function crearCache(opciones = {}) {
+  const env = opciones.env || process.env;
+  const ttlMs = opciones.ttlMs !== undefined
+    ? opciones.ttlMs
+    : (parseInt(env.SWL_MCP_CACHE_TTL_MS, 10) || DEFAULT_TTL_MS);
+
+  const store = new Map();
+  const stats = { hits: 0, misses: 0, invalidations: 0 };
+
+  /**
+   * Obtiene el valor cacheado para `path`. Si el archivo cambió (mtime) o el TTL
+   * expiró, vuelve a leer y parsear con `parser(contenido, path)`.
+   *
+   * @param {string} ruta - Path absoluto del archivo a cachear.
+   * @param {(contenido: string, ruta: string) => any} parser - Función que transforma
+   *   el contenido del archivo en el objeto a cachear. DEBE ser pura.
+   * @returns {{ data: any, hit: boolean } | null} null si el archivo no existe.
+   */
+  function get(ruta, parser) {
+    let stat;
+    try {
+      stat = fs.statSync(ruta);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+
+    const mtimeMs = stat.mtimeMs;
+    const ahora = Date.now();
+    const cached = store.get(ruta);
+
+    if (cached && cached.mtimeMs === mtimeMs && (ahora - cached.cargadoEn) < ttlMs) {
+      stats.hits++;
+      return { data: cached.data, hit: true };
+    }
+
+    if (cached) stats.invalidations++;
+    else stats.misses++;
+
+    const contenido = fs.readFileSync(ruta, 'utf-8');
+    const data = parser(contenido, ruta);
+    store.set(ruta, { mtimeMs, cargadoEn: ahora, data });
+    return { data, hit: false };
+  }
+
+  /**
+   * Invalida una entrada o todo el cache.
+   * @param {string} [ruta] - Si se omite, vacía todo.
+   */
+  function invalidate(ruta) {
+    if (ruta === undefined) {
+      const n = store.size;
+      store.clear();
+      stats.invalidations += n;
+      return n;
+    }
+    if (store.delete(ruta)) stats.invalidations++;
+    return 0;
+  }
+
+  return {
+    get,
+    invalidate,
+    stats: () => ({ ...stats, size: store.size, ttlMs }),
+    _store: store, // exposed para tests
+  };
+}
+
+module.exports = {
+  crearCache,
+  DEFAULT_TTL_MS,
+};