# 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/evolution/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`.
