Iris
официальныйMCP-нативный сервер для оценки агентов и наблюдаемости с трассировкой логов, оценкой качества вывода, отслеживанием затрат, 12 встроенными правилами оценки, панелью мониторинга в реальном времени и обнаружением PII
Что можно делать с Iris MCP?
- Записывайте и оценивайте запуски — Попросите ассистента записать запуск агента в Iris и оценить его результат, а затем посмотрите вердикт и оценки на панели мониторинга.
- Проверяйте правила безопасности и стоимости — Запускайте 28 встроенных детерминированных правил для выявления персональных данных, внедрения промптов, маркеров галлюцинаций и превышения порогов стоимости без вызовов LLM.
- Изучайте и редактируйте правила — Просматривайте список встроенных правил и проверяйте или изменяйте их: каждое правило можно изучить и отредактировать.
- Добавляйте собственные правила — Загружайте написанные вами правила через
eval.pluginsвconfig.json, закрепив их за хешем файла. - Сравнивайте запуски — Открывайте два запуска с одинаковыми вопросами рядом друг с другом с интервалом в представлении Runs на панели мониторинга.
- Блокируйте CI по вердиктам — Запускайте
ingestс параметрами--evaluate --fail-on any, чтобы завершать задание с ошибкой при любом вердикте, отличном от «пройдено».
Документация
Iris — хватит выпускать агентов на авось
Отправьте Iris запуск агента и попросите оценить его качество, безопасность и стоимость — на вашем компьютере, без SDK и учётной записи. В большинстве проектов с агентами качество проверяют, запуская несколько запомнившихся запросов и оценивая результат на глаз. Iris заменяет это проверяемыми числами: запуски вашего агента сохраняются в базе данных SQLite на вашем диске, а 28 встроенных правил детерминированно оценивают их — персональные данные, внедрение промптов, маркеры галлюцинаций, пороговые значения стоимости и собственные вызовы инструментов агента. Всё это бесплатно и без вызовов LLM; для семантических вопросов можно дополнительно подключить судью на базе LLM с жёстким ограничением стоимости каждой оценки. Каждое правило можно проверить и изменить: судья, которого нельзя проверить, — это просто авось с числом. Лицензия MIT, телеметрии нет. Ничего не покидает ваш компьютер, если вы сами не включите один из вариантов: конечную точку OpenTelemetry (IRIS_OTEL_ENDPOINT), которая экспортирует трассировки в указанный вами коллектор; судью на базе LLM с вашим собственным ключом, который отправляет оцениваемый текст этому провайдеру, а также проверяет цитаты, загружая страницы, на которые ссылается результат; или вебхук, который отправляет на заданный вами адрес идентификаторы, вердикт и названия правил, но никогда не текст.
Требуется Node.js версии 22.13 или новее. Проверьте командой node --version.

