Iris
offiziellMCP-nativer Agenten-Evaluierungs- und Observability-Server mit Trace-Logging, Ausgabequalitätsbewertung, Kostenverfolgung, 12 integrierten Evaluierungsregeln, Echtzeit-Dashboard und PII-Erkennung
Was kann man mit Iris MCP machen?
- Einen Lauf protokollieren und bewerten — Bitte deinen Assistenten, einen Agentenlauf in Iris zu protokollieren und seine Ausgabe zu bewerten. Sieh dir anschließend das Urteil und die Bewertungen im Dashboard an.
- Sicherheits- und Kostenregeln prüfen — Führe die 28 integrierten deterministischen Regeln für personenbezogene Daten, Prompt-Injection, Halluzinationsmarker und Kostenschwellenwerte ohne LLM-Aufrufe aus.
- Regeln prüfen und bearbeiten — Liste die integrierten Regeln auf und überprüfe oder ändere sie, denn jede Regel lässt sich einsehen und bearbeiten.
- Eine benutzerdefinierte Regel hinzufügen — Lade selbst geschriebene Regeln als Code über
eval.pluginsinconfig.json, fixiert durch den Datei-Hash. - Läufe vergleichen — Öffne in der Dashboard-Ansicht „Runs“ zwei Läufe zu denselben Fragen nebeneinander und mit einem Intervall.
- CI anhand von Urteilen blockieren — Führe
ingestmit--evaluate --fail-on anyaus, damit ein Job bei jedem Urteil fehlschlägt, das nicht „Bestanden“ lautet.
Dokumentation
Iris — Agenten nicht nach Bauchgefühl ausliefern
Sende Iris einen Agentenlauf und bitte um ein Urteil zu Qualität, Sicherheit und Kosten — auf deinem Rechner, ohne SDK und ohne Konto. Die meisten Agentenprojekte prüfen die Qualität, indem sie ein paar bekannte Prompts ausführen und die Ausgabe überfliegen. Iris ersetzt das durch überprüfbare Zahlen: Die Läufe deines Agenten landen in einer SQLite-Datenbank auf deiner Festplatte, 28 integrierte Regeln bewerten sie deterministisch — PII, Prompt-Injection, Halluzinationsmarker, Kostenschwellen und die eigenen Tool-Aufrufe des Agenten — kostenlos und ohne LLM-Aufrufe. Ein optionaler LLM-Judge mit einer festen Obergrenze für die Kosten pro Auswertung kümmert sich um semantische Fragen. Jede Regel lässt sich prüfen und bearbeiten, denn ein Judge, den du nicht überprüfen kannst, ist nur Bauchgefühl mit einer Zahl darauf. MIT-lizenziert, keine Telemetrie. Nichts verlässt deinen Rechner, außer du aktivierst eine dieser Optionen: einen OpenTelemetry-Endpunkt (IRIS_OTEL_ENDPOINT), der Traces an den von dir angegebenen Collector exportiert; den LLM-Judge mit deinem eigenen Schlüssel, der den zu bewertenden Text an diesen Anbieter sendet und dessen Quellenprüfung die in einer Ausgabe zitierten Seiten abruft; oder einen Webhook, der IDs, das Urteil und die Regelnamen — niemals den Text — an die von dir festgelegte Adresse sendet.
Erfordert Node.js 22.13 oder höher. Prüfe mit node --version.

