Iris

Iris — deja de lanzar agentes a ciegas

Iris puntúa cada ejecución de agente en calidad, seguridad y costo — en tu máquina, sin SDK y sin cuenta. La mayoría de los proyectos de agentes verifican calidad ejecutando algunos prompts recordados y evaluando la salida a ojo. Iris reemplaza eso con números que puedes auditar: las ejecuciones de tus agentes caen en una base de datos SQLite en tu disco, 13 reglas integradas las puntúan de forma determinista — PII, inyección de prompts, marcadores de alucinación, umbrales de costo — gratis, sin llamadas a LLM, y un juez LLM opcional con un tope de costo duro por evaluación maneja las preguntas semánticas. Cada regla es inspeccionable y editable, porque un juez que no puedes auditar es solo una corazonada con un número encima. Licencia MIT, sin telemetría; tus trazas nunca salen de tu máquina.

Requiere Node.js 20 o posterior. Verifícalo con node --version.

Un fallo en pantalla en 60 segundos

Sin cableado de agentes, sin configuración — un solo comando:

npx @iris-eval/mcp-server --demo

Esto siembra una base de datos demo — un puñado de agentes pequeños con una semana de ejecuciones — y sirve el panel contra ella en http://localhost:6920 (tu navegador se abre automáticamente en la primera ejecución). El panel aterriza en Fallos: qué falló, primero los peores y los más recientes. Vale la pena hacer clic — una fuga de PII detectada por las reglas de seguridad, un intento de inyección de prompt marcado, y un puntaje fallido del juez LLM con su justificación.

Los datos demo viven en su propia base de datos (demo.db en tu directorio de inicio de Iris — ~/.iris en macOS/Linux, %USERPROFILE%\.iris en Windows) y nunca se mezclan con tus trazas reales. Elimina todo con un solo comando:

npx @iris-eval/mcp-server --demo-clear

Conecta tu propio agente

Añade Iris a tu configuración MCP. Funciona con Claude Desktop, Claude Code, Cursor, Windsurf, Continue, VS Code, Cline, Zed, Codex CLI, Gemini CLI — y cualquier otro agente compatible con MCP. Un bloque, panel incluido:

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": ["@iris-eval/mcp-server", "--dashboard"]
    }
  }
}

Tu agente descubre las nueve herramientas de Iris al conectarse, y el panel sirve en http://localhost:6920. Ahora pega esto a tu agente:

Registra esa última tarea en Iris y evalúa la salida.

La traza aterriza en el panel con sus puntajes. ¿Prefieres el servidor MCP sin cabeza? Quita --dashboard de los argumentos — puedes abrir el mismo panel en cualquier momento con npx @iris-eval/mcp-server --dashboard.

Una cosa que vale la pena saber de antemano: las herramientas MCP se llaman cuando el modelo decide llamarlas. Iris no intercepta tu agente, así que las trazas se registran cuando tu agente pide que se registren — ya sea porque se lo dijiste, o porque tu código llama a las herramientas directamente. Pide a tu agente que "registre esto en Iris y lo evalúe" y lo hará. Si quieres una captura que no dependa de la elección del modelo, POST /api/v1/traces hace exactamente eso — tu código envía la traza por HTTP simple, sin modelo en el circuito (ver docs/http-ingest.md). La CLI y los SDK en el roadmap serán clientes ligeros sobre el mismo endpoint.

Captura por HTTP (sin modelo en el circuito)

Con el panel en ejecución, cualquier cosa que pueda enviar una solicitud HTTP puede registrar una traza — y opcionalmente ejecutar las evaluaciones deterministas en la misma solicitud:

curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "input": "What is the refund policy?",
    "output": "Refunds are available within 30 days of purchase.",
    "evaluate": true,
    "eval_type": "safety"
  }'

Devuelve 201 con el trace_id almacenado y el resultado de la evaluación. El endpoint acepta el mismo cuerpo que la herramienta log_trace y se encuentra detrás de la misma pila de middleware solo-loopback que el resto del panel. Contrato completo, referencia de campos y semántica de errores: docs/http-ingest.md.

Verifica la instalación

npx @iris-eval/mcp-server --self-test

Un diagnóstico de instalación sin conexión: round-trip de almacenamiento, evaluaciones deterministas, panel + protección contra DNS-rebinding — todo dentro de un home temporal aislado, así tu base de datos real nunca se abre. Código de salida 0 = saludable, 1 = una verificación falló.

claude mcp add --transport stdio iris-eval -- npx @iris-eval/mcp-server

{
  "servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["@iris-eval/mcp-server"]
    }
  }
}

{
  "context_servers": {
    "iris-eval": {
      "command": {
        "path": "npx",
        "args": ["@iris-eval/mcp-server"]
      }
    }
  }
}

[mcp_servers.iris-eval]
command = "npx"
args = ["@iris-eval/mcp-server"]

Otros Métodos de Instalación

# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-mcp --dashboard

# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint)
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data ghcr.io/iris-eval/mcp-server

Consejo: La instalación global (npm install -g) almacena trazas de forma persistente en ~/.iris/iris.db. Con npx, las trazas persisten en la misma ubicación, pero el arranque es más lento debido a la resolución de paquetes.

Lo que Obtienes

Hacia dónde va esto a continuación: el roadmap.

Herramientas MCP

Iris registra nueve herramientas que cualquier agente compatible con MCP puede invocar — ciclo de vida completo de reglas + trazas + LLM-como-juez + verificación semántica de citas:

