@vitronai/alethia

E2E nativo para agentes con seguridad verificable. Tu agente maneja un navegador real con inglés sencillo, y las acciones destructivas están bloqueadas por una puerta de seguridad que puedes demostrar que funciona — con un registro de auditoría firmado y sin nube.

Instalación

Claude Code — ruta más rápida (plugin):

/plugin marketplace add vitron-ai/alethia-mcp
/plugin install alethia@vitronai

Esto conecta tanto el servidor MCP como la skill en un solo paso — sin npm install manual ni edición de la configuración MCP. Reinicia o ejecuta /reload-plugins para activarlo.

Claude Code — solo skill (sin gestor de plugins):

mkdir -p ~/.claude/skills/alethia && \
  curl -fsSL https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/skills/alethia/SKILL.md \
    -o ~/.claude/skills/alethia/SKILL.md

Reinicia Claude Code. La próxima vez que le pidas probar una página, notará que Alethia aún no está configurado y te guiará para instalar el puente tú mismo.

Todos los demás (Claude Desktop, Cursor, Cline, Continue):

npm install -g @vitronai/alethia

Luego añade esto a la configuración MCP de tu cliente:

{
  "mcpServers": {
    "alethia": {
      "command": "alethia-mcp"
    }
  }
}

Reinicia tu cliente después de guardar. El runtime se descarga automáticamente (firmado, ~100 MB) la primera vez que tu agente llama a una herramienta de Alethia. Se abre una ventana de cockpit por defecto para que puedas observar — define ALETHIA_HEADLESS=1 para ocultarla; CI la oculta automáticamente.

Actualiza el puente: npm install -g @vitronai/alethia@latest. Desde 0.6.0 no necesitas un puente nuevo para versiones nuevas del runtime — consulta GitHub Releases en cada inicio.

Ejecuta siempre la última versión sin actualizar manualmente:

{
  "mcpServers": {
    "alethia": {
      "command": "npx",
      "args": ["-y", "@vitronai/alethia@latest"]
    }
  }
}

El sufijo @latest importa — sin él, npx -y puede servir una versión obsoleta en caché. Compensación: añade 10–30s en caché fría, y cada ejecución descarga lo que npm esté sirviendo actualmente (una instalación global es el valor predeterminado más seguro para trabajo sensible a cumplimiento, ya que solo cambia cuando la actualizas explícitamente).

Fija una versión específica del runtime (CI reproducible, bisección):

"env": { "ALETHIA_RUNTIME_VERSION": "0.4.0" }

Instala la skill de Claude Code (opcional, enseña a Claude cuándo usar cada herramienta):

alethia-mcp --install-skill

Related MCP server: titmas-agent-action-gate

Qué pedir

No llamas a estas herramientas directamente — solo pídele a tu agente en inglés sencillo, y él elige la correcta.

Escribir en campos de contraseña, token o tarjeta de crédito está bloqueado a menos que enmarques la solicitud como una prueba real de inicio de sesión o pago — el agente lo habilita por ti, no necesitas nombrar una bandera.

Más ejemplos listos para pegar: el libro de cocina para agentes tiene tutoriales completos — pruebas iniciales en una página desconocida, una pasada de cumplimiento completa, verificaciones paralelas en múltiples páginas, una demostración en vivo con un socio. Cada uno es un prompt literal que pegas.

Añade Alethia a tu proyecto

No se necesita instalación por proyecto — una vez que el servidor MCP está configurado, cualquier agente en cualquier proyecto puede usarlo.

1. Coloca un archivo .alethia en cualquier lugar de tu repositorio que trate como código de prueba — tests/e2e/, donde encaje.

   # tests/e2e/login.alethia
   name login flow
   navigate to http://127.0.0.1:5173
   assert "Sign in" is visible
   click Sign in
   type dev@company.com into the email field
   assert dashboard is visible

2. Pídele a tu agente que lo ejecute: "Ejecuta tests/e2e/login.alethia contra http://127.0.0.1:5173."

3. En CI, ejecútalo sin agente ni host MCP en absoluto:

   alethia run tests/e2e/login.alethia

   Sale con 0 en éxito, 1 en fallo. Flujo de trabajo listo para usar: examples/github-actions.yml.

Una referencia funcional (aplicación demo + especificaciones + CI + benchmark) vive en vitron-ai/alethia-anvil.

¿Por qué no Cypress o Playwright?

Y no es solo una herramienta de pruebas — pídele a un agente que verifique getComputedStyle() o offsetWidth en una página que está construyendo activamente, y obtienes una respuesta en vivo y sin caché directamente del DOM en lugar de un ciclo de recargar e inspeccionar.