Демонстрационная база данных, записанная с помощью scripts/demo-media.mts; исходный код — demo.mp4. Кадр: dashboard-overview.png.
Сбой на экране за 60 секунд
Без настройки агента и конфигурации — одна команда:
npx @iris-eval/mcp-server --demo
Она создаёт демонстрационную базу данных — пять небольших агентов, две недели запусков и вердикты, полученные самим движком, — и открывает панель управления с этими данными по адресу http://localhost:6920 (при первом запуске браузер откроется автоматически). Панель открывается на странице «Сбои»: сначала показаны самые серьёзные и самые свежие сбои, а на каждой карточке указаны правило и подтверждающие данные. Стоит заглянуть внутрь: утечка персональных данных, обнаруженная правилами безопасности; скрытая инструкция в публикации на форуме, которой подчинился суммаризатор; число, которого не было в исходном документе; сравнение двух запусков на одних и тех же двенадцати вопросах с интервалом («Запуски»); развёрнутое пользовательское правило и приостановленное правило с записями аудита; а также неудачная оценка судьи на базе LLM с обоснованием.
Демонстрационные данные хранятся в отдельной базе данных (demo.db в домашнем каталоге Iris — ~/.iris в macOS/Linux, %USERPROFILE%\.iris в Windows) и никогда не смешиваются с вашими реальными трассировками. Удалите их одной командой:
npx @iris-eval/mcp-server --demo-clear
Подключите собственного агента
Сначала убедитесь, что установка работает на этом компьютере: проверка выполняется офлайн и не открывает ваши данные:
npx @iris-eval/mcp-server --self-test # exit 0 = healthy
Затем добавьте Iris в MCP-клиент. Одна команда изменит собственный файл конфигурации клиента, сохранит все остальные серверы и зафиксирует версию, которую вы запустили:
npx -y @iris-eval/mcp-server install claude-code
Клиенты: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. Команда install --list показывает, какие клиенты найдены на этом компьютере, какую версию Iris запускает каждый из них и какой файл читает; команда install <client> --uninstall удаляет Iris. Все клиенты используют одну базу данных, поэтому после обновления обновите их все сразу командой install --upgrade (Обновление). Перезапустите клиент, чтобы загрузить Iris.
Claude Desktop: установка одним щелчком. В каждом выпуске начиная с версии 0.20.0 прилагается iris-eval.mcpb — пакет MCP: скачайте последнюю версию, откройте её, и Claude Desktop покажет диалог установки. Ничего в нём не обязательно: ключ Anthropic или OpenAI для судьи на базе LLM необязателен, а панель управления по умолчанию выключена. Пакет содержит npm-пакет и его зависимости, поэтому устанавливать больше ничего не нужно: Claude Desktop запускает Iris с помощью поставляемой вместе с ним версии Node, если она не ниже 22.13 (в Claude Desktop 1.1.6679 поставляется версия 24.13), а Iris хранит трассировки во встроенной в Node базе данных SQLite, в том же ~/.iris, что и все остальные варианты установки. В примечаниях к выпуску описано, как проверить подпись и аттестацию сборки.
Iris работает в любом MCP-клиенте, и для каждого указанного клиента есть строка с описанием проверки. Проверено при каждом запуске CI: Claude Code, Gemini CLI — настоящий клиент запускает Iris из конфигурации, созданной установщиком, и сообщает об успешном подключении (claude mcp list, gemini mcp list) в Linux, macOS и Windows; хуки плагина захвата Claude Code также проверяются с помощью настоящих скриптов. Настроено по собственной документации каждого клиента для MCP — установщик записывает файл, описанный в документации клиента, по указанному там пути и в нужном формате (блок mcpServers, servers в VS Code, context_servers в Zed, TOML в Codex), сохраняя комментарии и все остальные серверы; модульные тесты проверяют каждый путь и каждый формат записи по этой документации: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Для каждой строки указаны источник и дата проверки: https://iris-eval.com/clients. Если предпочитаете настроить вручную, добавьте один блок, включая панель управления:
{
"mcpServers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
}
}
}
При подключении клиент покажет двенадцать инструментов Iris, а панель управления будет доступна по адресу http://localhost:6920. Теперь отправьте агенту такой запрос:
Запиши последнее задание в Iris и оцени результат.
Трассировка появится на панели управления вместе с оценками. Если предпочитаете запускать MCP-сервер без графического интерфейса, удалите --dashboard из аргументов — в любой момент можно открыть ту же панель командой npx @iris-eval/mcp-server --dashboard.
Важно знать заранее: MCP-инструменты вызываются, когда модель решает их вызвать. Iris не перехватывает работу агента, поэтому трассировки записываются, когда агент просит Iris их записать: либо по вашей просьбе, либо когда ваш код напрямую вызывает инструменты. Попросите агента «записать это в Iris и оценить» — и он это сделает. Если вам нужен захват, не зависящий от решения модели, POST /api/v1/traces делает именно это: ваш код отправляет трассировку по обычному HTTP, без участия модели (см. docs/http-ingest.md). CLI и хуки хоста из плана развития будут лёгкими клиентами той же конечной точки.
Захват по HTTP (без участия модели)
Конечная точка приёма данных работает на порту панели управления — по умолчанию 6920, а не на порту транспорта MCP — и доступна только во время работы панели. Передайте --dashboard (или задайте IRIS_DASHBOARD=true); сам по себе --transport http не запускает её, а запрос к порту транспорта возвращает 404. Когда панель запущена, любое приложение, способное отправлять HTTP-запросы, может записать трассировку и при желании выполнить детерминированные оценки в том же запросе. GET /api/v1/capabilities на том же порту сообщает, что именно может оценивать этот сервер, что требуется каждому правилу, в каком состоянии находится судья и какие шаги нужны для его включения, а также какие действуют ограничения. Это тот же объект, который предоставляет ресурс MCP iris://capabilities, поэтому HTTP-клиент получает те же исходные сведения, что и MCP-клиент при инициализации:
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"
}'
Возвращает 201 с сохранённым trace_id и результатом оценки (в режиме --demo конечная точка отклоняет запись с ошибкой 403, чтобы демонстрационные данные никогда не смешивались с вашими). Конечная точка принимает то же тело запроса, что и инструмент log_trace, и проходит через тот же стек промежуточного ПО, что и остальная часть панели управления: по умолчанию привязка к loopback и защита от DNS rebinding, а также Bearer-аутентификация, если вы её настроили. Два простых факта: конечная точка принимает запросы на запись без аутентификации, если Iris запущен без --api-key (или IRIS_API_KEY). По умолчанию доступ с вашего компьютера обеспечивает привязка к loopback, поэтому перед привязкой за пределами loopback задайте ключ. Кроме того, данные сохраняются без изменений: input и output попадают в iris.db именно в том виде, в каком были отправлены, включая любой текст, который no_pii впоследствии пометит. Полное описание контракта, полей и семантики ошибок: docs/http-ingest.md.
Захват каждого хода Claude Code (необязательно)
/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval
Отдельный плагин, устанавливаемый независимо: его хуки записывают промпт каждого хода, вызовы инструментов (включая неудачные, вместе с полученной агентом ошибкой) и итоговый ответ, связывая их по промпту. Поэтому отправляются и вызовы прерванного хода, и вызовы фонового субагента. Затем данные передаются в iris-eval ingest в фоновом режиме, а критические фрагменты удаляются из текста, сохраняемого для оценки. Такой захват не зависит от решения модели вызвать инструмент. Ход, завершившийся ошибкой API, сохраняется без оценки; если модель также записала этот ход, сохраняются обе трассировки, а трассировка плагина помечается как созданная плагином, а не моделью. Плагин ничего не выводит, не блокирует работу и ничего никуда не отправляет. Одна лишь установка iris-eval никак не меняет цикл выполнения ходов. Ограничения и удаление: 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": []}
Лёгкий клиент для HTTP API сервера версии 0.16.0 и новее, версионируемый отдельно: номер версии указан в iris_eval.__version__ и на странице PyPI и не совпадает с версией сервера: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), синхронный и асинхронный режимы, типизированные ответы, собственное сообщение сервера при отказе, а также плагин pytest: фикстура iris и assert_iris(output, expect="pass"), проверяющий состояние вердикта. packages/python/README.md.
Запись каждого вызова OpenAI и Anthropic
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' });
Достаточно один раз обернуть клиент провайдера: каждый вызов модели станет одним спаном OpenTelemetry GenAI, отправленным на конечную точку OTLP, сохранённым вместе с входными и выходными данными, использованием токенов и вызовами инструментов, а затем оценённым. Такой захват не зависит от того, вызывает ли модель инструмент. wrap_openai / wrap_anthropic в клиенте Python; wrapOpenAI, wrapAnthropic и irisMiddleware для Vercel AI SDK в @iris-eval/sdk. Оба пакета пока не опубликованы (следующий выпуск iris-eval на PyPI; @iris-eval/sdk собирается из исходного кода до первого выпуска в npm). Поддерживаются потоки, вспомогательные функции потоковой передачи SDK и вызовы инструментов; исходный клиент не изменяется, а сбой Iris никогда не прерывает вызов. packages/sdk/README.md, packages/python/README.md.
Оценка каждого запуска LangChain и LangGraph
from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})
Каждый запуск верхнего уровня становится одной трассировкой (сам запуск, вызовы модели, вызовы инструментов и узлы графа в виде спанов GenAI) с входными и выходными данными, вызовами инструментов, использованием токенов и вердиктом. Python-клиент (pip install iris-eval, версия 0.2.0 и новее), JavaScript — как @iris-eval/langchain (в этом репозитории, пока не опубликован в npm). Оба варианта проверяются в CI на настоящем приложении LangGraph со скриптовой моделью; собственный экспорт OpenTelemetry из LangSmith проверяется так же. docs/otel-recipes.md.
Проверка в CI без сервера
npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any
any завершает задание с ошибкой при любом вердикте, который не является успешным: как при сбое, так и при отсутствии проверки. Чтобы завершать задание с ошибкой только для одного основания, укажите вместо этого --fail-on detector_veto.
Или используйте GitHub Action (0.16.0): она завершает задание с ошибкой для указанных вами вердиктов, записывает отчёт в сводку задания и публикует его одним комментарием к pull request, обновляя существующий комментарий: uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 с traces: traces.ndjson — docs/ci-gate.md.
Четвёртая дверь (0.15.0): POST /v1/traces на порту дашборда принимает OTLP/HTTP JSON или protobuf, которые уже отправляет ваша инструментация OpenTelemetry (экспортёр Python SDK поддерживает только protobuf, поэтому это также дверь для Python), и каждый OTLP-трейс становится трейcом Iris со своими спанами — docs/otel-integration.md; по одному рецепту для каждого фреймворка (Pydantic AI, Google ADK, LangGraph через LangSmith, CrewAI, OpenAI Agents SDK для Python и JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK и Mastra), каждый подтверждён фикстурой, в docs/otel-recipes.md. ingest читает один JSON-трейс (или NDJSON, по одному на строку) из stdin или файла, сохраняет его, оценивает по тем же правилам, что и evaluate_output, выводит одну строку JSON на каждый трейс с вердиктом и его обоснованием и завершает работу с кодом 1, если вердикт соответствует --fail-on. --dataset <id|label> ограничивает эту проверку ключами случаев из набора данных (POST /api/v1/datasets переносит ключи случаев запуска в набор), поэтому задание завершается ошибкой только для выбранных вами случаев. Полный рецепт, коды завершения и восемь оснований приведены в docs/ci-gate.md.
Напишите правило в виде кода
eval.plugins в config.json загружает написанные вами правила — ES-модуль, экспортирующий по умолчанию { name, kind, mechanism, version, needs, evaluate(ctx) }, — закреплённые по sha256 файла, поэтому при изменении файла после закрепления запуск будет отклонён, а не выполнен. Загруженный плагин срабатывает как встроенное правило и отображается в list_rules в разделе plugins. Контракт, способ вычисления хеша и допустимые возвращаемые значения плагина: docs/plugins.md.
Используйте движок в собственном процессе
Движок оценки можно импортировать — без сервера, базы данных и модели:
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
Тот же движок, те же правила и тот же компоновщик, что использует сервер; рядом с ним экспортируются builtInRules(), createCustomRule(), compose() и средства чтения опубликованной точности.
Типизированный клиент для HTTP-маршрута
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
Единое тело запроса для всех дверей: его принимают log_trace и iris-eval ingest. При отказе выбрасывается IrisClientError с формулировкой и статусом самого сервера. Обе подпути проверяются из упакованного tarball при каждой сборке.
Проверьте установку
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 сначала создаёт домашний каталог Iris, если он отсутствует, и проверяет, доступна ли запись (если нет — завершает работу с кодом 1 и указывает путь), сообщает состояние поискового индекса базы данных (полностью построен, сколько трейсов фоновая сборка уже проиндексировала или отсутствие FTS5 в этой SQLite), читает схему базы данных (если эту версию или MCP-клиент, закреплённый на более старом выпуске, нельзя открыть, завершает работу с кодом 1 и указывает способ исправления), а затем выполняет проверки — круговой проход хранилища, обнаружение тестовых SSN и инъекции правилами безопасности, запуск дашборда и защиту от DNS-rebinding — в изолированном временном домашнем каталоге. Ваша настоящая база данных только читается, но не изменяется. Всё, что записывает Iris, хранится в одном каталоге — вашем домашнем каталоге Iris: по умолчанию ~/.iris (%USERPROFILE%\.iris в Windows) или в каталоге, указанном IRIS_HOME. Там находятся iris.db, config.json, custom-rules.json, audit.log, preferences.json и демонстрационные файлы; укажите для IRIS_HOME временный каталог, чтобы попробовать Iris, не затрагивая настоящие данные.
Настройка средствами клиента
| Клиент | Статус | Что это означает | Читать |
|---|---|---|---|
| Claude Code | проверен | тест запускает настоящий клиент при каждом запуске CI | 2026-09-25 |
| Claude Desktop | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Cursor | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Devin Desktop (Windsurf) | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Continue | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| VS Code | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Cline | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Zed | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| OpenAI Codex CLI | заявлен | настроен по собственной документации MCP клиента; путь и формат установщика проверяются модульными тестами | 2026-09-25 |
| Gemini CLI | проверен | тест запускает настоящий клиент при каждом запуске CI | 2026-09-25 |
Для каждой строки указано, что именно проверялось: iris-eval.com/clients. Клиент не называется поддерживаемым, если его нет в таблице.
npx -y @iris-eval/mcp-server install <client> создаёт всё это за вас. Вручную, для каждого клиента:
Claude Desktop
Отредактируйте файл конфигурации MCP:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Добавьте приведённую выше конфигурацию JSON, затем перезапустите Claude Desktop.
Claude Code
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
Затем перезапустите сеанс (/clear или запустите заново), чтобы загрузились инструменты.
Примечание для Windows: не используйте обёртку
cmd /c— она вызывает проблемы при разборе путей. Командаnpxработает напрямую.
Cursor
Добавьте приведённую выше конфигурацию JSON в ~/.cursor/mcp.json (для всех проектов) или .cursor/mcp.json в рабочей области, указав "type": "stdio" в записи iris-eval — документация Cursor помечает это поле как обязательное.
Devin Desktop (Windsurf)
Добавьте приведённую выше конфигурацию JSON в mcp_config.json: ~/.config/devin/mcp_config.json в macOS и Linux, %APPDATA%\devin\mcp_config.json в Windows.
Continue
Сохраните приведённую выше конфигурацию JSON в отдельном файле в каталоге mcpServers приложения Continue: ~/.continue/mcpServers/iris-eval.json (для каждой рабочей области) или .continue/mcpServers/iris-eval.json в одной из них.
VS Code (встроенная поддержка MCP)
Добавьте в .vscode/mcp.json рабочей области (обратите внимание: VS Code использует servers, а не mcpServers):
{
"servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"]
}
}
}
Cline
Откройте панель MCP Servers в Cline → Configure MCP Servers и добавьте приведённую выше конфигурацию JSON mcpServers в cline_mcp_settings.json (~/.cline/data/settings/cline_mcp_settings.json, общий для Cline в VS Code, JetBrains и CLI).
Zed
Добавьте в settings.json Zed:
{
"context_servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"],
"env": {}
}
}
}
OpenAI Codex CLI
Добавьте в ~/.codex/config.toml:
[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]
Gemini CLI
Добавьте приведённую выше конфигурацию JSON mcpServers в ~/.gemini/settings.json. Gemini CLI подключается к MCP-серверам только в доверенных папках: если gemini mcp list показывает, что iris-eval отключён, выполните /permissions в этой папке.
Любой другой клиент с поддержкой MCP
Iris — стандартный MCP-сервер stdio: одна команда npx @iris-eval/mcp-server, без SDK и изменений кода. Если ваш клиент поддерживает MCP, он поддерживает и Iris. Форматы конфигурации клиентов меняются; если сомневаетесь, обратитесь к документации MCP вашего клиента и укажите эту команду.
Другие способы установки
# 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
Совет: глобальная установка (
npm install -g) постоянно хранит трейсы в~/.iris/iris.db. При использованииnpxтрейсы сохраняются там же, но запуск происходит медленнее из-за разрешения пакетов.
Образ контейнера и каталоги MCP, в которых указан Iris:
Что вы получаете
| Журналирование трейсов | Иерархические деревья спанов с задержкой каждого вызова инструмента, использованием токенов и стоимостью в USD. Хранятся в SQLite и доступны для мгновенных запросов. |
| Оценка выходных данных | 28 встроенных правил в 4 категориях: полнота, релевантность, безопасность, стоимость. Обнаружение PII (21 шаблон: SSN, кредитная карта, телефон, электронная почта, IBAN, дата рождения, MRN, IP, API-ключ, паспорт, а также токены AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean, учётные данные внутри URL, присваивания с именами секретов, блоки закрытых ключей PEM и сид-фразы; дата рождения, медицинский номер, паспорт и сид-фраза срабатывают только рядом со своей меткой, так задумано), инъекция промпта (38 шаблонов: фразы и структурные признаки), обнаружение заглушек в выходных данных, обнаружение галлюцинаций (25 сигналов фабрикации/противоречия с учётом контекста — передайте input, чтобы сопоставить их с исходными материалами агента) и шесть правил траектории, анализирующих, что агент СДЕЛАЛ: неотмеченный неудачный вызов инструмента, повторный вызов (по вызову, повторяющейся последовательности или цели после передачи tools), вызов с аргументами, не соответствующими собственной JSON Schema инструмента, который агент не повторил, файл, каталог или URL, указанный в ответе, но отсутствующий во всём, что прочитал агент, инструкция, поступившая внутри РЕЗУЛЬТАТА ИНСТРУМЕНТА и затем выполненная в более позднем вызове, а также задача, для которой потребовалось больше вызовов инструментов, чем допускает бюджет шагов. Ещё два правила сравнивают запуск с предыдущими запусками того же случая тем же агентом, не требуя от кого-либо задавать ожидаемое поведение: действие, которого не было ни в одном предыдущем запуске, и шаг, который был во всех предыдущих запусках, но отсутствует в этом. Траектория может поступать как tool_calls или как спаны TOOL в OpenTelemetry. Добавляйте собственные правила с помощью схем Zod. |
| LLM-судья | Необязательная семантическая оценка через Anthropic или OpenAI — используйте собственный API-ключ. Семь шаблонов. Если задан IRIS_RELEVANCE_JUDGE_MODEL, answers_the_ask обращается к судье relevance и отклоняет ответ не по теме; без него правило анализирует запрос лексически и выдаёт рекомендации. Жёсткий лимит стоимости на одну оценку (IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL, по умолчанию $0.25), стоимость каждой оценки указывается в результате. |
| Контроль стоимости | Совокупная стоимость всех агентов за любой период времени. Устанавливайте пороговые значения бюджета. Получайте предупреждения о перерасходе агентами. Трейс, в котором указаны количество токенов и модель, но не стоимость (как в большинстве трейсов OpenTelemetry и фреймворков), оценивается по прейскурантной цене модели и везде помечается как приблизительный; pricing.models в config.json задаёт цены моделей, отсутствующих во встроенной таблице, — docs/cost.md. |
| Веб-дашборд | Тёмный интерфейс с обновлением в реальном времени, который сначала показывает сбои, начиная с самых серьёзных и новых, — визуализация трейсов с полнотекстовым поиском по тексту всех трейсов, результатам оценок, разбивке стоимости и командной палитре (⌘K) для поиска собственных правил, трейсов и оценок. |
| Локальное хранение | Всё хранится в SQLite на вашем диске. Для самостоятельно размещённого сервера не нужны учётная запись или регистрация, телеметрия не отправляется. Исходящие HTTP-запросы выполняются только при вашем согласии: с собственным ключом LLM-судьи, для получения цитат, через настроенный вами экспортёр OTel или заданный вами вебхук. |
Что дальше: карта возможностей — все вопросы, которые можно задать Iris о каждом объекте, с указанием того, что доступно и чего не хватает, — и три направления.
Измерено, а не заявлено
У каждого встроенного правила опубликованы точность, полнота и F1 с 95%-ными доверительными интервалами. Они измерены на размеченном корпусе, который хранится в этом репозитории (proof/corpus/) и пересоздаётся одной командой — npm run proof — офлайн, без ключа и без участия модели. Эти показатели относятся к двум разным типам, и на странице их никогда не складывают: одни правила измеряются по меткам, которые модель присвоила, прочитав сам сбой; это измеряет обнаружение. Остальные проверяются по собственному документированному определению, применённому независимо; это показывает, что код реализует формулу, но ничего не говорит о том, обнаруживает ли формула сбой. proof/RESULTS.md и страница с доказательствами отмечают тип каждого правила. CI повторно выполняет измерение при каждом pull request и завершается с ошибкой, если зафиксированные показатели отличаются от результатов работы кода, поэтому правило не может измениться без изменения его показателей. Показатели опубликованы на iris-eval.com/proof и в proof/RESULTS.md; о том, как был создан корпус, чем он не является и как читать интервал, рассказывается в docs/proof.md. Корпус синтетический и размечен моделью — слепая разметка человеком ещё не выполнена, и на странице об этом сказано; node proof/blind-sample.mjs формирует воспроизводимую выборку, которая позволит разрешить этот вопрос.
Инструменты MCP
Iris регистрирует двенадцать инструментов, доступных любому MCP-совместимому агенту: трассировка и управление жизненным циклом правил, сравнение запусков, оценка с помощью LLM и семантическая проверка цитат:
log_trace— Записать выполнение агента со спанами, вызовами инструментов, использованием токенов и стоимостью; передайтеevaluate: true, чтобы оценить его в том же вызовеevaluate_output— Оценить качество вывода по правилам полноты, релевантности, безопасности и стоимости (эвристически, детерминированно, бесплатно)get_traces— Запросить сохранённые трассировки с фильтрацией, постраничной выдачей и поддержкой временного диапазона, а также найти запуск, в котором агент что-то сказал, используяq: полнотекстовый поиск по входным данным, выводу, значениям вызовов инструментов и метаданным; результаты ранжируются, совпавшие слова выделяютсяlist_rules— Перечислить развёрнутые пользовательские правила оценки (только чтение)deploy_rule— Зарегистрировать новое пользовательское правило оценки, чтобы оно срабатывало при каждомevaluate_outputсоответствующей категорииdelete_rule— Удалить развёрнутое пользовательское правило (разрушительная операция, идемпотентная)delete_trace— Удалить одну сохранённую трассировку по ID (разрушительная операция, ограниченная областью арендатора)evaluate_with_llm_judge— Семантическая оценка с помощью LLM (Anthropic или OpenAI). Семь шаблонов: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance. Ограничение стоимости, цена каждой оценки раскрывается. Используйте собственный API-ключ (IRIS_ANTHROPIC_API_KEYилиIRIS_OPENAI_API_KEY) — Iris не проксирует и не ретранслирует вызовы LLM.verify_citations— Извлечь цитаты из вывода (нумерованные, автор–год, URL, DOI), получить источники через резолвер с защитой от SSRF и списком разрешённых доменов, а затем с помощью LLM-судьи проверить, подтверждает ли каждый источник указанное утверждение. Исходящие HTTP-запросы выполняются только по запросу. Требуется тот же BYOK, что и дляevaluate_with_llm_judge.compare_runs— Ухудшил ли агент результат после изменения? Сравнивает два запуска сохранённых оценок: парный точный тест, если в запусках совпадают ключи случаев; интервал разницы в противном случае; честный ответ «нельзя определить» с указанием числа необходимых случаев либо «эквивалентно в пределах допуска». Для каждого правила выполняется собственный односторонний тест; результаты корректируются совместно (Benjamini–Hochberg), чтобы двадцать правил не могли искусственно создать регрессиюcompare_traces— Насколько надёжно агент отвечает на один и тот же вопрос? Частота успешных ответов по каждому случаю с интервалами, сначала нестабильные случаи, а также общая частота с учётом повторовevaluate_runs— Повторно оценить каждую трассировку запуска по текущим правилам и сохранить результат в новом запуске, чтобы изменение правил никогда не принималось за изменение агента
Включение LLM-судьи (необязательно; детерминированным правилам он никогда не нужен)
- Получите API-ключ Anthropic или OpenAI.
- Добавьте его в окружение процесса, который запускает Iris, а не только в окружение оболочки. Claude Code, Claude Desktop, Cursor и большинство MCP-клиентов: блок "env" записи iris-eval в конфигурации MCP — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (для ключа OpenAI используйте IRIS_OPENAI_API_KEY). Docker: добавьте -e IRIS_ANTHROPIC_API_KEY=... в команду запуска. HTTP или CI: экспортируйте переменную перед запуском iris-eval.
- Перезапустите сеанс MCP. Уже запущенный процесс не увидит переменную, заданную после его старта.
- Проверьте из клиента: прочитайте iris://capabilities — там judge.enabled должно быть true. Ключ, экспортированный в оболочке, не передаётся процессу, запускаемому клиентом, если он не указан в конфигурации клиента. На машине команда
npx @iris-eval/mcp-server --self-testвыводит строку о судье для этой оболочки, а GET /api/v1/health сообщает judge.enabled для работающей панели управления. - Ограничение расходов: стоимость каждого вызова ограничена значением IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (по умолчанию 0.25 USD); вызов отклоняется до любых расходов, если максимальная возможная стоимость превысит этот предел. Все вызовы судьи, которые Iris выполняет с вашим ключом, учитываются в общем дневном бюджете IRIS_LLM_JUDGE_DAILY_BUDGET_USD (по умолчанию 1 USD за день UTC); после его исчерпания вызовы не выполняются до полуночи UTC. Iris обращается к провайдеру напрямую с вашим ключом и никогда его не проксирует.
- Необязательно: задайте IRIS_RELEVANCE_JUDGE_MODEL, указав ID модели с известной ценой (например, claude-haiku-4-5), чтобы answers_the_ask просил судью проверять, отвечает ли каждый ответ на поставленный вопрос, и помечал ответы не по теме как неуспешные. Это один вызов судьи на каждую оценку с входными данными; он выполняется с вашим ключом и в пределах указанного выше лимита. Само наличие ключа эту функцию не включает. При каждом вызове входные данные и вывод отправляются провайдеру модели; перед отправкой личные данные и учётные данные с флагами no_pii заменяются (IRIS_RELEVANCE_JUDGE_REDACT=off отправляет их без изменений). Вызовы учитываются в дневном бюджете, а на один запрос выполняется не более IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST вызовов (по умолчанию 20); при исчерпании любого из этих лимитов answers_the_ask анализирует вопрос лексически и объясняет причину.
Если настроен IRIS_OTEL_ENDPOINT, вызовы log_trace также выполняют наилучшую попытку экспорта OTLP/HTTP JSON в любой коллектор OpenTelemetry (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb и т. д.). См. docs/otel-integration.md.
Как определяется passed
evaluate_output возвращает и score, и флаг passed — они отвечают на разные вопросы:
score(0..1) — взвешенное среднее по выполненным правилам, то есть градация качества.passed— вердикт о возможности выпуска, и оценка при его вынесении никогда не учитывается. Компоновщик рассматривает каждое правило с учётом типа утверждения, которое оно делает: настроенная вами политика блокирует выпуск; критический детектор накладывает вето; если критическая проверка была запрошена, но не смогла дать ответ, вердикт становится неизвестным (passed: false), а не положительным; все остальные детекторы объединяются в одну вероятность того, что вывод плох, и сопоставляются с коэффициентом потерь, указанным вами вeval.falsePassCost(по умолчанию 1, поэтому порог равен 0.5).verdict.basisуказывает слой, вынесший решение, аverdict.by— правила;verdict.alsoперечисляет все последующие слои, которые тоже вынесли бы решение;interpretations[]объясняет, почему неуспешное правило не повлияло на решение и какая настройка это изменила бы, а также называет вопросы, которые не оценивались, и входные данные, необходимые для их оценки.
Реальные нарушения безопасности приводят к безусловному отказу. По умолчанию no_pii, no_injection_patterns и no_blocklist_words — критические правила: если одно из них не проходит проверку, оценка возвращает passed: false независимо от результатов остальных правил, а в ответе перечисляются виновные правила в critical_failures. Утечку SSN нельзя компенсировать усреднением. Список критических встроенных правил задаётся настройкой развёртывания (eval.criticalRules / eval.nonCriticalRules), как и список детекторов, которые только сообщают о проблеме (eval.advisoryRules); результат каждого правила содержит эффективный флаг critical и criticalSource, а list_rules сообщает список правил, применяемый этим сервером. Пользовательские правила, развёрнутые с severity: "high" или "critical", приводят к безусловному отказу таким же образом; уровни серьёзности low/medium влияют только на оценку. Важно знать одну границу, одинаково обозначенную во всех интерфейсах: критическое правило, которое пропущено (из-за отсутствующего контекста, некорректного определения или остановки регулярного выражения по достижении лимита песочницы), не проверило вывод и не накладывает вето — все такие правила перечислены в critical_skipped. Шлюз, который должен закрываться при сбое, считает непустой critical_skipped неизвестным, а не положительным результатом и может аналогично обрабатывать любой пропуск budgetExceeded в rule_results.
Для CI-шлюзов: если не указать eval_type, выполняются все наборы правил — полнота, релевантность, безопасность, стоимость и любые пользовательские правила. В ответе указывается eval_type: "all" с note, подтверждающим запуск набора по умолчанию, а также карта categories для каждого набора. Каждая строка содержит state: вердикт для правил этого набора, поэтому в строке никогда не будет указано, что проверка пройдена, если оценка не прошла из-за других правил. Для набора, которому нечего оценивать (стоимость без cost_usd, релевантность без input), указываются state: "unknown" и passed: null — проверка не выполнялась, а не завершилась неудачей; такой набор никогда не учитывается при вынесении вердикта. В ответе всегда отражается запущенный набор eval_type, чтобы шлюз мог проверить полноту охвата; для вердикта используйте passed, а имя набора указывайте только при необходимости запустить более узкую проверку.
Создание пользовательского правила
Добавить правило можно двумя способами. Встроенные правила передаются в одном вызове evaluate_output (custom_rules, до 10 за вызов); они выполняются вместе с выбранным вами набором eval_type или отдельно, если указать eval_type: "custom". Развёрнутые правила регистрируются один раз с помощью deploy_rule, сохраняются в custom-rules.json в каталоге Iris home и выполняются при каждом последующем evaluate_output соответствующего evalType. В обоих случаях используется одна и та же структура определения:
| Поле | Обязательно | Описание |
|---|---|---|
name | да | От 1 до 80 символов; отображается в результатах как ruleName |
type | да | Одно из значений: regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold |
config | да | Ключи для этого типа: pattern (и необязательный flags) для двух типов регулярных выражений · min_length / max_length (количество символов) · keywords (и необязательный threshold, 0–1, по умолчанию 1 = должны присутствовать все) для двух типов ключевых слов · {} для json_schema · max_cost в USD для cost_threshold |
weight | нет | Вес в оценке; по умолчанию 1 |
deploy_rule оборачивает определение в name, необязательный description, evalType (completeness · relevance · safety · cost · custom) и severity. Уровень серьёзности определяет значение неуспешной проверки: low/medium только снижают оценку; high/critical приводят к безусловному отказу в оценке — passed: false, с указанием правила в critical_failures, — независимо от взвешенной оценки. Правило, которое пропущено (правило типа cost_threshold без cost_usd или регулярное выражение, остановленное по достижении 100 мс лимита песочницы), не проверило вывод и вместо этого указывается в critical_skipped. Разверните критическое правило, запрещающее агенту упоминать внутренние имена хостов:
{
"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" }
}
}
В ответе возвращается сохранённое правило — сохраните id для delete_rule:
{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }
Начиная со следующего evaluate_output с eval_type: "safety", результат, в котором упоминается db-primary.internal.example, возвращается passed: false с critical_failures: ["no_internal_hostnames"] — хотя все пять встроенных правил безопасности пройдены, а взвешенная оценка составляет 0.895. Шаблоны Regex должны проходить проверку на ReDoS во время развёртывания и всегда выполняться в изолированном рабочем процессе с жёстким ограничением в 100 ms. list_rules показывает, что развёрнуто; конструктор правил на панели управления создаёт такую же структуру на основе выбранного вами сбоя. Полный справочник, оценивание по типам и примеры с разбором: docs/custom-rules.md.
Полные схемы инструментов и конфигурация: iris-eval.com
Самостоятельный хостинг и бесплатное использование
Iris работает на вашем компьютере или собственной инфраструктуре. Ядро с открытым исходным кодом бесплатно и распространяется по лицензии MIT, без ограничений на использование и без учётной записи. Размещение данных, общая история команды и оповещения рассматриваются, но пока не разрабатываются; если они были бы вам полезны, напишите нам на hello@iris-eval.com.
Мы придерживаемся двух обязательств: ничто из того, что бесплатно сегодня, не станет платным, и мы не будем заявлять о сертификации соответствия требованиям, пока не получим её.
Примеры
- Настройка Claude Desktop — конфигурация MCP для режимов stdio и HTTP
- TypeScript — клиент MCP SDK — подключение и вызов инструментов
- Транспорт HTTP (TS + Python) — полный код клиента для интеграции в стиле REST
- Агент LangGraph, оценивание каждого запуска (Python) —
IrisCallbackHandlerв обратных вызовах графа; CI запускает тот же граф со скриптовой моделью - Команда CrewAI поверх OpenTelemetry (Python) — инструментирование OpenInference напрямую в точку приёма OTLP Iris, рецепт CrewAI в виде скрипта
- Агент OpenAI Agents SDK поверх OpenTelemetry (Python) и (JavaScript), а также агент LlamaIndex — каждый рецепт представлен скриптом, который CI запускает на реальном сервере Iris
Сообщество
- Проблемы на GitHub — сообщения об ошибках и запросы функций
- Обсуждения на GitHub — вопросы и идеи
- Получение помощи — где задать вопрос, сообщить об ошибке или уязвимости
- Руководство по участию — как внести вклад; AGENTS.md — то же руководство для агентов программирования
- Управление проектом — кто принимает решения, как принимаются изменения и как выпускается и проверяется релиз
- Приём данных по HTTP — детерминированный сбор трассировок через
POST /api/v1/traces - Карта возможностей — на какие вопросы можно задать Iris и чего ему не хватает
- Политика версионирования — что обещает каждый номер версии и какие условия должны быть выполнены до версии 1.0
Конфигурация и безопасность
Аргументы CLI
| Флаг | По умолчанию | Описание |
|---|---|---|
--transport | stdio | Тип транспорта: stdio или http |
--port | 3000 | Порт HTTP-транспорта |
--db-path | ~/.iris/iris.db | Путь к базе данных SQLite |
--config | ~/.iris/config.json | Путь к файлу конфигурации |
--api-key | — | Ключ API для HTTP-аутентификации (транспорт и панель управления, включая POST /api/v1/traces) |
--dashboard | false | Включить веб-панель управления. Также это единственный способ запустить конечную точку приёма данных POST /api/v1/traces — она никогда не запускается автоматически вместе с --transport http |
--dashboard-port | 6920 | Порт панели управления |
--dashboard-host | 127.0.0.1 | Адрес привязки панели управления. По умолчанию — loopback; панель управления не требует аутентификации, если не задан --api-key, поэтому привязка за пределами loopback открывает доступ ко всей истории трассировок |
--demo | false | Создать демонстрационную базу данных (отдельно от ваших реальных трассировок) и обслуживать панель управления на её основе |
--demo-clear | false | Удалить демонстрационную базу данных и завершить работу |
--self-test | false | Запустить автономную диагностику установки в изолированном временном домашнем каталоге, затем завершить работу (0 = всё исправно, 1 = проверка не пройдена). Диагностика также читает настроенную базу данных в режиме только для чтения и завершается ошибкой, если эта версия или закреплённый клиент MCP не может её открыть |
--purge | false | Удалить все сохранённые трассировки, спаны и оценки из настроенной базы данных, уплотнить файл и обрезать журнал предварительной записи, чтобы удалённый текст не оставался на диске, затем завершить работу. Развёрнутые правила, журнал аудита и настройки сохраняются. Действие необратимо. Сначала остановите все запущенные серверы Iris — файл уплотняется на месте. Нельзя использовать вместе с --demo, --demo-clear или --self-test |
--version | — | Вывести версию без дополнительного текста (например, 1.2.3) в stdout и завершить работу с кодом 0. Не читает ничего из домашнего каталога Iris |
Три команды принимают собственные аргументы и завершают работу: iris-eval ingest загружает трассировки из файла или stdin (Шлюз CI без сервера), iris-eval export traces|evaluations --format csv|jsonl выводит сохранённые данные с фильтрами, как в списках панели управления, в stdout или --out (docs/api-reference.md), а iris-eval install <client> добавляет Iris в конфигурацию клиента MCP — --uninstall удаляет его, --list показывает найденные на этом компьютере клиенты и версии Iris, которые они запускают, а --upgrade обновляет все клиенты, запускающие Iris, до этой версии (Подключение собственного агента, Обновление). Ни одна из них не запускает сервер.
config.json проверяется при запуске Iris. Если Iris не распознаёт ключ — например, из-за опечатки вроде eval.critcalRules или ключа от другого инструмента — либо значение имеет неверный тип, запуск будет отклонён с одним предложением, в котором указан полный ключ, наиболее вероятный ключ, который имелся в виду, или ожидаемый тип. Ничто в файле не игнорируется молча.
Переменные окружения
Каждая переменная документирована в --help. Если заданы и флаги CLI, и переменные окружения, приоритет имеют флаги CLI.
| Переменная | Описание |
|---|---|
IRIS_TRANSPORT | Тип транспорта (stdio или http) |
IRIS_HOST | Адрес привязки HTTP-транспорта (по умолчанию 127.0.0.1) |
IRIS_PORT | Порт HTTP-транспорта (1–65535, по умолчанию 3000) |
IRIS_HOME | Каталог для всех файлов пользователей: config.json, iris.db, custom-rules.json, audit.log, preferences.json (по умолчанию ~/.iris) |
IRIS_DB_PATH | Путь к базе данных SQLite (переопределяет IRIS_HOME только для БД) |
IRIS_SQLITE_DRIVER | Какой драйвер SQLite хранит базу данных: native (better-sqlite3, по умолчанию) или node (встроенный в Node node:sqlite, Node 22.13+). Если не задано: native; если нативный модуль не удаётся загрузить (или это сборка, которая аварийно завершится в этой версии Node), Iris один раз выдаёт предупреждение и переключается на встроенный драйвер |
IRIS_SEARCH_BUDGET_MS | Сколько времени один поиск трассировки (q) может читать данные, прежде чем ответить найденными на данный момент совпадениями и search.complete: false, в миллисекундах (от 50 до 60000, по умолчанию 1000). Пока поиск читает данные, остальные запросы ждут, поэтому это также максимальное время ожидания для них. Также storage.searchBudgetMs в config.json |
IRIS_SEARCH_INDEX | on (по умолчанию) или off. off не хранит полнотекстовый индекс трассировок: при записи сохраняется только трассировка, а поиск трассировок (q) читает сами трассировки в пределах IRIS_SEARCH_BUDGET_MS, начиная с самых новых, поэтому в большом хранилище он может вернуть только часть совпадений (search.complete: false). При отключении индекс, хранившийся в базе данных, удаляется; при повторном включении создаётся новый индекс в фоновом режиме. Также storage.searchIndex в config.json |
IRIS_LOG_LEVEL | Уровень журнала: debug, info, warn, error |
IRIS_DASHBOARD | true/1/yes/on включает веб-панель; false/0/no/off отключает её (также переопределяет dashboard.enabled в config.json) |
IRIS_DASHBOARD_PORT | Порт панели (1–65535, по умолчанию 6920) |
IRIS_WEBHOOK_URL | Получатель вебхука, срабатывающего при наступлении момента, — объединяется с notify.webhook в config.json (docs/webhooks.md) |
IRIS_WEBHOOK_SECRET | Ключ подписи вебхука (любая строка или whsec_ + base64); формат iris отказывается запускаться без него |
IRIS_DASHBOARD_HOST | Адрес привязки панели (по умолчанию 127.0.0.1) |
IRIS_API_KEY | API-ключ для HTTP-аутентификации. Обязателен, если HTTP-транспорт или панель привязываются не к loopback-адресу (0.0.0.0, адресу локальной сети, контейнеру): без него сервер отказывается запускаться |
IRIS_API_KEY_FILE | Путь к файлу, содержимое которого после удаления пробелов по краям является API-ключом — это шаблон секретного файла, который монтируют Docker и Kubernetes, чтобы ключ не хранился в блоке переменных окружения. Задайте это или IRIS_API_KEY, но не оба параметра |
IRIS_ALLOW_UNAUTHENTICATED | Задайте 1, чтобы намеренно использовать привязку не к loopback-адресу без ключа (снимает запрет; в этом случае границей безопасности становится сеть) |
IRIS_ALLOWED_ORIGINS | Список разрешённых источников через запятую. Панель: заголовки CORS (поддерживаются шаблоны, например http://localhost:*). HTTP-транспорт: список разрешённых Origin с точным совпадением для защиты от DNS rebinding (шаблоны игнорируются; loopback-источники самого сервера всегда разрешены) |
IRIS_MAX_INPUT_ELEMENTS | Максимальное число элементов массива и ключей объекта во входных данных до их проверки (целое число, по умолчанию 100000): аргументы вызова инструмента в любом транспорте и тело запроса на порту панели (JSON-тела API и POST /v1/traces, JSON или protobuf). При превышении лимита вызов инструмента возвращает ошибку; тело запроса — 413. Значение по умолчанию пропускает все допустимые JSON-входные данные, включая запрос размером 1 МБ. Для тела protobuf на POST /v1/traces действует собственный предел: один элемент на каждые 5 байт security.requestSizeLimit (209,716 при размере 1 МБ) или это значение, если оно выше, поэтому пакет экспортёра в пределах размера запроса не отклоняется из-за плотности (в самом плотном измеренном теле реального экспортёра приходится один элемент на 7.5 байта); увеличение requestSizeLimit для более крупных пакетов коллектора также увеличивает этот предел. Также security.maxInputElements в config.json |
IRIS_MAX_TOOL_INPUT_ELEMENTS | Название IRIS_MAX_INPUT_ELEMENTS до версии 0.21.0; читается, если новое название не задано (и security.maxToolInputElements в config.json, аналогично) |
IRIS_NO_AUTO_LAUNCH | Задайте 1, чтобы отключить автоматический запуск панели при первом запуске |
IRIS_ANTHROPIC_API_KEY | Требуется для evaluate_with_llm_judge + verify_citations с provider=anthropic |
IRIS_OPENAI_API_KEY | Требуется для evaluate_with_llm_judge + verify_citations с provider=openai |
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL | Жёсткий предел стоимости одного вызова LLM-судьи (по умолчанию 0.25). max_cost_usd может снизить его для вызова, но не повысить |
IRIS_RELEVANCE_JUDGE_MODEL | Идентификатор платной модели-судьи (например, claude-haiku-4-5). Если задано и указан ключ этого провайдера, answers_the_ask обращается к этому LLM-судье при каждой оценке с входными данными и принимает решение на основе его вердикта о релевантности — один вызов судьи на оценку, в пределах указанного выше лимита стоимости и двух лимитов ниже. Входные и выходные данные каждой такой оценки отправляются провайдеру этой модели (Anthropic или OpenAI) с использованием вашего ключа; перед отправкой личные данные и учётные данные, отмеченные флагами no_pii, заменяются. Если параметр не задан (по умолчанию), answers_the_ask анализирует запрос лексически и выдаёт рекомендации; данные никуда не отправляются (docs/llm-as-judge.md) |
IRIS_LLM_JUDGE_DAILY_BUDGET_USD | Сколько все вызовы судьи вместе могут потратить за день по UTC на одного арендатора (по умолчанию 1): судья релевантности, evaluate_with_llm_judge и verify_citations используют общий лимит. Он хранится в базе данных, поэтому перезапуск его не сбрасывает. Вызов выполняется, только если его максимальная возможная стоимость укладывается в оставшийся лимит; после его исчерпания answers_the_ask анализирует запрос лексически (judge.withheld: "daily_budget"), а инструменты судьи отвечают IRIS_BUDGET_EXCEEDED (с указанием источника, daily_budget_reached). 0 останавливает все вызовы |
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD | Название IRIS_LLM_JUDGE_DAILY_BUDGET_USD до версии 0.21.0, когда оно ограничивало только судью релевантности. Читается, если новое название не задано; в этом случае оно ограничивает все вызовы судьи. Сервер сообщает об этом при запуске |
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST | Число вызовов судьи релевантности, которые может выполнить один запрос (по умолчанию 20): пакет OTLP или повторная оценка evaluate_runs проверяет первые 20 трассировок с помощью судьи, а остальные анализирует лексически, с judge.withheld: "request_cap" |
IRIS_RELEVANCE_JUDGE_REDACT | on (по умолчанию): все флаги no_pii каждого спана (личные данные и учётные данные) во входных и выходных данных заменяются маркером [REDACTED:<kind>#<n>] перед отправкой судье релевантности. off отправляет их без изменений |
IRIS_CITATION_ALLOW_FETCH | Задайте 1, чтобы разрешить исходящие HTTP-запросы в verify_citations (по умолчанию отключено). Аргумент инструмента может отключить это для вызова, но не включить |
IRIS_CITATION_DOMAINS | Список разрешённых имён хостов для verify_citations через запятую (совпадение по суффиксу). Аргумент инструмента может сузить список, но не расширить его |
IRIS_CITATION_MAX_COST_USD_TOTAL | Максимальная сумма, которую один вызов verify_citations может потратить на вызовы судьи (по умолчанию 1). max_cost_usd_total может снизить её для вызова, но не повысить |
IRIS_OTEL_ENDPOINT | Включить экспорт трассировок в формате OTLP/HTTP JSON с наилучшими усилиями на этот URL коллектора |
IRIS_OTEL_SERVICE_NAME | Атрибут ресурса service.name для экспорта OTel (по умолчанию iris-eval) |
IRIS_OTEL_HEADERS | Заголовки k=v для экспорта OTel через запятую (например, authorization=Bearer abc) |
IRIS_OTEL_TIMEOUT_MS | Тайм-аут одного экспорта (по умолчанию 15000) |
RATE_LIMIT_SALT | Только для сайта — добавляет соль к хешу адреса, который использует ограничитель частоты запросов на площадке iris-eval.com; сервер никогда не читает это значение |
Безопасность
При использовании HTTP-транспорта Iris обеспечивает:
- Аутентификацию по API-ключу с безопасным по времени сравнением (Bearer для API-клиентов; вход в панель через браузер с помощью
?key=) - Ограничение CORS по умолчанию адресом localhost
- Ограничение частоты запросов для каждого адреса клиента в минуту: 600 запросов к API панели (
security.rateLimit.api) и 20 к конечной точке MCP (security.rateLimit.mcp); оба значения задаются вconfig.json; при превышении лимита запрос MCP получает ошибку JSON-RPC с указанием ключа - Заголовки безопасности Helmet
- Проверку входных данных Zod на всех маршрутах
- Регулярные выражения для пользовательских правил eval, защищённые от ReDoS
- Единый лимит размера запроса 1 МБ для каждого транспорта (
security.requestSizeLimit): HTTP возвращает413, stdio возвращает ошибку JSON-RPC и оставляет сеанс открытым - Единый лимит в 100,000 элементов массивов и ключей объектов во входных данных, подсчитываемых до проверки (
security.maxInputElements): при превышении лимита аргументы вызова инструмента в любом транспорте возвращают ошибку, а тело запроса панели или OTLP —413 - Ошибки проверки возвращают не более 20 проблем и их общее количество (
issueCount), поэтому ответ остаётся небольшим независимо от того, насколько неверен запрос
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard
Если задан ключ, API-клиенты — клиенты MCP, SDK захвата данных, POST /api/v1/traces — отправляют Authorization: Bearer <key>. Чтобы открыть панель в браузере, один раз добавьте ключ к любому URL панели, http://localhost:6920/?key=<api key>: Iris обменивает его на сессионную cookie HttpOnly, SameSite=Lax и перенаправляет на ту же страницу, удалив ключ из адресной строки. При открытии страницы без сеанса отображается форма входа, которая выполняет такой же обмен. Ключ никогда не сохраняется в браузере, а сеансы существуют только в процессе сервера (одновременно может быть не более 256 активных сеансов; если при входе все места заняты, запрос отклоняется, а не вытесняет существующий сеанс).
Рабочая среда
Несколько ключей и ротация без перерыва. security.apiKeys в config.json содержит любое количество дополнительных ключей, каждый с id и ровно одним из параметров keyFile (файл, содержимое которого после удаления пробелов по краям является ключом) или keyHash (значение sha256 в шестнадцатеричном формате, поэтому файл конфигурации не содержит секретов — printf %s "$KEY" | openssl dgst -sha256), а также необязательным expiresAt (ISO 8601), после которого ключ перестаёт действовать в указанный момент. Для ротации добавьте новый ключ, переключите клиентов на него, затем удалите старый. Ключи в config.json и файлах ключей вступают в силу без перезапуска (0.20.0): при каждом запросе сервер проверяет, изменился ли config.json или указанный в нём файл ключа, и при необходимости перечитывает ключи перед ответом. Удаление ключа из security.apiKeys или удаление его файла отзывает ключ при следующем запросе: этот запрос отклоняется, а все открытые с этим ключом сеансы браузера завершаются. Если config.json не удаётся прочитать (например, файл записан не полностью), система закрывает доступ; пока проблема не устранена, принимается только ключ из IRIS_API_KEY или --api-key. Сам ключ в IRIS_API_KEY или --api-key, а также включение или отключение аутентификации по-прежнему меняются только после перезапуска. Каждый ключ проходит аутентификацию, пока не будет удалён или не истечёт срок его действия, как при использовании Bearer, так и при входе в браузере; в журнале запуска указываются идентификаторы ключей. security.rateLimit.mcpKeyBy: "apiKey" учитывает минутный лимит конечной точки MCP отдельно для каждого ключа, а не для каждого адреса клиента, поэтому несколько агентов за одним адресом получают собственный лимит на минуту.
Несколько клиентов. --transport http обслуживает любое количество клиентов MCP по одному адресу: каждый initialize открывает собственный сеанс на одном движке и хранилище; одновременно допускается до 256 сеансов. При использовании stdio каждый клиент запускает собственный процесс сервера, а эти процессы совместно используют домашний каталог Iris: правило, развёрнутое, отключённое или удалённое одним клиентом, применяется во всех остальных в течение 20 мс; метка, записанная одним клиентом, сразу же доступна остальным; если два клиента одновременно изменяют правила, ни одно изменение не теряется.
Iris отказывается запускаться, если HTTP-транспорт или панель управления привязаны не только к loopback — 0.0.0.0, адресу локальной сети, контейнеру — и API-ключ не задан, и сообщает об этом одним предложением, в котором упоминается IRIS_API_KEY. Это относится и к простому docker run образа, который привязывает 0.0.0.0 внутри контейнера, поскольку через опубликованный порт loopback недоступен. Loopback без ключа продолжает работать (с предупреждением для HTTP-транспорта): в этом случае границей доступа служит сама машина.
# 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
Открыты по замыслу на сервере с ключом: GET /health на транспорте и GET /api/v1/health на панели управления отвечают без ключа и не подпадают ни под одно ограничение частоты запросов, используя единый формат: статус, версия, время работы, драйвер SQLite, checks для хранилища, файл развернутых правил и миграции (применённые относительно известных), состояние поискового индекса (search: готов или указано, какая доля трасс уже обработана при построении), а также наличие ключа судьи — но никогда не сам ключ, не трассу и не их количество. status имеет значение ok, только если все проверки пройдены; иначе он имеет значение degraded с HTTP 503, который проверяет собственный HEALTHCHECK образа Docker. Для всего остального нужен Authorization: Bearer <key> или сеанс браузера. На каждом сервере выполняется очистка данных: трассы и оценки старше retention.days (по умолчанию 30) удаляются при запуске, после того как сервер начинает отвечать, а затем каждые retention.sweepIntervalHours, небольшими порциями, чтобы запросы не ждали долго; --self-test выводит политику этого экземпляра, а iris://capabilities / GET /api/v1/capabilities передают её как retention.
Вебхук срабатывает при наступлении события (0.16.0): notify.webhook в config.json (или IRIS_WEBHOOK_URL и IRIS_WEBHOOK_SECRET) указывает получателя, и Iris отправляет одно подписанное сообщение, когда вердикт не пройден, критическое обнаружение блокирует результат, стоимость оказывается выбросом, частота сбоев правила меняется или по делу впервые получены оба варианта ответа — идентификаторы, вердикт, правила и числа, но никогда текст агента. Подпись одновременно соответствует стандартам Standard Webhooks и GitHub; повторы выполняются с экспоненциальной задержкой, для каждого агента и правила действует период охлаждения, а оценка не задерживается; форматы сообщений Slack и Discord встроены. docs/webhooks.md.
Ваши данные на диске
Всё, что хранит Iris, находится в домашнем каталоге Iris (~/.iris или IRIS_HOME). iris.db сохраняет input и output каждой трассы без изменений — включая любой текст, который no_pii впоследствии пометит; обнаружение не редактирует текст, если вы сами этого не попросите: storage.redact: "critical_spans" в config.json сохраняет результат каждой оценки, заменяя фрагменты, помеченные критическим детектором, на [REDACTED:<pattern>] (по умолчанию выключено; смещения в свидетельствах по-прежнему указывают на текст, который видел вызывающий код). storage.synchronous задаёт момент записи данных на диск: normal (значение по умолчанию) синхронизирует журнал упреждающей записи при каждой контрольной точке, поэтому при сбое Iris ничего не теряется и файл не повреждается, но отключение питания или сбой операционной системы могут отменить записи, сделанные после последней синхронизации; full синхронизирует каждую фиксацию и сохраняет её при обоих типах сбоев, добавляя около 1,5 мс к каждой записи. При запуске, а затем каждые retention.sweepIntervalHours (по умолчанию 24; 0 отключает таймер) трассы и оценки старше retention.days (по умолчанию 30; 0 отключает очистку; задаётся в config.json) удаляются, а журнал упреждающей записи проходит контрольную точку. За пределами этого срока сохраняется только один объект: закреплённый базовый запуск вместе с его оценками, поскольку с ним сравниваются все последующие запуски. Каждая очистка, сохраняющая часть данных, записывает в журнал сведения о запуске и количестве объектов; снимите закрепление с запуска, и следующая очистка удалит его. Примеры наборов данных и метки не являются трассами или оценками и не удаляются при очистке. Удаление трассы — через delete_trace или очистку — стирает текст всех связанных с ней оценок (результат, ожидаемый текст и сообщения правил) и устанавливает erased_at; вердикт, оценки и смещения свидетельств сохраняются. Перед возвратом после каждого удаления выполняется контрольная точка журнала упреждающей записи, поэтому удалённый текст нельзя прочитать из iris.db или iris.db-wal (если в этот момент файл читает поиск или другой процесс читает либо записывает его, удаление возвращается без ожидания, а текст исчезает из файла сразу после завершения операции). Чтобы немедленно удалить всё, остановите сервер и выполните --purge: команда удаляет все сохранённые трассы, фрагменты и оценки, уплотняет базу данных и обрезает журнал упреждающей записи, чтобы текст исчез с диска, сохраняя развернутые правила, журнал аудита и настройки. Перед применением миграции к существующему iris.db выпуск создаёт копию рядом с файлом (iris.db.<from>-to-<to>.<time>.bak, доступную только владельцу; сохраняются три последние копии; Переход на предыдущую версию): в копии трассы остаются в прежнем виде, поэтому очистка удалит трассы старше retention.days, а --purge удалит их все. Сервер создаёт копию и выполняет миграции после ответа клиенту, в отдельном потоке: поступившие в это время вызовы инструментов, чтение ресурсов и HTTP-запросы ждут не более 30 с каждый, после чего отклоняются с сообщением о текущей операции сервера (IRIS_STORAGE_ERROR, можно повторить; HTTP 503 с Retry-After). Проверка состояния продолжает отвечать и сообщает, что выполняется обновление. В версии 0.19.0 при 100 000 трасс, каждая из которых представляет собой цикл агента, копирование и миграции заняли около 6 с. iris-eval ingest, --purge и --self-test по-прежнему выполняют обновление до любых других действий.
Iris не шифрует данные в состоянии покоя. iris.db и файлы журнала упреждающей записи создаются с правами только для владельца (режим 600), а домашний каталог Iris создаётся с режимом 700 (в Windows вместо этого действуют списки управления доступом к файлам). База данных не хранит ключи поставщиков LLM: IRIS_ANTHROPIC_API_KEY и IRIS_OPENAI_API_KEY считываются из окружения и никогда не записываются на диск. Однако в ней хранятся входные и выходные данные трасс без изменений, поэтому разместите домашний каталог Iris на зашифрованном диске или томе (FileVault, BitLocker, LUKS или зашифрованный облачный том для точки монтирования /data образа Docker).
Экспорт — кнопка Export на страницах Traces и Evaluations панели управления, GET /api/v1/traces/export и /api/v1/evaluations/export или iris-eval export — содержит сохранённый текст без изменений, как он отображается на панели: входные и выходные данные трассы без изменений, результат оценки с применённым storage.redact. Обращайтесь с экспортированным файлом так же, как с исходной базой данных.
Устранение неполадок
Первый шаг: запустите самопроверку
npx @iris-eval/mcp-server --self-test
Она проверяет хранилище, детерминированные оценки и панель управления в изолированном временном домашнем каталоге и выводит вердикт для каждого шага — в сообщении об ошибке указано, какой шаг не пройден. Код завершения 0 означает, что установка работает исправно.
Iris не запускается / ERR_MODULE_NOT_FOUND
Возможно, у вас закэширована старая версия. Очистите кэш npx и повторите попытку:
npx --yes @iris-eval/mcp-server@latest
Или установите пакет глобально, чтобы полностью избежать проблем с кэшем:
npm install -g @iris-eval/mcp-server@latest
npm install --ignore-scripts нарушил работу привязки SQLite
Iris хранит трассы с помощью better-sqlite3, нативного модуля, который загружает или компилирует привязку в установочном скрипте. Если этот скрипт был пропущен — из-за --ignore-scripts в командной строке, ignore-scripts=true в .npmrc (часто встречается на корпоративных компьютерах) или зеркала реестра, удаляющего postinstall, — запуск завершается длинным сообщением «Could not locate the bindings file» со списком дюжины проверенных путей. Пересоберите этот модуль:
npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3
Инструменты не отображаются в Claude Code
Инструменты MCP загружаются только при запуске сеанса. После добавления iris-eval перезапустите сеанс с помощью /clear или перезапустите терминал.
Проверка версии
npx @iris-eval/mcp-server --version
Она также указана в первой строке журнала запуска (Starting Iris MCP server vX.Y.Z), а --self-test выводит её в сводке. Для глобальной установки установленную версию показывает npm ls -g @iris-eval/mcp-server.
Обновление
Все клиенты MCP на одной машине используют одну базу данных, ~/.iris/iris.db, а install закрепляет за каждым клиентом выпуск, создавший его конфигурацию. Когда выпуск меняет схему базы данных, первый процесс этого выпуска, открывший файл, обновляет его; после этого клиент, закреплённый за старым выпуском, отказывается запускаться. Поэтому обновите все клиенты за один раз — до обновления или сразу после него:
npx -y @iris-eval/mcp-server@latest install --upgrade
Команда находит все конфигурации клиентов на этой машине, в которых запускается Iris, и обновляет закреплённую версию до указанного выпуска (сохраняя всё добавленное вами в запись, например --dashboard или блок env), не меняет закрепление на более новый выпуск и записи, запускающие что-либо помимо npm-пакета, а также выводит список выполненных действий. Перезапустите указанные клиенты. install --list показывает, какую версию Iris запускает каждый клиент.
Две установки находятся вне этих файлов: расширение Claude Desktop (iris-eval.mcpb) обновляется при открытии более нового пакета, а плагины Claude Code — с помощью claude plugin marketplace update iris-eval, затем claude plugin update iris-eval@iris-eval (и claude plugin update iris-eval-capture@iris-eval для плагина захвата).
Обновление с 0.19.x до 0.20.0. Версия 0.20.0 добавляет в базу данных поисковый индекс и другие данные (миграции 015 и последующие). После того как любой процесс 0.20.0 откроет ~/.iris/iris.db (расширение Claude Desktop, npx iris-eval или npx @iris-eval/mcp-server без указания версии), клиент, закреплённый за 0.19.x, завершится с сообщением This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, …. Это сообщение выдаёт 0.19.x, и изменить его нельзя; решение — выполнить команду выше. Перед обновлением 0.20.0 создаёт копию файла рядом с ним, поэтому при необходимости можно вернуться к предыдущей версии (см. ниже).
При запуске, обновившем базу данных, в stderr выводится информация о выполненных действиях: созданная копия, выпуски, которые больше не смогут открыть файл, и клиенты на этой машине, закреплённые за одним из этих выпусков, а также команда для исправления. --self-test читает базу данных, не изменяя её, и выводит ту же информацию до запуска любых процессов.
Для глобальной установки выполните npm update -g @iris-eval/mcp-server, затем iris-eval install --upgrade.
Переход на предыдущую версию
Выпуск, обновивший базу данных, сначала создаёт её копию рядом с исходным файлом: iris.db.<from>-to-<to>.<time>.bak в домашнем каталоге Iris (<from> — выпуск, который последним изменил схему файла; <to> — выпуск, выполнивший обновление; точный путь выводится в строке запуска). Чтобы вернуться к предыдущей версии:
- Остановите все клиенты MCP и любые другие процессы Iris, использующие базу данных.
- Сохраните обновлённый файл на случай, если захотите вернуться: переименуйте
iris.dbвiris.db.upgradedи удалитеiris.db-walиiris.db-shm, если они существуют. - Скопируйте резервную копию в
iris.db:cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db. - Закрепите за каждым клиентом предыдущий выпуск: выполните
npx -y @iris-eval/mcp-server@0.19.0 install <client>для каждого клиента (install --upgradeникогда не возвращает клиента на предыдущую версию).
Трассы, сохранённые после обновления, находятся в iris.db.upgraded, а не в резервной копии. Если копия не была создана (в строке запуска указана причина, например переполненный диск), предыдущий выпуск не сможет открыть обновлённый файл; в этом случае нужно выполнить install --upgrade.
Драйвер хранилища
Установка проходит успешно даже на платформе, для которой нет готовой сборки better-sqlite3. better-sqlite3 — необязательная зависимость: если npm не может ни скачать готовый бинарный файл для вашей версии Node и платформы, ни скомпилировать его (для компиляции нужны Python и инструментарий C++ — в Windows это средства сборки C++ для Visual Studio), npm выводит ошибку сборки, пропускает модуль и завершает установку. После этого Iris работает на встроенном в Node SQLite и сообщает об этом: при запуске в stderr выводится одна строка с причиной, а --self-test показывает driver node: better-sqlite3 is not installed …. Чтобы снова использовать нативный драйвер, установите его там, где доступна готовая сборка или инструментарий (npm install better-sqlite3 в проекте; при глобальной установке повторно установите Iris с помощью npm install -g @iris-eval/mcp-server, когда инструментарий станет доступен). При каждом изменении CI устанавливает упакованный сервер, принудительно вызывая сбой нативной сборки, и проверяет, что установка завершается, а самопроверка сохраняет и читает трассу с помощью встроенного драйвера.
Iris хранит всё в одном файле SQLite, который открывается с помощью better-sqlite3 — нативного дополнения, загружаемого или компилируемого для вашей версии Node и платформы. Если этот модуль не удаётся загрузить, Iris переключается на встроенный в Node SQLite (node:sqlite, Node 22.13 или новее) и выводит одно предупреждение в stderr, поэтому отсутствие готовой сборки лишь замедляет запуск, а не делает его невозможным. То же происходит до загрузки модуля, если это better-sqlite3, скомпилированное на вашем компьютере с заголовками Node 24.19 или новее и запущенное на Node 24.19–24.21: в этих версиях такой бинарный файл аварийно завершает весь процесс при первом освобождении инструкции (Assertion failed: (env) != nullptr, nodejs/node#65446). В Node 24.22.0 исправление уже есть, и Iris загружает там бинарный файл. npm rebuild better-sqlite3 заменяет его готовым бинарным файлом, безопасным для всех версий. IRIS_SQLITE_DRIVER=node намеренно выбирает встроенный вариант, а native запрещает переключение. Встроенный вариант открывается с отключённой загрузкой расширений и отключённым trusted_schema; при его загрузке Node выводит собственную строку ExperimentalWarning: SQLite is an experimental feature в stderr, и Iris её не подавляет. --self-test и GET /health указывают используемый драйвер; все числа на странице с результатами измерений получены на нативном драйвере, а в CI набор тестов запускается на обоих.
Версия Node.js
Для Iris требуется Node.js 22.13 или новее. Поддержка Node 20 завершилась 2026-04-30, поэтому он не поддерживается; поддержка Node 18 завершилась в апреле 2025 года.
Минимальная версия — 22.13, а не 22.0, потому что 22.13.0 — первый выпуск с node:sqlite. Это первая версия, в которой у каждой поддерживаемой установки Iris есть второй драйвер хранилища: если нативное дополнение better-sqlite3 не удаётся загрузить, Iris переключается на встроенный в Node SQLite вместо того, чтобы завершить запуск с ошибкой. До 22.13 — и на протяжении всего срока существования Node 20 — был только один драйвер, и отсутствие готовой сборки делало запуск невозможным.
node --version # Must be v22.13.0 or newer
Windows: cmd /c не требуется
/doctor Claude Code может предложить обернуть npx в cmd /c. Это не требуется и приводит к проблемам при разборе путей. Используйте напрямую 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"
Если Iris оказался вам полезен, поставьте звезду репозиторию — так другим будет проще его найти.
Лицензия MIT.