• log_trace — Registra una ejecución de agente con spans, llamadas a herramientas, uso de tokens y costo
• evaluate_output — Puntúa la calidad de la salida contra reglas de completitud, relevancia, seguridad y costo (heurístico, determinista, gratis)
• get_traces — Consulta trazas almacenadas con filtrado, paginación y soporte de rangos de tiempo
• list_rules — Enumera las reglas de evaluación personalizadas desplegadas (solo lectura)
• deploy_rule — Registra una nueva regla de evaluación personalizada para que se active en cada evaluate_output de esa categoría
• delete_rule — Elimina una regla personalizada desplegada (destructivo, idempotente)
• delete_trace — Elimina una sola traza almacenada por ID (destructivo, limitado por tenant)
• evaluate_with_llm_judge — Evaluación semántica vía LLM (Anthropic u OpenAI). Cinco plantillas: precisión, utilidad, seguridad, corrección, fidelidad. Con tope de costo, precio por evaluación revelado. Trae tu propia clave API (IRIS_ANTHROPIC_API_KEY o IRIS_OPENAI_API_KEY) — Iris no hace proxy ni retransmite llamadas a LLM.
• verify_citations — Extrae citas de la salida (numeradas, autor-año, URLs, DOIs), recupera fuentes detrás de un resolutor protegido contra SSRF + lista de dominios permitidos, y usa un juez LLM para verificar si cada fuente realmente respalda la afirmación citada. HTTP saliente opt-in. Mismo requisito BYOK que evaluate_with_llm_judge.

Cuando IRIS_OTEL_ENDPOINT está configurado, las llamadas a log_trace también emiten una exportación OTLP/HTTP JSON de mejor esfuerzo a cualquier colector OpenTelemetry (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, etc). Ver docs/otel-integration.md.

Cómo se decide passed

evaluate_output devuelve tanto un score como una bandera passed — responden preguntas diferentes:

• score (0..1) es el promedio ponderado de las reglas que se ejecutaron — un gradiente de calidad.
• passed es el veredicto de publicar/no publicar: true solo cuando el puntaje supera el umbral de aprobación (por defecto 0.7) y ninguna regla crítica falló.

Las violaciones de seguridad genuinas fallan de forma dura. no_pii, no_injection_patterns y no_blocklist_words son reglas críticas: si una falla, la evaluación reporta passed: false sin importar cuán bien puntuaron las demás reglas, y la respuesta nombra a los culpables en critical_failures. Un SSN filtrado no puede promediarse. Las reglas personalizadas desplegadas con severity: "high" o "critical" fallan de forma dura de la misma manera; las severidades low/medium solo afectan el puntaje. Un límite que debes conocer: una regla crítica que se omitió (contexto faltante, o cualquier otra causa de omisión) no ha juzgado la salida y no veta — rule_results muestra cada omisión y su razón, para que una puerta que deba fallar en modo cerrado ante no-veredictos pueda hacerlo.

Una advertencia para puertas de CI: si omites eval_type, se ejecuta el paquete por defecto completeness — las reglas de seguridad no. La respuesta hace eco de eval_type (más un note cuando se usó el valor por defecto) para que tu puerta pueda verificar qué paquete se ejecutó realmente. Usa passed para el veredicto y eval_type: "safety" para la cobertura.

Esquemas completos de herramientas y configuración: iris-eval.com

Funciones alojadas

Iris se ejecuta completamente en tu máquina hoy, y todo lo que hace es gratis, con licencia MIT, sin límites y sin cuenta.

El almacenamiento alojado, el historial compartido de equipo y las alertas están bajo consideración, no en construcción. No hay precios ni nada que comprar. Si el historial compartido te fuera útil, la lista de espera es cómo descubrimos si vale la pena construirlo — no te compromete a nada.

Dos compromisos se mantienen en cualquier caso: nada que sea gratis hoy se moverá detrás de un muro de pago, y no se reclamará ninguna certificación de cumplimiento antes de obtenerla.

Ejemplos

• Configuración de Claude Desktop — configuración MCP para modos stdio y HTTP
• TypeScript — cliente SDK MCP — conecta e invoca herramientas
• Transporte HTTP (TS + Python) — código de cliente completo para integración estilo REST
• Instrumentación LangChain (Python, conceptual) — andamiaje que muestra la forma; necesita que tu código de agente sea ejecutable
• Instrumentación CrewAI (Python, conceptual) — andamiaje; misma advertencia

Comunidad

• GitHub Issues — Informes de errores y solicitudes de funciones
• GitHub Discussions — Preguntas e ideas
• Contributing Guide — Cómo contribuir
• HTTP Ingest — Captura determinista de trazas mediante POST /api/v1/traces
• Roadmap — Lo que viene a continuación

# Production deployment
iris-mcp --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

npx @iris-eval/mcp-server --self-test

npx --yes @iris-eval/mcp-server@latest

npm install -g @iris-eval/mcp-server@latest

npx @iris-eval/mcp-server --dashboard
# First log line: "Starting Iris MCP server vX.Y.Z"

# If using npx (clears cache and fetches latest)
npx --yes @iris-eval/mcp-server@latest

# If installed globally
npm update -g @iris-eval/mcp-server

node --version  # Must be v20.x or v22.x+

# Correct
claude mcp add --transport stdio iris-eval -- npx @iris-eval/mcp-server

# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx @iris-eval/mcp-server"

Si Iris te resulta útil, considera darle una estrella al repositorio: ayuda a que otros lo encuentren.

Con licencia MIT.