Die Demo-Datenbank, aufgezeichnet von scripts/demo-media.mts; der Quellcode ist demo.mp4. Ein Standbild: dashboard-overview.png.
Ein Fehler in 60 Sekunden auf dem Bildschirm
Keine Agentenverdrahtung, keine Konfiguration — ein Befehl:
npx @iris-eval/mcp-server --demo
Damit wird eine Demo-Datenbank angelegt — fünf kleine Agenten, zwei Wochen an Läufen, jedes Urteil vom eigenen Bewertungsmodul — und das Dashboard damit unter http://localhost:6920 gestartet (beim ersten Start öffnet sich automatisch dein Browser). Das Dashboard öffnet sich bei Fehler: Was fehlgeschlagen ist, zuerst die schlimmsten und neuesten Fälle, jede Karte mit dem Namen der Regel und ihren Belegen. Es lohnt sich, hineinzuklicken — ein von den Sicherheitsregeln erkannter PII-Datenabfluss, eine versteckte Anweisung in einem Forenbeitrag, der der Zusammenfasser gefolgt ist, eine Zahl, die im Quelldokument nie vorkam, zwei Läufe mit denselben zwölf Fragen im Vergleich mit einem Intervall (Läufe), eine bereitgestellte benutzerdefinierte Regel und eine pausierte Regel samt Prüfprotokollen sowie eine fehlgeschlagene Bewertung durch den LLM-Judge mit Begründung.
Die Demo-Daten liegen in einer eigenen Datenbank (demo.db in deinem Iris-Home-Verzeichnis — ~/.iris unter macOS/Linux, %USERPROFILE%\.iris unter Windows) und werden nie mit deinen echten Traces vermischt. Entferne alles mit einem Befehl:
npx @iris-eval/mcp-server --demo-clear
Deinen eigenen Agenten verbinden
Prüfe zuerst, ob die Installation auf diesem Rechner funktioniert — der Test läuft offline und öffnet nichts von dir:
npx @iris-eval/mcp-server --self-test # exit 0 = healthy
Füge Iris dann deinem MCP-Client hinzu. Ein Befehl schreibt in die Konfigurationsdatei des Clients, lässt alle anderen Server darin unverändert und fixiert die ausgeführte Version:
npx -y @iris-eval/mcp-server install claude-code
Die Clients: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list zeigt, welche davon auf diesem Rechner gefunden wurden, welche Iris-Version jeweils ausgeführt wird und welche Datei der Client einliest; mit install <client> --uninstall entfernst du Iris wieder. Alle Clients verwenden dieselbe Datenbank. Verschiebe sie daher nach einem Upgrade alle auf einmal mit install --upgrade (Aktualisieren). Starte den Client neu, damit die Änderung geladen wird.
Claude Desktop: ein Klick. Jede Version ab 0.20.0 enthält iris-eval.mcpb, ein MCP Bundle: Lade die neueste Version herunter, öffne sie, und Claude Desktop zeigt einen Installationsdialog an. Nichts darin ist erforderlich — ein Anthropic- oder OpenAI-Schlüssel für den LLM-Judge ist optional, und das Dashboard ist ein Schalter, der standardmäßig ausgeschaltet ist. Das Bundle enthält das npm-Paket und seine Abhängigkeiten, sodass nichts weiter installiert werden muss: Claude Desktop führt es mit der mitgelieferten Node-Version aus, sofern diese 22.13 oder neuer ist (Claude Desktop 1.1.6679 enthält Version 24.13), und Iris speichert Traces mit der integrierten SQLite-Unterstützung von Node im selben ~/.iris, das auch alle anderen Installationen verwenden. In den Versionshinweisen steht, wie du die Signatur und den Build-Nachweis überprüfst.
Iris läuft in jedem MCP-Client, und für jeden aufgeführten Client gibt es einen Eintrag, der erklärt, wie er geprüft wird. Bei jedem CI-Lauf verifiziert: Claude Code, Gemini CLI — der echte Client startet Iris mit der vom Installer geschriebenen Konfiguration und meldet, dass die Verbindung hergestellt wurde (claude mcp list, gemini mcp list), unter Linux, macOS und Windows; auch die Capture-Plugin-Hooks von Claude Code werden über die echten Skripte ausgeführt. Gemäß der MCP-Dokumentation des jeweiligen Clients konfiguriert — der Installer schreibt die Datei, die der jeweilige Client dokumentiert, am dokumentierten Pfad und in seinem eigenen Format (einen mcpServers-Block, VS Codes servers, Zeds context_servers, Codex’ TOML), wobei Kommentare und alle anderen Server erhalten bleiben. Unit-Tests prüfen jeden Pfad und jeden Format-Writer anhand dieser Dokumentation: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Jeder Eintrag mit Quelle und Datum der Prüfung: https://iris-eval.com/clients. Stattdessen manuell einrichten: ein Block, Dashboard inklusive:
{
"mcpServers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
}
}
}
Dein Client zeigt beim Verbinden die zwölf Tools von Iris an, und das Dashboard ist unter http://localhost:6920. erreichbar. Füge nun Folgendes in deinen Agenten ein:
Protokolliere die letzte Aufgabe in Iris und bewerte die Ausgabe.
Der Trace erscheint mit seinen Bewertungen im Dashboard. Du möchtest den MCP-Server lieber ohne Oberfläche ausführen? Entferne --dashboard aus den Argumenten — dasselbe Dashboard kannst du jederzeit mit npx @iris-eval/mcp-server --dashboard öffnen.
Eine wichtige Sache vorab: MCP-Tools werden aufgerufen, wenn das Modell sich dafür entscheidet. Iris fängt deinen Agenten nicht ab. Traces werden also protokolliert, wenn dein Agent Iris darum bittet — entweder, weil du es ihm gesagt hast, oder weil dein Code die Tools direkt aufruft. Bitte deinen Agenten, „das hier in Iris zu protokollieren und zu bewerten“, und er wird es tun. Wenn du eine Erfassung möchtest, die nicht davon abhängt, ob das Modell den Aufruf auswählt, erledigt POST /api/v1/traces genau das — dein Code sendet den Trace über einfaches HTTP, ohne dass ein Modell beteiligt ist (siehe docs/http-ingest.md). Die CLI- und Host-Hooks auf der Roadmap werden schlanke Clients für denselben Endpunkt sein.
Über HTTP erfassen (ohne Modellbeteiligung)
Der Ingest-Endpunkt läuft auf dem Dashboard-Port — standardmäßig 6920, nicht auf dem MCP-Transportport — und ist nur verfügbar, solange das Dashboard läuft. Übergib --dashboard (oder setze IRIS_DASHBOARD=true); --transport http allein startet es nicht, und eine Anfrage an den Transportport gibt 404 zurück. Wenn das Dashboard läuft, kann alles, was HTTP-Anfragen senden kann, einen Trace protokollieren — und optional die deterministischen Auswertungen in derselben Anfrage ausführen. GET /api/v1/capabilities am selben Port gibt an, was dieser Server bewerten kann, welche Voraussetzungen die einzelnen Regeln haben, welchen Status der Judge hat und welche Schritte ihn aktivieren sowie welche Grenzen gelten — dasselbe Objekt, das die MCP-Ressource iris://capabilities bereitstellt. So erhält ein HTTP-Aufrufer denselben Kontext, den ein MCP-Client bei der Initialisierung bekommt:
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"
}'
Gibt 201 mit dem gespeicherten trace_id und dem Auswertungsergebnis zurück (im Modus --demo verweigert der Endpunkt Schreibvorgänge mit 403, damit Demo-Daten nie mit deinen eigenen vermischt werden). Der Endpunkt akzeptiert denselben Body wie das Tool log_trace und durchläuft denselben Middleware-Stack wie der Rest des Dashboards: standardmäßig Bindung an Loopback und Schutz vor DNS-Rebinding sowie Bearer-Authentifizierung, wenn du einen Schlüssel festlegst. Zwei einfache Fakten dazu: Der Endpunkt akzeptiert nicht authentifizierte Schreibvorgänge, sofern Iris nicht mit --api-key (oder IRIS_API_KEY) gestartet wurde — standardmäßig hält die Bindung an Loopback ihn auf deinen Rechner beschränkt. Lege daher einen Schlüssel fest, bevor du ihn außerhalb von Loopback bindest. Und was gespeichert wird, wird unverändert übernommen — input und output landen genau wie gesendet in iris.db, einschließlich aller Texte, die no_pii anschließend markiert. Vollständiger Vertrag, Feldreferenz und Fehlersemantik: docs/http-ingest.md.
Jeden Claude-Code-Turn erfassen (optional)
/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval
Ein zweites, separat installiertes Plugin: Seine Hooks zeichnen den Prompt jedes Turns, Tool-Aufrufe (auch fehlgeschlagene, einschließlich des Fehlers, den der Agent erhalten hat) und die endgültige Antwort auf. Sie werden anhand des Prompts zugeordnet, sodass auch die Aufrufe eines unterbrochenen Turns und die eines Hintergrund-Subagenten gesendet werden. Anschließend übergeben die Hooks sie im Hintergrund an iris-eval ingest, wobei kritische Spans im gespeicherten Auswertungstext redigiert werden — eine Erfassung, die nicht davon abhängt, ob das Modell einen Tool-Aufruf auswählt. Ein Turn, der mit einem API-Fehler endete, wird ohne Bewertung gespeichert. Wenn das Modell den Turn ebenfalls protokolliert hat, bleiben beide Traces erhalten, und der des Plugins wird als solcher gekennzeichnet. Das Plugin gibt nie etwas aus, blockiert nie und sendet nichts irgendwohin. Die Installation von iris-eval allein ändert nichts an deinem Turn-Ablauf. Einschränkungen und Deinstallation: claude-plugin-capture/README.md.
Python
pip install iris-eval
from iris_eval import IrisClient
iris = IrisClient() # IRIS_URL, or the running dashboard's runtime.json
iris.evaluate_output("…", input="…", agent_name="support-bot")["verdict"] # {"state": "pass", "basis": "clean", "by": []}
Ein schlanker Client für die HTTP-API von Server 0.16.0 und höher, mit eigener Versionierung — iris_eval.__version__ und die PyPI-Seite geben seine Versionsnummer an, die nicht der des Servers entspricht: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), synchron und asynchron, typisierte Antworten, die eigene Begründung des Servers für eine Ablehnung — sowie ein pytest-Plugin: eine iris-Fixture und assert_iris(output, expect="pass"), die den Status des Urteils prüft. packages/python/README.md.
Jeden OpenAI- und Anthropic-Aufruf aufzeichnen
from iris_eval import wrap_openai
client = wrap_openai(OpenAI(), agent_name="support-bot") # every call: a GenAI span to POST /v1/traces, scored
import { wrapOpenAI } from '@iris-eval/sdk';
const openai = wrapOpenAI(new OpenAI(), { agentName: 'support-bot' });
Umschließe den Provider-Client einmal, und jeder Modellaufruf wird zu einem OpenTelemetry-GenAI-Span, der an den OTLP-Endpunkt gesendet, mit Eingabe, Ausgabe, Token-Nutzung und Tool-Aufrufen gespeichert und bewertet wird: eine Erfassung, die nicht davon abhängt, ob das Modell ein Tool aufruft. wrap_openai / wrap_anthropic im Python-Client; wrapOpenAI, wrapAnthropic und irisMiddleware für das Vercel AI SDK in @iris-eval/sdk. Beide sind noch nicht veröffentlicht (die nächste Version iris-eval auf PyPI; @iris-eval/sdk wird bis zur ersten npm-Veröffentlichung aus dem Quellcode erstellt). Streams, die Stream-Helfer der SDKs und Tool-Aufrufe werden unterstützt. Der ursprüngliche Client wird nicht verändert, und ein Ausfall von Iris unterbricht keinen Aufruf — packages/sdk/README.md, packages/python/README.md.
Jeden LangChain- und LangGraph-Lauf bewerten
from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})
Jeder Lauf der obersten Ebene wird zu einem Trace (dem Lauf, seinen Modellaufrufen, seinen Tool-Aufrufen und seinen Graph-Knoten als GenAI-Spans) mit Eingabe, Ausgabe, Tool-Aufrufen, Token-Nutzung und einem Urteil. Python im Client (pip install iris-eval, ab Version 0.2.0), JavaScript als @iris-eval/langchain (in diesem Repository, noch nicht auf npm veröffentlicht). Beide werden in CI anhand einer echten LangGraph-App mit einem skriptgesteuerten Modell geprüft. Auch der eigene OpenTelemetry-Export von LangSmith wird auf dieselbe Weise geprüft — docs/otel-recipes.md.
Ein CI-Gate, kein Server erforderlich
npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any
any schlägt den Job bei jedem Urteil fehl, das kein Pass ist: bei einem Fehlschlag und bei einem Urteil, das nicht geprüft wurde. Gib stattdessen eine einzelne Grundlage an (--fail-on detector_veto), damit der Job nur bei dieser fehlschlägt.
Oder die GitHub Action (0.16.0), die den Job bei den von dir angegebenen Urteilen fehlschlagen lässt, den Beleg in die Job-Zusammenfassung schreibt und ihn als einzelnen Pull-Request-Kommentar veröffentlicht, der bei Aktualisierungen ersetzt wird: uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 mit traces: traces.ndjson — docs/ci-gate.md.
Eine vierte Tür (0.15.0): POST /v1/traces am Dashboard-Port nimmt das OTLP/HTTP-JSON oder -Protobuf entgegen, das deine OpenTelemetry-Instrumentierung bereits ausgibt (der Exporter des Python-SDKs spricht nur Protobuf, daher ist dies auch die Python-Tür), und jeder OTLP-Trace wird zu einem Iris-Trace mit seinen Spans — docs/otel-integration.md; ein Rezept pro Framework (Pydantic AI, Google ADK, LangGraph via LangSmith, CrewAI, das OpenAI Agents SDK in Python und JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, das Vercel AI SDK und Mastra), jeweils durch eine Fixture belegt, unter docs/otel-recipes.md. ingest liest einen JSON-Trace (oder NDJSON, einen pro Zeile) von stdin oder aus einer Datei, speichert ihn, wertet ihn exakt nach denselben Regeln aus, die evaluate_output ausführt, gibt eine JSON-Zeile pro Trace mit dem Urteil und seiner Grundlage aus und beendet sich mit Exit-Code 1, wenn ein Urteil auf --fail-on zutrifft. --dataset <id|label> beschränkt dieses Gate auf die Fall-Keys in einem Dataset (POST /api/v1/datasets übernimmt die Fall-Keys eines Laufs in ein Dataset), sodass ein Job nur bei den Fällen fehlschlägt, die du ausgewählt hast. Das vollständige Rezept, die Exit-Codes und die acht Grundlagen findest du unter docs/ci-gate.md.
Eine Regel als Code schreiben
eval.plugins in config.json lädt von dir geschriebene Regeln — ein ES-Modul, dessen Default-Export { name, kind, mechanism, version, needs, evaluate(ctx) } ist — und bindet es an den SHA-256-Hash der Datei. Wenn sich die Datei seit dem Festlegen des Hashes geändert hat, wird der Start verweigert, statt die Datei auszuführen. Ein geladenes Plugin wird wie eine integrierte Regel ausgeführt und erscheint unter list_rules bei plugins. Der Vertrag, das Hash-Verfahren und die möglichen Rückgabewerte eines Plugins: docs/plugins.md.
Die Engine in deinem eigenen Prozess verwenden
Die Evaluierungs-Engine lässt sich importieren — ohne Server, Datenbank oder Modell:
import { EvalEngine, defaultConfig } from '@iris-eval/mcp-server/engine';
const engine = new EvalEngine(defaultConfig.eval.defaultThreshold, defaultConfig.eval.ruleThresholds, defaultConfig.eval);
const result = await engine.evaluateAll({ output: answer, input: prompt, toolCalls, costUsd });
result.verdict.state; // 'pass' | 'fail' | 'unknown', with result.verdict.basis and result.interpretations
Dieselbe Engine, dieselben Regeln und derselbe Composer, die der Server ausführt; builtInRules(), createCustomRule(), compose() und die Reader für veröffentlichte Genauigkeitswerte werden daneben exportiert.
Ein typisierter Client für die HTTP-Route
import { createClient } from '@iris-eval/mcp-server/client';
const iris = createClient({ baseUrl: 'http://127.0.0.1:6920', apiKey: process.env.IRIS_API_KEY });
const { trace_id, evaluation } = await iris.logTrace({ agent_name: 'support-bot', input, output, tool_calls, evaluate: true });
evaluation?.verdict?.state; // the same object evaluate_output returns
Ein Body für jede Tür: Er wird von log_trace und iris-eval ingest akzeptiert. Bei einer Ablehnung wird IrisClientError mit dem eigenen Satz und Status des Servers ausgelöst. Beide Unterpfade werden bei jedem Build anhand eines gepackten Tarballs geprüft.
Installation überprüfen
npx @iris-eval/mcp-server --self-test # offline diagnostic; exit 0 = healthy, 1 = a check failed
npx @iris-eval/mcp-server --version # prints the bare version, e.g. 1.2.3
--self-test erstellt zuerst dein Iris-Home, falls es fehlt, und prüft, ob es beschreibbar ist (Exit-Code 1 mit Angabe des Pfads, falls nicht). Anschließend wird angezeigt, wo sich der Suchindex deiner Datenbank befindet (vollständig, mit der Anzahl der Traces, die ein Hintergrundprozess bisher indexiert hat, oder ohne FTS5 in dieser SQLite-Version), das Schema deiner Datenbank gelesen (Exit-Code 1 mit der Lösung, wenn diese Version oder ein auf eine ältere Version festgelegter MCP-Client sie nicht öffnen kann) und dann werden die Prüfungen ausgeführt — Speicher-Roundtrip, eine erkannte eingefügte SSN und eine erkannte Prompt-Injection, Dashboard-Start und Schutz vor DNS-Rebinding — in einem isolierten temporären Home. Deine echte Datenbank wird nur gelesen, niemals geändert. Alles, was Iris schreibt, liegt in einem Verzeichnis, deinem Iris-Home: standardmäßig ~/.iris (%USERPROFILE%\.iris unter Windows) oder dort, wohin IRIS_HOME zeigt. Dort befinden sich iris.db, config.json, custom-rules.json, audit.log, preferences.json und die Demodateien. Zeige mit IRIS_HOME auf ein temporäres Verzeichnis, um Iris auszuprobieren, ohne deine echten Daten anzurühren.
Einrichtung nach Tool
| Client | Status | Bedeutung | Lesen |
|---|---|---|---|
| Claude Code | verifiziert | Ein Test steuert den echten Client bei jedem CI-Lauf | 2026-09-25 |
| Claude Desktop | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Cursor | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Devin Desktop (Windsurf) | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Continue | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| VS Code | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Cline | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Zed | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| OpenAI Codex CLI | angegeben | Konfiguration anhand der eigenen MCP-Dokumentation des Clients; Pfad und Format des Installers sind durch Unit-Tests abgedeckt | 2026-09-25 |
| Gemini CLI | verifiziert | Ein Test steuert den echten Client bei jedem CI-Lauf | 2026-09-25 |
Jede Zeile mit den geprüften Angaben: iris-eval.com/clients. Kein Client wird ohne einen Eintrag als unterstützt bezeichnet.
npx -y @iris-eval/mcp-server install <client> schreibt all das für dich. Manuell, pro Client:
Claude Desktop
Bearbeite deine MCP-Konfigurationsdatei:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Füge die obige JSON-Konfiguration hinzu und starte Claude Desktop anschließend neu.
Claude Code
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
Starte anschließend die Sitzung neu (/clear oder durch erneutes Starten), damit die Tools geladen werden.
Windows-Hinweis: Verwende nicht den Wrapper
cmd /c— er verursacht Probleme beim Parsen von Pfaden. Der Befehlnpxfunktioniert direkt.
Cursor
Füge die obige JSON-Konfiguration zu ~/.cursor/mcp.json (für jedes Projekt) oder .cursor/mcp.json in einem Workspace hinzu, mit "type": "stdio" im Eintrag iris-eval — laut Cursor-Dokumentation ist dies erforderlich.
Devin Desktop (Windsurf)
Füge die obige JSON-Konfiguration zu mcp_config.json hinzu: ~/.config/devin/mcp_config.json unter macOS und Linux, %APPDATA%\devin\mcp_config.json unter Windows.
Continue
Speichere die obige JSON-Konfiguration als eigene Datei im Ordner mcpServers von Continue: ~/.continue/mcpServers/iris-eval.json (für jeden Workspace) oder .continue/mcpServers/iris-eval.json in einem einzelnen Workspace.
VS Code (natives MCP)
Füge sie in deinem Workspace zu .vscode/mcp.json hinzu (Hinweis: VS Code verwendet servers, nicht mcpServers):
{
"servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"]
}
}
}
Cline
Öffne den Bereich „MCP Servers“ von Cline → „Configure MCP Servers“ und füge die obige JSON-Konfiguration mcpServers zu cline_mcp_settings.json hinzu (~/.cline/data/settings/cline_mcp_settings.json, gemeinsam von Cline in VS Code, JetBrains und der CLI verwendet).
Zed
Füge sie zu settings.json von Zed hinzu:
{
"context_servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"],
"env": {}
}
}
}
OpenAI Codex CLI
Füge sie zu ~/.codex/config.toml hinzu:
[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]
Gemini CLI
Füge die obige JSON-Konfiguration mcpServers zu ~/.gemini/settings.json hinzu. Gemini CLI verbindet sich nur in vertrauenswürdigen Ordnern mit MCP-Servern: Wenn gemini mcp list iris-eval als „Disabled“ anzeigt, führe /permissions in diesem Ordner aus.
Alles andere, das MCP unterstützt
Iris ist ein standardmäßiger stdio-MCP-Server — ein einzelner Befehl npx @iris-eval/mcp-server, kein SDK, keine Codeänderungen. Wenn dein Client MCP unterstützt, unterstützt er auch Iris. Die Konfigurationsformate der Clients ändern sich; im Zweifelsfall sieh in der MCP-Dokumentation deines Clients nach und verweise ihn auf diesen Befehl.
Weitere Installationsmethoden
# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-eval --dashboard
# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint).
# The image binds 0.0.0.0 inside the container, so a key is required (see Production).
# The volume is the Iris home: the database, deployed rules and audit log persist in it.
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
-e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server
Tipp: Bei einer globalen Installation (
npm install -g) werden Traces dauerhaft unter~/.iris/iris.dbgespeichert. Mitnpxbleiben Traces am selben Ort erhalten, der Start dauert jedoch wegen der Paketauflösung länger.
Das Container-Image und die MCP-Verzeichnisse, in denen Iris aufgeführt ist:
Was du bekommst
| Trace-Protokollierung | Hierarchische Span-Bäume mit Latenz pro Tool-Aufruf, Tokenverbrauch und Kosten in USD. In SQLite gespeichert und sofort abfragbar. |
| Ausgabebewertung | 28 integrierte Regeln in 4 Kategorien: Vollständigkeit, Relevanz, Sicherheit und Kosten. PII-Erkennung (21 Muster: SSN, Kreditkarte, Telefonnummer, E-Mail, IBAN, Geburtsdatum, MRN, IP, API-Key, Reisepass sowie AWS-/Slack-/SendGrid-/GitHub-/Google-/npm-/DigitalOcean-Tokens, Zugangsdaten in URLs, Zuweisungen mit geheimnisbezogenen Namen, PEM-Private-Key-Blöcke und Seed-Phrasen; Geburtsdatum, Krankenaktennummer, Reisepass und Seed-Phrase werden nur in der Nähe ihrer Bezeichnung erkannt, absichtlich so), Prompt-Injection (38 Muster, Phrase + Struktur), Erkennung von Platzhalterausgaben, Halluzinationserkennung (25 kontextbezogene Signale für Erfindungen und Widersprüche — übergib input, um sie anhand des Quellmaterials des Agenten zu prüfen) und sechs Trajektorienregeln, die auswerten, was der Agent GETAN hat: ein nicht bestätigter fehlgeschlagener Tool-Aufruf, ein wiederholter Aufruf (nach Aufruf, wiederholter Sequenz oder Ziel, sobald du tools sendest), ein Aufruf, dessen Argumente das eigene JSON-Schema des Tools ablehnt und den der Agent nicht erneut versucht hat, eine Datei, ein Verzeichnis oder eine URL, auf die sich die Antwort bezieht, die aber in nichts vorkommt, was der Agent gelesen hat, eine Anweisung, die in einem TOOL RESULT einging und anschließend von einem späteren Aufruf befolgt wurde, sowie eine Aufgabe, für die mehr Tool-Aufrufe als das Schrittbudget nötig waren. Zwei weitere Regeln vergleichen einen Lauf mit früheren Läufen desselben Agents für denselben Fall, ohne dass jemand die Erwartung festlegen muss: eine Aktion, die kein früherer Lauf ausgeführt hat, und ein Schritt, den jeder frühere Lauf ausgeführt hat, dieser Lauf jedoch nicht. Eine Trajektorie kann als tool_calls oder als OpenTelemetry-TOOL-Spans eingehen. Füge benutzerdefinierte Regeln mit Zod-Schemas hinzu. |
| LLM-as-Judge | Optionale semantische Bewertung über Anthropic oder OpenAI — verwende deinen eigenen API-Key. Sieben Vorlagen. Wenn IRIS_RELEVANCE_JUDGE_MODEL gesetzt ist, fragt answers_the_ask den Judge relevance ab und lässt eine themenfremde Antwort durchfallen; andernfalls wertet die Regel die Anfrage lexikalisch aus und gibt einen Hinweis. Hartes Kostlimit pro Evaluierung (IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL, standardmäßig $0.25), Kosten pro Evaluierung werden im Ergebnis ausgewiesen. |
| Kostentransparenz | Gesamtkosten aller Agents über einen beliebigen Zeitraum. Lege Budgetgrenzen fest. Lass dich bei überhöhten Ausgaben von Agents benachrichtigen. Ein Trace, der Tokenzahlen und ein Modell, aber keine Kosten übermittelt (wie die meisten OpenTelemetry- und Framework-Traces), wird zum Listenpreis des Modells berechnet und überall, wo er angezeigt wird, als geschätzt markiert; pricing.models in config.json legt Preise für Modelle fest, die nicht in der integrierten Tabelle enthalten sind — docs/cost.md. |
| Web-Dashboard | Dunkle Echtzeit-Oberfläche, die zuerst die Fehler anzeigt, schlimmste und neueste zuerst — Trace-Visualisierung mit Volltextsuche über den Text aller Traces, Evaluierungsergebnisse, Kostenaufschlüsselungen und eine Befehlspalette (⌘K), die deine eigenen Regeln, Traces und Evaluierungen durchsucht. |
| Lokal zuerst | Alles liegt in SQLite auf deinem Datenträger. Der selbst gehostete Server benötigt weder Konto noch Registrierung und sendet keine Telemetriedaten. Ausgehende HTTP-Anfragen erfolgen nur, wenn du sie aktivierst: mit deinem eigenen LLM-Judge-Key, beim Abrufen von Zitaten, über einen von dir konfigurierten OTel-Exporter oder an einen von dir eingerichteten Webhook. |
Wohin es als Nächstes geht: die Funktionsübersicht — jede Frage, die Iris zu jedem Thema gestellt werden kann, mit dem, was Iris weiß und was ihr fehlt — und die drei Entwicklungspfade.
Gemessen, nicht behauptet
Jede integrierte Regel hat veröffentlichte Präzisions-, Trefferquoten- und F1-Werte mit 95-%-Konfidenzintervallen. Sie wurden anhand eines annotierten Korpus gemessen, der sich in diesem Repository befindet (proof/corpus/) und sich mit einem einzigen Befehl — npm run proof — offline, ohne Schlüssel und ohne Modell im Ablauf neu erzeugen lässt. Diese Werte beruhen auf zwei unterschiedlichen Arten von Messungen, die auf der Seite niemals zusammengerechnet werden: Einige Regeln werden anhand von Labels gemessen, die ein Modell durch Lesen des Fehlers selbst vergeben hat; das misst die Erkennung. Die übrigen werden unabhängig anhand ihrer eigenen dokumentierten Definition geprüft; das zeigt, ob der Code die Formel implementiert, sagt aber nichts darüber aus, ob die Formel den Fehler erkennt. proof/RESULTS.md und die Nachweisseite kennzeichnen jede Regel. CI wiederholt die Messung bei jedem Pull Request und schlägt fehl, wenn die eingecheckten Werte von den Ergebnissen des Codes abweichen. So kann sich eine Regel nicht ändern, ohne dass sich auch ihre Werte ändern. Die Werte stehen auf iris-eval.com/proof und in proof/RESULTS.md; wie der Korpus erstellt wurde, was er nicht ist und wie ein Intervall zu lesen ist, steht unter docs/proof.md. Der Korpus ist synthetisch und mit Modell-Labels versehen — eine verblindete menschliche Annotation steht noch aus, worauf die Seite hinweist; node proof/blind-sample.mjs zieht die reproduzierbare Stichprobe, die diese Frage klären wird.
MCP-Tools
Iris registriert zwölf Tools, die jeder MCP-kompatible Agent aufrufen kann — für Trace- und Regel-Lebenszyklus, Vergleiche zwischen Durchläufen, LLM-as-Judge und semantische Zitatprüfung:
log_trace— Protokolliert eine Agentenausführung mit Spans, Tool-Aufrufen, Token-Verbrauch und Kosten; übergibevaluate: true, um sie im selben Aufruf zu bewertenevaluate_output— Bewertet die Ausgabequalität anhand von Regeln zu Vollständigkeit, Relevanz, Sicherheit und Kosten (heuristisch, deterministisch, kostenlos)get_traces— Durchsucht gespeicherte Traces mit Filtern, Paginierung und Unterstützung für Zeitbereiche und findet den Durchlauf, in dem der Agent etwas mitqgesagt hat: Volltextsuche über Eingaben, Ausgaben, Tool-Aufrufwerte und Metadaten, sortiert nach Relevanz, mit markierten Treffernlist_rules— Listet bereitgestellte benutzerdefinierte Eval-Regeln auf (schreibgeschützt)deploy_rule— Registriert eine neue benutzerdefinierte Eval-Regel, damit sie bei jedemevaluate_outputdieser Kategorie ausgelöst wirddelete_rule— Entfernt eine bereitgestellte benutzerdefinierte Regel (destruktiv, idempotent)delete_trace— Entfernt einen einzelnen gespeicherten Trace anhand seiner ID (destruktiv, auf den Mandanten beschränkt)evaluate_with_llm_judge— Semantische Eval per LLM (Anthropic oder OpenAI). Sieben Vorlagen: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance. Mit Kostenobergrenze und ausgewiesenen Preisen pro Eval. Verwende deinen eigenen API-Schlüssel (IRIS_ANTHROPIC_API_KEYoderIRIS_OPENAI_API_KEY) — Iris leitet LLM-Aufrufe weder über einen Proxy noch weiter.verify_citations— Extrahiert Zitate aus der Ausgabe (nummeriert, Autor-Jahr, URLs, DOIs), ruft Quellen über einen SSRF-geschützten Resolver mit Domain-Allowlist ab und verwendet einen LLM-Judge, um zu prüfen, ob jede Quelle die zitierte Behauptung tatsächlich stützt. Ausgehende HTTP-Anfragen nur nach ausdrücklicher Aktivierung. Dieselbe BYOK-Anforderung wie beievaluate_with_llm_judge.compare_runs— Hat eine Änderung den Agenten verschlechtert? Vergleicht zwei Durchläufe gespeicherter Evaluationen: einen gepaarten exakten Test, wenn die Durchläufe gemeinsame Fall-Keys haben, andernfalls ein Intervall für die Differenz, ein ehrliches „nicht feststellbar“ mit der benötigten Fallzahl oder „innerhalb einer Marge gleichwertig“. Für jede Regel gilt ein eigener einseitiger Test; die Tests werden gemeinsam korrigiert (Benjamini–Hochberg), damit zwanzig Regeln nicht künstlich eine Regression erzeugencompare_traces— Wie zuverlässig beantwortet der Agent dieselbe Frage? Pass-Raten pro Fall mit Intervallen, zuerst die instabilen Fälle und eine Gesamtrate, die Wiederholungen berücksichtigtevaluate_runs— Bewertet jeden Trace eines Durchlaufs erneut anhand der heutigen Regeln und erstellt einen neuen Durchlauf, damit eine Regeländerung nie als Agentenänderung fehlinterpretiert wird
LLM-Judge aktivieren (optional; die deterministischen Regeln benötigen ihn nie)
- Besorge dir einen API-Schlüssel von Anthropic oder OpenAI.
- Hinterlege ihn in der Umgebung des Prozesses, der Iris ausführt, nicht nur in deiner Shell. Claude Code, Claude Desktop, Cursor und die meisten MCP-Clients: im „env“-Block des iris-eval-Eintrags in deiner MCP-Konfiguration — „iris-eval“: { „command“: „npx“, „args“: [„-y“, „@iris-eval/mcp-server“], „env“: { „IRIS_ANTHROPIC_API_KEY“: „sk-ant-...“ } } (IRIS_OPENAI_API_KEY für einen OpenAI-Schlüssel). Docker: -e IRIS_ANTHROPIC_API_KEY=... im Ausführungsbefehl. HTTP oder CI: exportiere den Schlüssel, bevor du iris-eval startest.
- Starte die MCP-Sitzung neu. Ein laufender Prozess sieht keine Variable, die erst nach seinem Start gesetzt wurde.
- Prüfe direkt in deinem Client: Lies iris://capabilities — dort muss judge.enabled auf true stehen. Ein in deiner Shell exportierter Schlüssel wird nicht an den vom Client gestarteten Prozess weitergegeben, sofern er nicht in dessen Konfiguration aufgeführt ist. Auf einem Rechner gibt
npx @iris-eval/mcp-server --self-testdie Judge-Zeile für diese Shell aus; GET /api/v1/health meldet judge.enabled auf einem laufenden Dashboard. - Ausgabenschutz: Jeder Aufruf ist durch IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL begrenzt (Standardwert 0.25 USD) und wird abgelehnt, bevor Kosten entstehen, wenn der Höchstbetrag diese Grenze überschreiten würde. Jeder Judge-Aufruf, den Iris mit deinem Schlüssel tätigt, wird auf ein gemeinsames Tagesbudget angerechnet: IRIS_LLM_JUDGE_DAILY_BUDGET_USD (Standardwert 1 USD pro UTC-Tag); nach Erreichen des Limits erfolgen bis Mitternacht UTC keine weiteren Aufrufe. Iris ruft den Anbieter direkt mit deinem Schlüssel auf und verwendet keinen Proxy.
- Optional: Setze IRIS_RELEVANCE_JUDGE_MODEL auf eine bepreiste Modell-ID (zum Beispiel claude-haiku-4-5), damit answers_the_ask den Judge fragt, ob jede Antwort auf die jeweilige Frage eingeht, und themenfremde Antworten durchfallen lässt. Pro Evaluation mit Eingabe erfolgt ein Judge-Aufruf, der mit deinem Schlüssel und innerhalb der oben genannten Kostenobergrenze ausgeführt wird; der Schlüssel allein aktiviert diese Funktion nicht. Bei jedem Aufruf werden die Eingabe und Ausgabe an den Modellanbieter gesendet, nachdem die Flags no_pii für personenbezogene Daten und Zugangsdaten ersetzt wurden (IRIS_RELEVANCE_JUDGE_REDACT=off sendet sie unverändert). Die Aufrufe werden auf dasselbe Tagesbudget angerechnet und sind pro Anfrage auf IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST begrenzt (Standardwert 20); nach Erreichen eines der beiden Limits wertet answers_the_ask die Frage lexikalisch aus und erklärt warum.
Wenn IRIS_OTEL_ENDPOINT konfiguriert ist, geben Aufrufe von log_trace außerdem nach bestem Bemühen einen OTLP/HTTP-JSON-Export an beliebige OpenTelemetry-Collector aus (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb usw.). Siehe docs/otel-integration.md.
Wie passed entschieden wird
evaluate_output gibt sowohl ein score als auch ein passed-Flag zurück — sie beantworten unterschiedliche Fragen:
score(0..1) ist der gewichtete Durchschnitt der ausgeführten Regeln — ein Qualitätsindikator.passedist das Go/No-Go-Urteil; der Score wird dafür niemals herangezogen. Ein Composer wertet jede Regel nach der Art ihrer Aussage aus: Eine von dir konfigurierte Richtlinie ist ein Gate; ein kritischer Detektor kann ein Veto einlegen; eine kritische Prüfung, die angefordert wurde, aber keine Antwort liefern konnte, führt zum Urteil unbekannt (passed: false) statt zu „unbedenklich“; alle übrigen Detektoren werden zu einer Wahrscheinlichkeit zusammengefasst, dass die Ausgabe fehlerhaft ist, und anhand des von dir ineval.falsePassCostangegebenen Verlustverhältnisses gewichtet (Standardwert 1, also liegt der Schwellenwert bei 0.5).verdict.basisnennt die entscheidende Ebene undverdict.bydie Regeln;verdict.alsolistet alle späteren Ebenen auf, die ebenfalls entschieden hätten;interpretations[]erklärt, warum eine fehlgeschlagene Regel nicht entscheidend war und welche Einstellung das ändern würde, und nennt alle Fragen, die nicht bewertet wurden, sowie die Eingabe, die eine Bewertung ermöglichen würde.
Echte Sicherheitsverstöße führen zu einem harten Fehlschlag. Standardmäßig sind no_pii, no_injection_patterns und no_blocklist_words kritische Regeln: Schlägt eine davon fehl, meldet die Eval passed: false, unabhängig davon, wie gut die übrigen Regeln abschneiden; die Antwort nennt die verantwortlichen Regeln in critical_failures. Eine offengelegte SSN lässt sich nicht durch Mittelwertbildung ausgleichen. Welche integrierten Regeln kritisch sind, ist eine Deployment-Einstellung (eval.criticalRules / eval.nonCriticalRules); ebenso lässt sich festlegen, welche Detektoren nur berichten (eval.advisoryRules). Jedes Regelergebnis enthält das wirksame critical-Flag und criticalSource; list_rules meldet die Regelliste, die dieser Server anwendet. Benutzerdefinierte Regeln, die mit severity: "high" oder "critical" bereitgestellt wurden, führen auf dieselbe Weise zu einem harten Fehlschlag; die Schweregrade low/medium wirken sich nur auf den Score aus. Eine wichtige Grenze, die auf allen Oberflächen gleich beschrieben wird: Eine kritische Regel, die übersprungen wurde (fehlender Kontext, fehlerhafte Definition oder ein Regex, der wegen des Sandbox-Zeitlimits abgebrochen wurde), hat die Ausgabe nicht bewertet und legt daher kein Veto ein — jede solche Regel wird in critical_skipped genannt. Ein Gate, das bei Fehlern geschlossen bleiben muss, behandelt ein nicht leeres critical_skipped als unbekannt, nicht als unbedenklich, und kann jeden budgetExceeded-Skip in rule_results genauso behandeln.
Für CI-Gates gilt: Wenn du eval_type weglässt, werden alle Bundles ausgeführt — Vollständigkeit, Relevanz, Sicherheit, Kosten und alle benutzerdefinierten Regeln. Die Antwort enthält eval_type: "all" mit einem note, das bestätigt, dass die Standardeinstellung ausgeführt wurde, sowie eine categories-Map pro Bundle. Jede Zeile enthält state: das Urteil für die Regeln dieses Bundles, sodass eine Zeile niemals „bestanden“ meldet, wenn Regeln die Evaluation nicht bestanden haben. Ein Bundle, für das es nichts zu bewerten gibt (Kosten ohne cost_usd, Relevanz ohne input), meldet dort state: "unknown" und passed: null — nicht ausgewertet, nicht fehlgeschlagen — und wird nie für das Urteil berücksichtigt. Die Antwort gibt immer das ausgeführte eval_type zurück, damit dein Gate die Abdeckung prüfen kann. Verwende passed für das Urteil und gib ein Bundle nur an, wenn du einen enger gefassten Durchlauf möchtest.
Eine benutzerdefinierte Regel erstellen
Es gibt zwei Möglichkeiten, eine Regel hinzuzufügen. Inline-Regeln werden bei einem einzelnen Aufruf von evaluate_output mitgegeben (custom_rules, bis zu 10 pro Aufruf); sie werden zusätzlich zum ausgewählten eval_type-Bundle oder allein mit eval_type: "custom" ausgeführt. Bereitgestellte Regeln werden einmalig mit deploy_rule registriert, unter custom-rules.json im Iris-Home-Verzeichnis gespeichert und bei jedem künftigen evaluate_output ihrer Kategorie evalType ausgeführt. Die Definition hat in beiden Fällen dieselbe Form:
| Feld | Erforderlich | Beschreibung |
|---|---|---|
name | ja | 1–80 Zeichen; erscheint in den Ergebnissen als ruleName |
type | ja | eines von regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold |
config | ja | die Schlüssel für diesen Typ: pattern (+ optional flags) für die beiden Regex-Typen · min_length / max_length (eine Zeichenanzahl) · keywords (+ optional threshold, 0–1, Standardwert 1 = alle müssen vorkommen) für die beiden Schlüsselworttypen · {} für json_schema · max_cost in USD für cost_threshold |
weight | nein | Gewicht im Score; Standardwert 1 |
deploy_rule umschließt die Definition mit name, einem optionalen description, evalType (completeness · relevance · safety · cost · custom) und severity. Der Schweregrad gibt an, was ein Fehlschlag bedeutet: low/medium senken nur den Score; high/critical führen zu einem harten Fehlschlag der Evaluation — passed: false, wobei die Regel in critical_failures genannt wird — unabhängig vom gewichteten Score. Eine übersprungene Regel (eine cost_threshold-Regel ohne cost_usd oder ein Regex, der wegen des Sandbox-Zeitlimits von 100 ms abgebrochen wurde) hat die Ausgabe nicht bewertet und wird stattdessen in critical_skipped aufgeführt. Stelle eine kritische Regel bereit, die interne Hostnamen in allen Agentenausgaben verbietet:
{
"name": "no_internal_hostnames",
"description": "Output must not mention internal hostnames.",
"evalType": "safety",
"severity": "critical",
"definition": {
"name": "no_internal_hostnames",
"type": "regex_no_match",
"config": { "pattern": "\\b[a-z0-9-]+\\.internal\\.example\\b", "flags": "i" }
}
}
Die Antwort enthält die gespeicherte Regel — bewahre das id für delete_rule auf:
{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }
Ab dem unmittelbar nächsten evaluate_output mit eval_type: "safety" kommt eine Ausgabe, die db-primary.internal.example erwähnt, passed: false mit critical_failures: ["no_internal_hostnames"] zurück — obwohl alle fünf integrierten Sicherheitsregeln bestanden wurden und der gewichtete Score 0.895 beträgt. Regex-Muster müssen beim Deployment eine ReDoS-Prüfung bestehen und immer in einem Sandbox-Worker mit einer harten Frist von 100 ms ausgeführt werden. list_rules zeigt, was deployed wird; der Regel-Composer im Dashboard erstellt dieselbe Struktur anhand eines Fehlers, auf den du geklickt hast. Vollständige Referenz, Bewertung nach Typ und ausgearbeitete Beispiele: docs/custom-rules.md.
Vollständige Tool-Schemas und Konfiguration: iris-eval.com
Selbst gehostet und kostenlos
Iris läuft auf deinem Rechner oder deiner eigenen Infrastruktur. Der Open-Source-Kern ist kostenlos und unter der MIT-Lizenz veröffentlicht, ohne Nutzungslimits und ohne Konto. Gehosteter Speicher, gemeinsamer Teamverlauf und Benachrichtigungen werden erwogen, aber nicht entwickelt; wenn sie dir helfen würden, schreib uns an hello@iris-eval.com.
Zwei Zusagen gelten: Nichts, was heute kostenlos ist, wird hinter eine Bezahlschranke verschoben, und es werden keine Compliance-Zertifizierungen beansprucht, bevor sie vorliegen.
Beispiele
- Claude Desktop einrichten — MCP-Konfiguration für stdio- und HTTP-Modi
- TypeScript — MCP-SDK-Client — Tools verbinden und aufrufen
- HTTP-Transport (TS + Python) — vollständiger Client-Code für eine REST-ähnliche Integration
- Ein LangGraph-Agent, Lauf für Lauf bewertet (Python) —
IrisCallbackHandlerin den Callbacks des Graphen; CI führt denselben Graphen mit einem skriptgesteuerten Modell aus - Ein CrewAI-Team über OpenTelemetry (Python) — der OpenInference-Instrumentor direkt an Iris' OTLP-Schnittstelle, das CrewAI-Rezept als Skript
- Ein OpenAI-Agents-SDK-Agent über OpenTelemetry (Python) und (JavaScript) sowie ein LlamaIndex-Agent — jedes Rezept als Skript, das CI gegen einen echten Iris-Server ausführt
Community
- GitHub-Issues — Fehlerberichte und Funktionswünsche
- GitHub-Diskussionen — Fragen und Ideen
- Hilfe erhalten — Wo du Fragen stellen, einen Fehler melden oder eine Sicherheitslücke melden kannst
- Leitfaden zum Mitwirken — So kannst du beitragen; AGENTS.md ist derselbe Leitfaden für Coding-Agenten
- Governance — Wer entscheidet, wie Änderungen übernommen und Releases erstellt und überprüft werden
- HTTP-Ingest — Deterministische Trace-Erfassung über
POST /api/v1/traces - Funktionsübersicht — Alle Fragen, die Iris gestellt werden können, und was noch fehlt
- Versionsrichtlinie — Was jede Versionsnummer verspricht und was vor Version 1.0 erfüllt sein muss
Konfiguration & Sicherheit
CLI-Argumente
| Flag | Standard | Beschreibung |
|---|---|---|
--transport | stdio | Transporttyp: stdio oder http |
--port | 3000 | Port des HTTP-Transports |
--db-path | ~/.iris/iris.db | Pfad zur SQLite-Datenbank |
--config | ~/.iris/config.json | Pfad zur Konfigurationsdatei |
--api-key | — | API-Schlüssel für die HTTP-Authentifizierung (Transport und Dashboard, einschließlich POST /api/v1/traces) |
--dashboard | false | Web-Dashboard aktivieren. Außerdem die einzige Möglichkeit, den Ingest-Endpunkt POST /api/v1/traces zu starten — er wird mit --transport http niemals implizit gestartet |
--dashboard-port | 6920 | Dashboard-Port |
--dashboard-host | 127.0.0.1 | Bind-Adresse des Dashboards. Standardmäßig Loopback — das Dashboard ist nicht authentifiziert, sofern --api-key nicht gesetzt ist; eine Bindung außerhalb von Loopback legt daher deinen gesamten Trace-Verlauf offen |
--demo | false | Eine Demo-Datenbank (getrennt von deinen echten Traces) anlegen und das Dashboard damit bereitstellen |
--demo-clear | false | Die Demo-Datenbank löschen und beenden |
--self-test | false | Die Offline-Installationsdiagnose in einem isolierten temporären Home-Verzeichnis ausführen und anschließend beenden (0 = alles in Ordnung, 1 = eine Prüfung fehlgeschlagen). Liest außerdem die konfigurierte Datenbank schreibgeschützt und schlägt fehl, wenn diese Version oder ein festgelegter MCP-Client sie nicht öffnen kann |
--purge | false | Alle gespeicherten Traces, Spans und Auswertungen aus der konfigurierten Datenbank löschen, die Datei komprimieren und das Write-Ahead-Log kürzen, damit der gelöschte Text nicht auf dem Datenträger zurückbleibt, und anschließend beenden. Deployed-Regeln, Audit-Log und Einstellungen bleiben erhalten. Nicht rückgängig zu machen. Beende zuerst alle laufenden Iris-Server — die Datei wird direkt vor Ort komprimiert. Kann nicht mit --demo, --demo-clear oder --self-test kombiniert werden |
--version | — | Die reine Versionsnummer (z. B. 1.2.3) nach stdout ausgeben und mit Status 0 beenden. Liest nichts aus deinem Iris-Home-Verzeichnis |
Drei Befehle nehmen eigene Argumente entgegen und beenden sich anschließend: iris-eval ingest lädt Traces aus einer Datei oder von stdin (Ein CI-Gate, kein Server erforderlich), iris-eval export traces|evaluations --format csv|jsonl schreibt die gespeicherten Daten, gefiltert wie die Listen im Dashboard, nach stdout oder --out (docs/api-reference.md), und iris-eval install <client> trägt Iris in die Konfiguration eines MCP-Clients ein — --uninstall entfernt es, --list zeigt die auf diesem Rechner gefundenen Clients und die jeweilige Iris-Version an, --upgrade aktualisiert jeden Client, der Iris ausführt, auf diese Version (Eigenen Agenten anbinden, Aktualisieren). Keiner davon startet einen Server.
config.json wird beim Start von Iris validiert. Ein Schlüssel, den Iris nicht kennt — ein Tippfehler wie eval.critcalRules oder ein Schlüssel eines anderen Tools — oder ein Wert mit falschem Typ verhindert den Start. Es erscheint ein Satz, der den vollständigen Schlüssel, den wahrscheinlich gemeinten Schlüssel oder den erwarteten Typ nennt. Nichts in der Datei wird stillschweigend ignoriert.
Umgebungsvariablen
Jede Variable, die --help dokumentiert. Wenn CLI-Flags und Umgebungsvariablen gleichzeitig gesetzt sind, haben die CLI-Flags Vorrang.
| Variable | Beschreibung |
|---|---|
IRIS_TRANSPORT | Transporttyp (stdio oder http) |
IRIS_HOST | Bind-Adresse des HTTP-Transports (Standard: 127.0.0.1) |
IRIS_PORT | Port des HTTP-Transports (1–65535, Standard: 3000) |
IRIS_HOME | Verzeichnis für alle benutzerspezifischen Dateien: config.json, iris.db, custom-rules.json, audit.log, preferences.json (Standard: ~/.iris) |
IRIS_DB_PATH | SQLite-Datenbankpfad (überschreibt IRIS_HOME nur für die Datenbank) |
IRIS_SQLITE_DRIVER | Welcher SQLite-Treiber die Datenbank verwaltet: native (better-sqlite3, der Standard) oder node (integriertes node:sqlite von Node, Node 22.13+). Nicht gesetzt: native; wenn das native Modul nicht geladen werden kann (oder ein Build vorliegt, der unter dieser Node-Version abbrechen würde), gibt Iris einmal eine Warnung aus und verwendet stattdessen das integrierte Modul |
IRIS_SEARCH_BUDGET_MS | Wie lange eine Trace-Suche (q) lesen darf, bevor sie mit den bis dahin gefundenen Treffern und search.complete: false antwortet, in Millisekunden (50 bis 60000, Standard: 1000). Während des Lesens blockiert eine Suche andere Anfragen; dies ist also auch die maximale Wartezeit für diese. Außerdem storage.searchBudgetMs in config.json |
IRIS_SEARCH_INDEX | on (Standard) oder off. off führt keinen Volltextindex der Traces: Beim Schreiben wird nur der Trace gespeichert, sonst nichts, und eine Trace-Suche (q) liest die Traces selbst innerhalb von IRIS_SEARCH_BUDGET_MS, beginnend mit den neuesten. Bei einem großen Speicher kann sie daher nur einen Teil der Treffer zurückgeben (search.complete: false). Beim Deaktivieren wird der von der Datenbank gespeicherte Index gelöscht; beim erneuten Aktivieren wird im Hintergrund ein neuer erstellt. Außerdem storage.searchIndex in config.json |
IRIS_LOG_LEVEL | Protokollierungsstufe: debug, info, warn, error |
IRIS_DASHBOARD | true/1/yes/on aktiviert das Web-Dashboard; false/0/no/off deaktiviert es (überschreibt außerdem dashboard.enabled in config.json) |
IRIS_DASHBOARD_PORT | Dashboard-Port (1–65535, Standard: 6920) |
IRIS_WEBHOOK_URL | Empfänger des Webhooks, der bei einem Moment ausgelöst wird — zusammengeführt mit notify.webhook in config.json (docs/webhooks.md) |
IRIS_WEBHOOK_SECRET | Signaturschlüssel des Webhooks (beliebige Zeichenfolge oder whsec_ + base64); das Format iris kann ohne Schlüssel nicht ausgeführt werden |
IRIS_DASHBOARD_HOST | Bind-Adresse des Dashboards (Standard: 127.0.0.1) |
IRIS_API_KEY | API-Schlüssel für die HTTP-Authentifizierung. Erforderlich, um den HTTP-Transport oder das Dashboard außerhalb von Loopback zu binden (0.0.0.0, eine LAN-Adresse, ein Container): Ohne ihn verweigert der Server den Start |
IRIS_API_KEY_FILE | Pfad zu einer Datei, deren getrimmter Inhalt der API-Schlüssel ist — das Muster mit geheimen Dateien, die Docker und Kubernetes einbinden, sodass der Schlüssel nie in einer Umgebungsvariablen steht. Setzen Sie entweder dies oder IRIS_API_KEY, nicht beides |
IRIS_ALLOW_UNAUTHENTICATED | Auf 1 setzen, um absichtlich eine Nicht-Loopback-Bindung ohne Schlüssel auszuführen (hebt die Startverweigerung auf; das Netzwerk bildet dann Ihre Sicherheitsgrenze) |
IRIS_ALLOWED_ORIGINS | Durch Kommas getrennte Zulassungsliste für Origins. Dashboard: CORS-Header (unterstützt Globs, z. B. http://localhost:*). HTTP-Transport: Zulassungsliste mit exakter Übereinstimmung für Origin zum Schutz vor DNS-Rebinding (Globs werden ignoriert; die eigenen Loopback-Origins des Servers sind immer zulässig) |
IRIS_MAX_INPUT_ELEMENTS | Maximale Anzahl von Array-Elementen und Objektschlüsseln, die eine Eingabe enthalten darf, bevor sie validiert wird (ganze Zahl, Standard: 100000): Argumente eines Tool-Aufrufs bei jedem Transport sowie ein Request-Body am Dashboard-Port (die JSON-Bodies der API und POST /v1/traces, JSON oder protobuf). Ein Tool-Aufruf, der den Grenzwert überschreitet, erhält ein Fehlerergebnis; ein Body wird mit 413 beantwortet. Der Standardwert lässt jede gemessene legitime JSON-Eingabe zu, selbst wenn sie den gesamten 1-MB-Request ausfüllt. Für einen protobuf-Body auf POST /v1/traces gilt eine eigene Obergrenze: ein Element pro 5 Bytes von security.requestSizeLimit (209,716 bei 1 MB) oder dieser Wert, falls er höher ist. Dadurch wird ein Batch eines Exporters innerhalb der Request-Größe nicht wegen seiner Dichte abgewiesen (der dichteste gemessene echte Exporter-Body enthält ein Element pro 7.5 Bytes). Wird requestSizeLimit für größere Batches eines Collectors erhöht, steigt auch diese Grenze. Außerdem security.maxInputElements in config.json |
IRIS_MAX_TOOL_INPUT_ELEMENTS | Der Name von IRIS_MAX_INPUT_ELEMENTS vor 0.21.0; wird gelesen, wenn der neue Name nicht gesetzt ist (und ebenso security.maxToolInputElements in config.json) |
IRIS_NO_AUTO_LAUNCH | Auf 1 setzen, um den automatischen Start des Dashboards beim ersten Ausführen zu deaktivieren |
IRIS_ANTHROPIC_API_KEY | Erforderlich für evaluate_with_llm_judge + verify_citations mit provider=anthropic |
IRIS_OPENAI_API_KEY | Erforderlich für evaluate_with_llm_judge + verify_citations mit provider=openai |
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL | Harte Kostengrenze pro LLM-Judge-Aufruf (Standard: 0.25). max_cost_usd kann sie für einen Aufruf senken, aber niemals erhöhen |
IRIS_RELEVANCE_JUDGE_MODEL | ID eines bepreisten Judge-Modells (z. B. claude-haiku-4-5). Wenn diese Variable gesetzt ist und der Schlüssel des Anbieters vorliegt, fragt answers_the_ask bei jeder Auswertung mit Eingabe diesen LLM-Judge ab und entscheidet anhand seines Relevanzurteils — ein Judge-Aufruf pro Auswertung, innerhalb der obigen Kostengrenze und der beiden folgenden Limits. Die Eingabe und Ausgabe jeder solchen Auswertung werden an den Anbieter dieses Modells (Anthropic oder OpenAI) über Ihren Schlüssel gesendet; zuvor werden die durch no_pii gekennzeichneten personenbezogenen Daten und Zugangsdaten ersetzt. Wenn nicht gesetzt (Standard), wertet answers_the_ask die Anfrage lexikalisch aus und gibt Empfehlungen; es werden keine Daten gesendet (docs/llm-as-judge.md) |
IRIS_LLM_JUDGE_DAILY_BUDGET_USD | Betrag, den alle Judge-Aufrufe zusammen pro UTC-Tag und Mandant höchstens kosten dürfen (Standard: 1): Der Relevanz-Judge, evaluate_with_llm_judge und verify_citations teilen sich dieses Limit. Es wird in der Datenbank gespeichert und durch einen Neustart nicht zurückgesetzt. Ein Aufruf erfolgt nur, wenn seine Worst-Case-Kosten in das verbleibende Budget passen; danach wertet answers_the_ask die Anfrage lexikalisch aus (judge.withheld: "daily_budget") und die Judge-Tools antworten mit IRIS_BUDGET_EXCEEDED (einem Zitat, daily_budget_reached). 0 verhindert alle Aufrufe |
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD | Der Name von IRIS_LLM_JUDGE_DAILY_BUDGET_USD vor 0.21.0, als es nur den Relevanz-Judge begrenzte. Wird gelesen, wenn der neue Name nicht gesetzt ist; dann begrenzt es alle Judge-Aufrufe. Der Server weist beim Start darauf hin |
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST | Anzahl der Relevanz-Judge-Aufrufe pro Request (Standard: 20): Bei einem OTLP-Batch oder einer erneuten Bewertung mit evaluate_runs beurteilt der Judge die ersten 20 Traces und wertet den Rest lexikalisch aus, mit judge.withheld: "request_cap" |
IRIS_RELEVANCE_JUDGE_REDACT | on (Standard): Die durch no_pii gekennzeichneten Daten (personenbezogene Daten und Zugangsdaten) in Eingabe und Ausgabe jedes Spans werden vor dem Senden an den Relevanz-Judge durch eine [REDACTED:<kind>#<n>]-Markierung ersetzt. off sendet sie unverändert |
IRIS_CITATION_ALLOW_FETCH | Auf 1 setzen, um ausgehende HTTP-Anfragen in verify_citations zu erlauben (standardmäßig deaktiviert). Ein Tool-Argument kann dies für einen Aufruf deaktivieren, aber nicht aktivieren |
IRIS_CITATION_DOMAINS | Durch Kommas getrennte Hostnamen-Zulassungsliste für verify_citations (Suffixübereinstimmung). Ein Tool-Argument kann sie einschränken, aber keine Einträge hinzufügen |
IRIS_CITATION_MAX_COST_USD_TOTAL | Höchstbetrag, den ein einzelner verify_citations-Aufruf für Judge-Aufrufe ausgeben darf (Standard: 1). max_cost_usd_total kann ihn für einen Aufruf senken, aber niemals erhöhen |
IRIS_OTEL_ENDPOINT | Best-Effort-Export von Traces als OTLP/HTTP-JSON an diese Collector-URL aktivieren |
IRIS_OTEL_SERVICE_NAME | service.name-Ressourcenattribut für den OTel-Export (Standard: iris-eval) |
IRIS_OTEL_HEADERS | Durch Kommas getrennte k=v-Header für den OTel-Export (z. B. authorization=Bearer abc) |
IRIS_OTEL_TIMEOUT_MS | Timeout pro Export (Standard: 15000) |
RATE_LIMIT_SALT | Nur Website — salzt den Adress-Hash, den das Ratenlimit des iris-eval.com-Playgrounds speichert; der Server liest diese Variable nie |
Sicherheit
Bei Verwendung des HTTP-Transports umfasst Iris:
- API-Schlüsselauthentifizierung mit zeitkonstantem Vergleich (Bearer für API-Clients; Browser-Anmeldung beim Dashboard über
?key=) - CORS standardmäßig auf localhost beschränkt
- Ratenbegrenzung pro Client-Adresse und Minute: 600 Anfragen an die Dashboard-API (
security.rateLimit.api) und 20 an den MCP-Endpunkt (security.rateLimit.mcp), beide inconfig.jsonfestgelegt; eine MCP-Anfrage, die das Limit überschreitet, erhält einen JSON-RPC-Fehler, der den Schlüssel nennt - Helmet-Sicherheitsheader
- Zod-Eingabevalidierung auf allen Routen
- ReDoS-sichere reguläre Ausdrücke für benutzerdefinierte Eval-Regeln
- Ein Request-Größenlimit von 1 MB für jeden Transport (
security.requestSizeLimit): HTTP antwortet mit413, stdio mit einem JSON-RPC-Fehler und hält die Sitzung offen - Ein Limit von 100,000 Array-Elementen und Objektschlüsseln pro Eingabe, gezählt vor der Validierung (
security.maxInputElements): Argumente eines Tool-Aufrufs bei jedem Transport erhalten bei Überschreitung ein Fehlerergebnis; ein Dashboard- oder OTLP-Request-Body erhält einen413 - Validierungsfehler geben höchstens 20 Probleme und die Gesamtzahl zurück (
issueCount), damit die Antwort unabhängig davon, wie fehlerhaft der Request ist, klein bleibt
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard
Wenn ein Schlüssel gesetzt ist, senden API-Clients — MCP-Clients, Capture-SDKs, POST /api/v1/traces — Authorization: Bearer <key>. Um das Dashboard in einem Browser zu öffnen, hängen Sie den Schlüssel einmalig an eine beliebige Dashboard-URL an, http://localhost:6920/?key=<api key>: Iris tauscht ihn gegen ein HttpOnly-SameSite=Lax-Sitzungscookie aus und leitet zur selben Seite weiter, wobei der Schlüssel aus der Adressleiste entfernt wird. Eine ohne Sitzung geöffnete Seite zeigt ein Anmeldeformular an, das denselben Austausch durchführt. Der Schlüssel wird nie im Browser gespeichert, und Sitzungen bestehen nur im Serverprozess (höchstens 256 gleichzeitig; eine Anmeldung wird abgelehnt, wenn alle Sitzungsplätze belegt sind, statt eine Sitzung zu verdrängen).
Produktion
Mehrere Schlüssel und Rotation ohne Unterbrechung. security.apiKeys in config.json enthält beliebig viele weitere Schlüssel, jeweils mit einem id und genau einem von keyFile (eine Datei, deren getrimmter Inhalt der Schlüssel ist) oder keyHash (der sha256-Hexwert des Schlüssels, sodass die Konfigurationsdatei kein Geheimnis enthält — printf %s "$KEY" | openssl dgst -sha256), sowie optional einem expiresAt (ISO 8601), nach dessen Zeitpunkt der Schlüssel nicht mehr akzeptiert wird. Für eine Rotation: neuen Schlüssel hinzufügen, Clients umstellen, alten Schlüssel entfernen. Schlüssel in config.json und in Schlüsseldateien werden ohne Neustart wirksam (0.20.0): Bei jeder Anfrage prüft der Server, ob sich config.json oder eine darin angegebene Schlüsseldatei geändert hat, und liest die Schlüssel bei Bedarf vor der Antwort erneut ein. Wird ein Schlüssel aus security.apiKeys entfernt oder seine Schlüsseldatei gelöscht, wird er bei der nächsten Anfrage widerrufen: Diese Anfrage wird abgelehnt und alle mit diesem Schlüssel geöffneten Browsersitzungen werden abgemeldet. Ein config.json, das nicht gelesen werden kann (zum Beispiel, weil es nur teilweise geschrieben wurde), führt zu einer sicheren Ablehnung; bis zur Behebung wird nur ein Schlüssel aus IRIS_API_KEY oder --api-key akzeptiert. Der Schlüssel in IRIS_API_KEY oder --api-key selbst sowie die Aktivierung der Authentifizierung ändern sich weiterhin nur nach einem Neustart. Jeder Schlüssel authentifiziert sowohl über Bearer als auch bei der Browser-Anmeldung, bis er entfernt wird oder abläuft; das Startprotokoll nennt die IDs. security.rateLimit.mcpKeyBy: "apiKey" berechnet das Minutenbudget des MCP-Endpunkts pro Schlüssel statt pro Client-Adresse, sodass mehrere Agents hinter derselben Adresse jeweils ihr eigenes Minutenbudget erhalten.
Mehrere Clients. --transport http bedient beliebig viele MCP-Clients an einer Adresse: Jedes initialize öffnet eine eigene Sitzung über dieselbe Engine und denselben Speicher, bis zu 256 gleichzeitig. Bei stdio startet jeder Client einen eigenen Serverprozess; diese Prozesse teilen sich das Iris-Home-Verzeichnis: Eine über einen Client bereitgestellte, deaktivierte oder gelöschte Regel gilt innerhalb von 20 ms auch für alle anderen, ein über einen Client geschriebenes Label wird von den anderen ebenso schnell gelesen, und wenn zwei Clients gleichzeitig Regeln ändern, geht keine der Änderungen verloren.
Iris verweigert den Start, wenn der HTTP-Transport oder das Dashboard außerhalb von Loopback gebunden ist — 0.0.0.0, eine LAN-Adresse, ein Container — und kein API-Schlüssel vorhanden ist, und sagt dies in einem Satz, der IRIS_API_KEY nennt. Dazu gehört auch ein bloßes docker run des Images, das innerhalb des Containers an 0.0.0.0 bindet, weil Loopback über einen veröffentlichten Port nicht erreichbar ist. Loopback ohne Schlüssel funktioniert weiterhin (mit einer Warnung beim HTTP-Transport): Dort ist die Rechnergrenze die Zugriffskontrolle.
# The image: pass a key
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
-e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server
# Compose: the file requires the variable and refuses before the container starts
IRIS_API_KEY="$(openssl rand -hex 32)" docker compose up
# A network you have already fenced some other way: run open, on purpose
IRIS_ALLOW_UNAUTHENTICATED=1 iris-eval --transport http --dashboard
Standardmäßig offen auf einem Server mit Schlüssel: GET /health beim Transport und GET /api/v1/health beim Dashboard antworten ohne Schlüssel und außerhalb sämtlicher Ratenbegrenzungen in einem einheitlichen Format: Status, Version, Betriebszeit, der SQLite-Treiber, checks für den Speicher, die bereitgestellte Regeldatei und die Migrationen (angewendet im Vergleich zu den bekannten), der Zustand des Suchindex (search: bereit oder wie weit der Aufbau im Verhältnis zu den Traces fortgeschritten ist) und ob ein Judge-Schlüssel vorhanden ist — niemals der Schlüssel selbst, niemals ein Trace, niemals deren Anzahl. status ist nur dann ok, wenn alle Prüfungen erfolgreich sind; andernfalls ist es degraded mit HTTP 503, worauf das HEALTHCHECK des Docker-Images selbst prüft. Für alles andere ist Authorization: Bearer <key> oder eine Browsersitzung erforderlich. Die Aufbewahrungsbereinigung läuft auf jedem Server: Traces und Auswertungen, die älter als retention.days sind (Standardwert 30), werden beim Start gelöscht, sobald der Server Anfragen beantwortet, und danach alle retention.sweepIntervalHours in kurzen Schritten, die keine Anfrage lange warten lassen; --self-test gibt die Richtlinie dieser Installation aus, und iris://capabilities / GET /api/v1/capabilities übermitteln sie als retention.
Ein Webhook wird bei einem Ereignis ausgelöst (0.16.0): notify.webhook in config.json (oder IRIS_WEBHOOK_URL und IRIS_WEBHOOK_SECRET) benennt einen Empfänger, und Iris sendet eine signierte Nachricht, wenn ein Urteil fehlschlägt, eine kritische Erkennung ein Veto einlegt, Kosten ein Ausreißer sind, sich die Fehlerrate einer Regel ändert oder ein Fall zum ersten Mal auf beide Arten beantwortet wird — IDs, das Urteil, die Regeln und die Zahlen, niemals den Text des Agenten. Gleichzeitig nach den Standards von Standard Webhooks und GitHub signiert, mit Wiederholungsversuchen und Backoff, mit Abklingzeit pro Agent und Regel, ohne die Auswertung zu beeinträchtigen; Slack- und Discord-Nachrichten sind integriert. docs/webhooks.md.
Deine Daten auf dem Datenträger
Alles, was Iris speichert, befindet sich in deinem Iris-Home-Verzeichnis (~/.iris oder IRIS_HOME). iris.db speichert input und output jedes Traces unverändert — einschließlich aller Texte, die no_pii anschließend markiert; die Erkennung schwärzt nichts, sofern du sie nicht dazu aufforderst: storage.redact: "critical_spans" in config.json speichert die Ausgabe jeder Auswertung, wobei die von einem kritischen Detektor markierten Spans durch [REDACTED:<pattern>] ersetzt werden (standardmäßig deaktiviert; die Beweis-Offsets verweisen weiterhin auf den Text, den der Aufrufer gesehen hat). storage.synchronous legt fest, wann ein Schreibvorgang auf dem Datenträger landet: normal (Standardwert) synchronisiert das Write-Ahead-Log bei jedem Checkpoint. Bei einem Absturz von Iris geht dadurch nichts verloren und die Datei kann nicht beschädigt werden; ein Stromausfall oder ein Absturz des Betriebssystems kann jedoch Schreibvorgänge seit der letzten Synchronisierung rückgängig machen. full synchronisiert jeden Commit und erhält ihn auch bei beiden Ereignissen, bei etwa 1,5 ms zusätzlichem Aufwand pro Schreibvorgang. Beim Start und danach alle retention.sweepIntervalHours (Standardwert 24; 0 deaktiviert den Timer) werden Traces und Auswertungen gelöscht, die älter als retention.days sind (Standardwert 30; 0 deaktiviert die Bereinigung; festgelegt in config.json), und das Write-Ahead-Log wird per Checkpoint gesichert. Eine Sache bleibt über den Zeitraum hinaus erhalten: der angeheftete Baseline-Lauf samt seinen Auswertungen, da alle späteren Läufe mit ihm verglichen werden. Jeder Bereinigungslauf, der etwas davon zurückbehält, vermerkt dies im Log mit dem Lauf und den Anzahlen; hebe die Anheftung des Laufs auf, und der nächste Bereinigungslauf löscht ihn. Dataset-Fälle und Labels sind keine Traces oder Auswertungen und werden nicht bereinigt. Beim Löschen eines Traces — durch delete_trace oder durch die Bereinigung — wird der Text jeder damit verknüpften Auswertung gelöscht (die Ausgabe, der erwartete Text und die Regelmeldungen), und erased_at wird gesetzt; das Urteil, die Bewertungen und die Beweis-Offsets bleiben erhalten. Jeder Löschvorgang sichert das Write-Ahead-Log per Checkpoint, bevor er zurückkehrt, sodass der gelöschte Text in iris.db oder iris.db-wal nicht lesbar bleibt (wenn gerade eine Suche die Datei liest oder ein anderer Prozess sie liest oder beschreibt, kehrt der Löschvorgang ohne Warten zurück, und der Text wird aus der Datei entfernt, sobald der Vorgang abgeschlossen ist). Um jetzt alles zu entfernen, stoppe den Server und führe --purge aus: Dadurch werden alle gespeicherten Traces, Spans und Auswertungen gelöscht, die Datenbank kompaktiert und das Write-Ahead-Log gekürzt, sodass der Text vom Datenträger entfernt ist; bereitgestellte Regeln, Audit-Log und Einstellungen bleiben erhalten. Bevor ein Release eine Migration auf ein vorhandenes iris.db anwendet, erstellt es eine Kopie daneben (iris.db.<from>-to-<to>.<time>.bak, nur für den Eigentümer zugänglich; die drei neuesten bleiben erhalten; Downgrading): Die Kopie enthält die Traces im ursprünglichen Zustand, daher löscht die Aufbewahrungsbereinigung alle, die älter als retention.days sind, und --purge löscht sie alle. Der Server erstellt die Kopie und führt die Migrationen aus, nachdem er seinem Client geantwortet hat, auf einem eigenen Thread: Tool-Aufrufe, Ressourcenlesevorgänge und HTTP-Anfragen, die währenddessen eintreffen, warten jeweils höchstens 30 s und werden dann mit einem Satz abgewiesen, der erklärt, was der Server gerade tut (IRIS_STORAGE_ERROR, wiederholbar; HTTP 503 mit Retry-After). Die Health-Abfrage antwortet währenddessen weiterhin und gibt an, was das Upgrade gerade tut. Bei 100.000 Traces, die jeweils eine Agentenschleife darstellen, dauerten die Kopie und die Migrationen ab Version 0.19.0 etwa 6 s. iris-eval ingest, --purge und --self-test führen das Upgrade weiterhin durch, bevor sie irgendetwas anderes tun.
Iris verschlüsselt seine Daten nicht im Ruhezustand. iris.db und die Write-Ahead-Log-Dateien werden nur für den Eigentümer zugänglich erstellt (Modus 600), und das Iris-Home-Verzeichnis wird mit Modus 700 erstellt (unter Windows gelten stattdessen Dateiberechtigungen). Die Datenbank speichert keine LLM-Anbieterschlüssel: IRIS_ANTHROPIC_API_KEY und IRIS_OPENAI_API_KEY werden aus der Umgebung gelesen und niemals auf dem Datenträger gespeichert. Trace-Eingaben und -Ausgaben werden jedoch unverändert gespeichert. Lege das Iris-Home-Verzeichnis daher auf einem verschlüsselten Datenträger oder Volume ab (FileVault, BitLocker, LUKS oder ein verschlüsseltes Cloud-Volume für den /data-Mount des Docker-Images).
Ein Export — über die Schaltfläche Export auf den Dashboard-Seiten „Traces“ und „Evaluations“, GET /api/v1/traces/export und /api/v1/evaluations/export oder iris-eval export — enthält den gespeicherten Text unverändert, genau wie ihn das Dashboard anzeigt: Trace-Eingabe und -Ausgabe unverändert, Auswertungsausgabe mit angewendetem storage.redact. Behandle eine exportierte Datei wie die Datenbank, aus der sie stammt.
Fehlerbehebung
Erster Schritt: Selbsttest ausführen
npx @iris-eval/mcp-server --self-test
Dabei werden der Speicher, die deterministischen Auswertungen und das Dashboard in einem isolierten temporären Home-Verzeichnis geprüft und die Ergebnisse für jeden Schritt ausgegeben — die Fehlerausgabe nennt den fehlerhaften Schritt. Exit-Code 0 bedeutet, dass die Installation fehlerfrei ist.
Iris startet nicht / ERR_MODULE_NOT_FOUND
Möglicherweise ist eine ältere Version im Cache. Leere den npx-Cache und versuche es erneut:
npx --yes @iris-eval/mcp-server@latest
Oder installiere das Paket global, um Cache-Probleme vollständig zu vermeiden:
npm install -g @iris-eval/mcp-server@latest
npm install --ignore-scripts hat die SQLite-Bindung beschädigt
Iris speichert Traces mit better-sqlite3, einem nativen Modul, das seine Bindung während eines Installationsskripts herunterlädt oder kompiliert. Wenn dieses Skript übersprungen wurde — --ignore-scripts in der Befehlszeile, ignore-scripts=true in einem .npmrc (häufig auf Unternehmensrechnern) oder ein Registry-Spiegel, der Postinstall-Skripte entfernt — schlägt der Start mit einer langen Ausgabe „Could not locate the bindings file“ fehl, in der ein Dutzend versuchter Pfade aufgelistet sind. Erstelle dieses eine Modul neu:
npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3
Tools werden in Claude Code nicht angezeigt
MCP-Tools werden nur beim Sitzungsstart geladen. Starte nach dem Hinzufügen von iris-eval die Sitzung mit /clear neu oder starte das Terminal erneut.
Versionsprüfung
npx @iris-eval/mcp-server --version
Auch die erste Startprotokollzeile enthält die Version (Starting Iris MCP server vX.Y.Z), und --self-test gibt sie in seiner Zusammenfassung aus. Bei einer globalen Installation zeigt npm ls -g @iris-eval/mcp-server die installierte Version an.
Aktualisieren
Alle MCP-Clients auf einem Rechner verwenden dieselbe Datenbank, ~/.iris/iris.db, und install bindet jeden Client an das Release, das seine Konfiguration geschrieben hat. Wenn ein Release das Schema der Datenbank ändert, aktualisiert der erste Prozess dieses Releases, der die Datei öffnet, das Schema. Danach verweigert ein Client, der weiterhin an ein älteres Release gebunden ist, den Start. Aktualisiere daher alle Clients in einem Schritt, bevor oder direkt nachdem du das Upgrade durchführst:
npx -y @iris-eval/mcp-server@latest install --upgrade
Der Befehl findet alle Client-Konfigurationen auf diesem Rechner, die Iris ausführen, und aktualisiert jede Bindung auf dieses Release (wobei alle Ergänzungen am Eintrag erhalten bleiben, etwa --dashboard oder ein env-Block). Eine Bindung an ein neueres Release und Einträge, die etwas anderes als das npm-Paket ausführen, bleiben unverändert. Der Befehl listet auf, was er getan hat. Starte die genannten Clients neu. install --list zeigt, welche Iris-Version jeder Client ausführt.
Zwei Installationen befinden sich außerhalb dieser Dateien: Die Claude-Desktop-Erweiterung (iris-eval.mcpb) wird aktualisiert, wenn du ein neueres Bundle öffnest, und die Claude-Code-Plugins mit claude plugin marketplace update iris-eval und anschließend claude plugin update iris-eval@iris-eval (sowie claude plugin update iris-eval-capture@iris-eval für das Capture-Plugin).
Upgrade von 0.19.x auf 0.20.0. 0.20.0 ergänzt den Suchindex und weitere Funktionen in der Datenbank (Migrationen 015 und höher). Sobald ein Prozess mit 0.20.0 ~/.iris/iris.db geöffnet hat (die Claude-Desktop-Erweiterung, npx iris-eval oder npx @iris-eval/mcp-server ohne Versionsangabe), wird ein an 0.19.x gebundener Client mit This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, … beendet. Diese Meldung stammt von 0.19.x und kann nicht geändert werden; die Lösung ist der obige Befehl. Vor dem Upgrade erstellt 0.20.0 eine Kopie der Datei daneben, sodass auch ein Zurückwechseln möglich ist (siehe unten).
Ein Start, bei dem die Datenbank aktualisiert wird, gibt auf stderr aus, was geschehen ist: die erstellte Kopie, welche älteren Releases die Datei nicht mehr öffnen können und alle Clients auf diesem Rechner, die an eines davon gebunden sind, einschließlich des Befehls. --self-test liest die Datenbank, ohne sie zu ändern, und gibt dieselben Informationen aus, bevor du irgendetwas startest.
Bei einer globalen Installation: npm update -g @iris-eval/mcp-server, dann iris-eval install --upgrade.
Downgrade
Ein Release, das die Datenbank aktualisiert, erstellt zuerst eine Kopie daneben: iris.db.<from>-to-<to>.<time>.bak in deinem Iris-Home-Verzeichnis (<from> ist das Release, das das Schema der Datei zuletzt geändert hat; <to> das Release, das sie aktualisiert hat; die Startzeile enthält den genauen Pfad). So wechselst du zurück:
- Stoppe alle MCP-Clients und alle anderen Iris-Prozesse, die die Datenbank verwenden.
- Bewahre die aktualisierte Datei auf, falls du zurückwechseln möchtest: Benenne
iris.dbiniris.db.upgradedum und löscheiris.db-walundiris.db-shm, falls vorhanden. - Kopiere die Sicherung nach
iris.db:cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db. - Binde jeden Client wieder an das ältere Release:
npx -y @iris-eval/mcp-server@0.19.0 install <client>für jeden Client (install --upgradesetzt keinen Client auf eine ältere Version zurück).
Traces, die nach dem Upgrade gespeichert wurden, befinden sich in iris.db.upgraded, nicht in der Sicherung. Wenn keine Kopie erstellt wurde (in der Startzeile steht der Grund, zum Beispiel ein voller Datenträger), kann das ältere Release die aktualisierte Datei nicht öffnen. In diesem Fall bleibt nur install --upgrade.
Der Speichertreiber
Auf einer Plattform ohne vorgefertigtes better-sqlite3 ist die Installation trotzdem erfolgreich. better-sqlite3 ist eine optionale Abhängigkeit: Wenn npm weder eine vorgefertigte Binärdatei für deine Node-Version und Plattform herunterladen noch eine kompilieren kann (zum Kompilieren sind Python und eine C++-Toolchain erforderlich — unter Windows die C++-Buildtools von Visual Studio), gibt npm den Build-Fehler aus, überspringt das Modul und schließt die Installation ab. Iris läuft dann mit dem integrierten SQLite von Node und weist darauf hin: Beim Start wird auf stderr eine Zeile mit dem Grund ausgegeben, und --self-test zeigt driver node: better-sqlite3 is not installed …. Um den nativen Treiber wieder zu verwenden, installiere ihn dort, wo ein vorgefertigtes Paket oder eine Toolchain verfügbar ist (npm install better-sqlite3 im Projekt; bei einer globalen Installation installiere Iris erneut mit npm install -g @iris-eval/mcp-server, sobald eine Toolchain verfügbar ist). CI installiert bei jeder Änderung den gepackten Server mit erzwungenem Fehlschlag des nativen Builds und verlangt, dass die Installation abgeschlossen wird und der Selbsttest einen Trace mit dem integrierten Treiber speichert und liest.
Iris speichert alles in einer einzigen SQLite-Datei, die von better-sqlite3 geöffnet wird — einem nativen Add-on, das für deine Node-Version und Plattform heruntergeladen oder kompiliert wird. Wenn dieses Modul nicht geladen werden kann, greift Iris mit einer Warnung auf stderr auf das integrierte SQLite von Node zurück (node:sqlite, Node 22.13 oder neuer). Ein fehlendes Prebuild führt also zu einem langsameren Start statt zu einem fehlgeschlagenen. Dasselbe gilt, bevor es geladen wird, für ein better-sqlite3, das auf deinem Rechner mit Node-24.19- oder neueren Headern kompiliert und unter Node 24.19 bis 24.21 ausgeführt wird: Dort bricht eine solche Binärdatei den gesamten Prozess beim ersten Freigeben eines Statements ab (Assertion failed: (env) != nullptr, nodejs/node#65446). Node 24.22.0 enthält die Fehlerbehebung, und Iris lädt die Binärdatei dort. npm rebuild better-sqlite3 ersetzt sie durch die vorgefertigte Binärdatei, die in allen Versionen sicher ist. IRIS_SQLITE_DRIVER=node wählt absichtlich das integrierte Modul, native verbietet den Fallback. Das integrierte Modul wird mit deaktiviertem Laden von Erweiterungen und deaktiviertem trusted_schema geöffnet; Node gibt beim Laden eine eigene ExperimentalWarning: SQLite is an experimental feature-Zeile auf stderr aus, die Iris nicht unterdrückt. --self-test und GET /health geben den verwendeten Treiber an; alle Zahlen auf der Nachweisseite wurden mit dem nativen Treiber gemessen, und die Testsuite läuft in CI mit beiden.
Node.js-Version
Iris erfordert Node.js 22.13 oder neuer. Node 20 erreichte am 2026-04-30 das Ende seiner Lebensdauer und wird nicht unterstützt; Node 18 endete im April 2025.
Die Mindestversion ist 22.13 statt 22.0, weil 22.13.0 die erste Version ist, die node:sqlite enthält. Damit ist es die erste Version, in der jede unterstützte Iris-Installation über einen zweiten Speichertreiber verfügt: Wenn das native better-sqlite3-Add-on nicht geladen werden kann, greift Iris auf das integrierte SQLite von Node zurück, statt den Start abzubrechen. Vor 22.13 — und während seiner gesamten Lebensdauer unter Node 20 — gab es immer nur einen Treiber, und ein fehlendes Prebuild verhinderte den Start.
node --version # Must be v22.13.0 or newer
Windows: cmd /c nicht erforderlich
Claude Codes /doctor schlägt möglicherweise vor, npx mit cmd /c zu umschließen. Das ist nicht erforderlich und verursacht Probleme bei der Pfadverarbeitung. Verwende direkt npx:
# Correct
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx -y @iris-eval/mcp-server"
Wenn Iris für dich nützlich ist, kannst du das Repo mit einem Stern versehen — so finden es auch andere leichter.
Unter MIT-Lizenz.