Profundiza: Arquitectura · Puerta de seguridad · FAQ · Patrones de UI para pruebas dirigidas por agentes

Banderas de CLI

alethia-mcp                  Run as a stdio MCP server (default)
alethia-mcp run <path>       Run an NLP test file from the shell (CI mode)
alethia-mcp run --nlp "..."  Run inline NLP from the shell
alethia-mcp run -            Read NLP from stdin
alethia-mcp --version        Print the version and exit
alethia-mcp --health-check   Probe the Alethia runtime and exit 0/1
alethia-mcp --debug          Run with debug logging on stderr

También se instala un alias más corto alethia (el mismo binario), por lo que el subcomando run se puede invocar como alethia run <ruta>.

Variables de entorno

Cómo se mantiene actualizado el puente

• El runtime se auto-instala en el primer uso desde releases firmados de GitHub (verificado con Ed25519). El puente pregunta a GitHub cuál es la versión actual en el primer inicio (caché de 1h) — no hay fijación de versión en el código fuente del puente, por lo que un puente instalado globalmente sigue obteniendo runtimes actuales a medida que se publican.

• El puente también se auto-actualiza (desde 0.8.0): verifica npm al inicio, verifica el SHA-512 del tarball, instala en ~/.alethia/bridge/<versión>/. Nunca cruza una versión mayor sin acción explícita; una versión nueva solo se vuelve confiable después de completar un handshake MCP real, y las versiones que fallan antes de eso se ponen en cuarentena después de 3 intentos.

• La skill incluida de Claude Code se auto-refresca de la misma manera — cada ejecución la compara con ~/.claude/skills/alethia/SKILL.md y la sobrescribe si está desactualizada.

Solución de problemas

"Alethia desktop runtime is not running" — ejecuta alethia-mcp --health-check (activa la auto-instalación si falta). Si eso falla, verifica la conectividad de red con GitHub.

"WRITE_HIGH" / "EA1 POLICY BLOCK" en el registro de auditoría — se bloqueó una acción destructiva. Este es el comportamiento correcto de fallo cerrado (fail-closed), no un error que corregir. Ampliarlo requiere configuración humana; un agente no puede hacerlo desde dentro de una llamada.

"SENSITIVE_INPUT_DENIED" — se detectó un campo de contraseña/token/tarjeta de crédito. Solo anule con allowSensitiveInput: true para pruebas legítimas de autenticación/pago.

El cliente MCP no ve las herramientas — ejecute alethia-mcp --health-check, verifique la forma de su configuración, reinicie el cliente y establezca ALETHIA_DEBUG=1 para registrar el tráfico del puente.

"Server transport closed unexpectedly" / el puente sale silenciosamente — generalmente es un puente en caché obsoleto. Si usa npx -y @vitronai/alethia sin @latest, agréguelo o ejecute rm -rf ~/.npm/_npx. Si usa una instalación global, ejecute npm install -g @vitronai/alethia@latest. Luego salga por completo y reinicie su cliente (Cmd-Q en macOS, no solo cierre la ventana).

"Veo un nuevo lanzamiento en GitHub pero mi runtime no se ha actualizado" — la verificación de "qué hay de nuevo" se almacena en caché durante 1 hora. Rómpala con rm ~/.alethia/.latest-release ~/.alethia/.bridge-registry-cache y luego reinicie su cliente.

Postura de seguridad

El runtime es solo local por arquitectura: su binario firmado se niega a navegar a cualquier lugar fuera de file://, localhost, 127.0.0.1, .local y los rangos privados RFC1918. Esta es una constante en tiempo de compilación: ninguna bandera, variable de entorno o interruptor de interfaz la cambia. Modelo de amenazas completo y proceso de divulgación: SECURITY.md. Informes de abuso: team@vitron.ai.

Privacidad

Solo local por arquitectura: nada se recopila, transmite o almacena fuera de su máquina. El contenido de la página, las capturas de pantalla y las instrucciones de prueba se procesan localmente y nunca se envían a ningún lugar. Los paquetes de evidencia se escriben en su sistema de archivos solo bajo solicitud explícita. Cero telemetría, cero análisis, cero informes de fallos. Preguntas: team@vitron.ai.

Licencia y aviso de patente

Este puente tiene licencia MIT — consulte LICENSE. El runtime de Alethia en sí está pendiente de patente (Solicitud de EE. UU. N.º 19/571,437); la licencia MIT de este puente no otorga una licencia de patente al runtime. El uso comercial del runtime puede requerir una licencia separada. Consultas de licencias: team@vitron.ai.