Iris

公式

MCPネイティブのエージェント評価と可観測性サーバー。トレースログ、出力品質評価、コスト追跡、12の組み込み評価ルール、リアルタイムダッシュボード、PII検出を備えています。

Iris MCPで何ができますか?

  • 実行を記録してスコアを確認 — アシスタントにエージェントの実行を Iris に記録して出力を評価するよう依頼し、ダッシュボードで判定とスコアを確認します。
  • 安全性とコストのルールを確認 — LLM を呼び出さずに、PII、プロンプトインジェクション、ハルシネーションの兆候、コストのしきい値に関する組み込みの決定論的ルール 28 件を実行します。
  • ルールを確認・編集 — 組み込みルールを一覧表示して確認または変更します。すべてのルールを確認・編集できます。
  • カスタムルールを追加 — config.json の eval.plugins を通じて、コードとして作成したルールを読み込み、ファイルハッシュで固定します。
  • 実行を比較 — ダッシュボードの Runs ビューで、同じ質問に対する 2 つの実行を間隔を空けて並べて表示します。
  • 判定に基づいて CI をゲート — --evaluate --fail-on any を指定して ingest を実行し、pass 以外の判定が 1 つでもあればジョブを失敗させます。

ドキュメント

Iris — 勘に頼ったエージェントのリリースはもうやめよう

CI OpenSSF Scorecard OpenSSF Best Practices npm version License: MIT Install in Cursor Install in VS Code

Iris にエージェントの実行結果を送り、品質、安全性、コストについて評価してもらいましょう。マシン上で完結し、SDKもアカウントも不要です。 多くのエージェントプロジェクトでは、覚えているプロンプトをいくつか実行し、出力を目視して品質を確認しています。Iris はそれを監査可能な数値に置き換えます。エージェントの実行結果はディスク上の SQLite データベースに保存され、組み込みの28個のルールが、PII、プロンプトインジェクション、ハルシネーションの兆候、コストのしきい値、エージェント自身のツール呼び出しを決定論的に採点します。無料で、LLM呼び出しもありません。さらに、評価ごとの厳格なコスト上限を設けたオプションのLLMジャッジが、意味的な判断を担います。すべてのルールは確認・編集できます。監査できないジャッジは、数値を付けただけの勘にすぎないからです。MITライセンス、テレメトリーなし。次のいずれかを有効にしない限り、データがマシンの外に出ることはありません。指定したコレクターにトレースをエクスポートする OpenTelemetry エンドポイント(IRIS_OTEL_ENDPOINT)、独自のキーを使うLLMジャッジ(判定対象のテキストをプロバイダーに送信し、引用チェックでは出力が引用するページを取得します)、またはID、判定結果、ルール名のみを設定したアドレスに送信するWebhook(テキストは送信しません)。

Node.js 22.13以降が必要です。 node --version で確認できます。

The demo: Failures, a failure opened, two runs compared

デモデータベースは scripts/demo-media.mts が記録したものです。ソースはdemo.mp4です。静止画:dashboard-overview.png。

60秒で画面上の失敗を確認

エージェントの接続設定も設定ファイルも不要です。コマンドを1つ実行するだけです。

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

これにより、デモデータベース(小規模なエージェント5つ、2週間分の実行結果、すべてエンジン自身による判定)が作成され、そのデータを使ってダッシュボードが起動します。http://localhost:6920**(初回起動時にブラウザーが自動で開きます)。ダッシュボードは Failures から始まります。失敗した項目が、最悪のもの、新しいものの順に表示され、各カードにはルール名とその根拠が示されます。クリックして確認する価値のある例として、安全性ルールが検出したPII漏えい、フォーラム投稿に隠された指示に要約エージェントが従ったケース、ソース文書にない数値、同じ12個の質問に対する2回の実行を信頼区間付きで比較した結果(Runs)、カスタムルールのデプロイと一時停止の監査行、根拠説明付きのLLMジャッジ採点失敗があります。

デモデータは専用のデータベース(Irisのホームディレクトリにある demo.db — macOS/Linuxでは ~/.iris、Windowsでは %USERPROFILE%\.iris)に保存され、実際のトレースと混ざることはありません。次のコマンド1つですべて削除できます。

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

独自のエージェントを接続する

まず、このマシンでインストールが正常に動作することを確認します。オフラインで実行され、あなたのデータを開くことはありません。

npx @iris-eval/mcp-server --self-test   # exit 0 = healthy

次に、MCPクライアントにIrisを追加します。コマンド1つでクライアント自身の設定ファイルを書き換え、ほかのサーバー設定はすべて保持し、実行したバージョンを固定します。

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を削除できます。すべてのクライアントは1つのデータベースを共有するため、アップグレード後は install --upgrade ですべてをまとめて移行してください(更新)。読み込むにはクライアントを再起動します。

Claude Desktop:ワンクリック。 0.20.0以降の各リリースには iris-eval.mcpb(MCP Bundle)が付属します。最新版をダウンロードして開くと、Claude Desktopにインストールダイアログが表示されます。ダイアログ内の項目はどれも必須ではありません。LLMジャッジ用のAnthropicまたはOpenAIキーは任意で、ダッシュボードは初期状態ではオフになっています。バンドルにはnpmパッケージとその依存関係が含まれているため、ほかにインストールするものはありません。Claude Desktopは、同梱するNodeが22.13以降ならそのNodeで実行します(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 ブロック、VS Codeの servers、Zedの context_servers、CodexのTOML)。コメントやほかのサーバー設定はすべて保持されます。ユニットテストでは、各パスと各形式の書き込み処理がそのドキュメントに準拠していることを確認しています。対象はClaude Desktop、Cursor、Devin Desktop(Windsurf)、Continue、VS Code、Cline、Zed、OpenAI Codex CLIです。出典と確認日を含む各行はこちら:https://iris-eval.com/clients. 手動で設定する場合は、ダッシュボードも含めて次のブロックを1つ追加します。

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

接続すると、クライアントにIrisの12個のツールが表示され、ダッシュボードは http://localhost:6920. で利用できます。次の内容をエージェントに貼り付けてください。

直前のタスクをIrisに記録し、出力を評価してください。

トレースがスコアとともにダッシュボードに表示されます。MCPサーバーをヘッドレスで使う場合は、引数から --dashboard を外してください。同じダッシュボードはいつでも npx @iris-eval/mcp-server --dashboard で開けます。

あらかじめ知っておくとよいことが1つあります。 MCPツールを呼び出すかどうかは、モデルが判断します。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クライアントがinitialize時に受け取る情報を提供します。

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"
  }'

保存された trace_id と評価結果を含む 201 が返ります(--demo モードでは、エンドポイントは 403 で書き込みを拒否するため、デモデータが実データと混ざることはありません)。このエンドポイントは log_trace ツールと同じリクエスト本文を受け付け、ダッシュボードのほかの部分と同じミドルウェアスタックを通ります。デフォルトではループバックにバインドされ、DNSリバインディング対策が有効です。キーを設定した場合はBearer認証も適用されます。知っておくべき事実は2つです。 Irisを --api-key(または IRIS_API_KEY)付きで起動しない限り、認証なしの書き込みを受け付けます。デフォルトでマシン内に限定されるのはループバックへのバインドによるものなので、ループバック以外にバインドする前にキーを設定してください。また、保存される内容は送信されたままです。input と output は、no_pii が後で検出するテキストも含め、送信されたとおりに iris.db に保存されます。仕様、フィールドのリファレンス、エラーの意味についてはdocs/http-ingest.mdを参照してください。

Claude Codeのすべてのターンをキャプチャ(任意)

/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval

別途インストールする2つ目のプラグインです。各ターンのプロンプト、ツール呼び出し(失敗したものも含み、エージェントが受け取ったエラーも記録)、最終回答をプロンプトにひも付けてフックで記録します。そのため、中断されたターンの呼び出しやバックグラウンドのサブエージェントの呼び出しも送信されます。記録内容は 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": []}

サーバー0.16.0以降のHTTP APIを使う薄いクライアントで、サーバーとは独立してバージョン管理されています。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' });

プロバイダークライアントを一度ラップすれば、モデル呼び出しごとに1つのOpenTelemetry GenAIスパンがOTLPエンドポイントに送信され、入力、出力、トークン使用量、ツール呼び出しとともに保存・採点されます。モデルがツールを呼び出すかどうかに左右されないキャプチャです。Pythonクライアントでは wrap_openai / wrap_anthropic、@iris-eval/sdk のVercel AI SDKでは wrapOpenAI、wrapAnthropic、irisMiddleware を使います。どちらもまだ公開されていません(次回の 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")]})

トップレベルの実行ごとに1つのトレースが作成されます(実行本体、モデル呼び出し、ツール呼び出し、グラフノードをGenAIスパンとして記録)。入力、出力、ツール呼び出し、トークン使用量、判定結果が含まれます。Pythonはクライアント内(pip install iris-eval、0.2.0以降)、JavaScriptは @iris-eval/langchain として提供されます(このリポジトリ内にあり、npmには未公開)。どちらも、スクリプト化したモデルを使う実際のLangGraphアプリでCI検証済みです。LangSmith独自のOpenTelemetryエクスポートも同じ方法で検証済みです。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)を使うと、指定した判定でジョブを失敗させ、結果をジョブのサマリーに書き込み、プルリクエストにコメントを1つ投稿します。コメントは更新時に同じ場所で更新されます。uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 と traces: traces.ndjson を使います。docs/ci-gate.md。 4つ目の入口(0.15.0):ダッシュボードポート上の POST /v1/traces は、OpenTelemetry の計装がすでに出力している OTLP/HTTP JSON または protobuf を受け取り、各 OTLP トレースをスパン付きの Iris トレースに変換します(Python SDK のエクスポーターは protobuf のみを扱うため、これが Python 用の入口でもあります)。docs/otel-integration.md;各フレームワーク(Pydantic AI、Google ADK、LangSmith 経由の LangGraph、CrewAI、Python と JavaScript の OpenAI Agents SDK、LlamaIndex、AutoGen、Microsoft Agent Framework、Semantic Kernel、Vercel AI SDK、Mastra)につき1つのレシピを用意し、それぞれフィクスチャで検証しています。docs/otel-recipes.md。ingest は stdin またはファイルから1つの JSON トレース(または1行につき1つの NDJSON)を読み込み、保存し、evaluate_output が実行するものとまったく同じルールで評価し、判定とその根拠を含む JSON 行をトレースごとに出力します。また、判定が --fail-on に一致すると終了コード 1 で終了します。--dataset <id|label> を使うと、このゲートの対象をデータセット内のケースキーに限定できます(POST /api/v1/datasets は実行のケースキーを1つのデータセットに昇格させます)。そのため、ジョブが失敗するのは選択したケースだけです。詳しい手順、終了コード、8つの根拠については docs/ci-gate.md を参照してください。

ルールをコードとして記述する

config.json 内の eval.plugins は、作成したルールを読み込みます。ルールはデフォルトエクスポートが { name, kind, mechanism, version, needs, evaluate(ctx) } である ES モジュールで、ファイルの 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 で終了)。次に、データベースの検索インデックスの状態(完全、バックグラウンド構築でこれまでにインデックス化されたトレース数、またはこの SQLite では FTS5 が利用できないこと)を報告し、データベースのスキーマを読み取ります(このバージョン、または古いリリースに固定された MCP クライアントで開けない場合は、修正方法を示して終了コード 1 で終了)。その後、隔離された一時ホーム内で、ストレージの往復、仕込んだ SSN と安全ルールが検出する仕込んだインジェクション、ダッシュボードの起動、DNS リバインディング対策を確認します。実際のデータベースは読み取るだけで、変更しません。Iris が書き込むものはすべて1つのディレクトリ、Iris ホームに保存されます。デフォルトは ~/.iris(Windows では %USERPROFILE%\.iris)、または IRIS_HOME が指す場所です。iris.db、config.json、custom-rules.json、audit.log、preferences.json とデモファイルはここに保存されます。実際のデータに触れずに Iris を試すには、IRIS_HOME を一時ディレクトリに設定してください。

ツール別の設定
クライアント状態意味確認日
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 に追加し、iris-eval エントリに "type": "stdio" を指定します。Cursor のドキュメントでは必須とされています。

Devin Desktop (Windsurf)

上記の JSON 設定を mcp_config.json に追加します。macOS と Linux では ~/.config/devin/mcp_config.json、Windows では %APPDATA%\devin\mcp_config.json です。

Continue

上記の JSON 設定を独立したファイルとして Continue の mcpServers フォルダーに保存します。すべてのワークスペースでは ~/.continue/mcpServers/iris-eval.json、1つのワークスペースでは .continue/mcpServers/iris-eval.json を使います。

VS Code(ネイティブ MCP)

ワークスペースの .vscode/mcp.json に追加します(注意:VS Code では mcpServers ではなく servers を使います)。

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

Cline

Cline の MCP Servers パネルを開き、Configure MCP Servers を選択して、上記の mcpServers JSON 設定を cline_mcp_settings.json に追加します(~/.cline/data/settings/cline_mcp_settings.json。VS Code、JetBrains、CLI で Cline が共有します)。

Zed

Zed の settings.json に追加します。

{
  "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

上記の mcpServers JSON 設定を ~/.gemini/settings.json に追加します。Gemini CLI は信頼済みフォルダー内でのみ MCP サーバーに接続します。gemini mcp list で iris-eval が Disabled と表示される場合は、そのフォルダーで /permissions を実行してください。

その他の MCP 対応クライアント

Iris は標準的な stdio MCP サーバーです。必要なのは 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 の場合も同じ場所にトレースが保存されますが、パッケージ解決のため起動が遅くなります。

コンテナイメージと、Iris を掲載している MCP ディレクトリ:

Docker Glama Score PulseMCP mcp.so

利用できる機能

トレース記録ツール呼び出しごとのレイテンシ、トークン使用量、USD 建てコストを含む階層的なスパンツリー。SQLite に保存され、すぐに検索できます。
出力評価4カテゴリ(完全性、関連性、安全性、コスト)にわたる28個の組み込みルール。PII 検出(21パターン:SSN、クレジットカード、電話番号、メールアドレス、IBAN、生年月日、MRN、IP、API キー、パスポートに加え、AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean のトークン、URL 内の認証情報、シークレット名を含む代入、PEM 秘密鍵ブロック、シードフレーズ。生年月日、医療記録番号、パスポート、シードフレーズはラベルの近くにある場合のみ検出されます。意図的な仕様です)、プロンプトインジェクション検出(38パターン。フレーズと構造の両方)、スタブ出力検出、幻覚検出(文脈に基づく捏造・矛盾のシグナル25種。エージェントのソース資料と照合するには input を渡します)、そしてエージェントが実際に行ったことを読み取る6つの軌跡ルール:認識されないままのツール呼び出し失敗、同じ呼び出しの繰り返し(呼び出し単位、シーケンスの繰り返し、または tools を送信した場合は対象単位)、ツール自身の JSON Schema に引数が違反し、エージェントが再試行しなかった呼び出し、エージェントが読んだ内容に存在しないファイル、ディレクトリ、URL を回答で引用すること、TOOL RESULT 内に届いた指示に後続の呼び出しで従うこと、ステップ予算を超えるツール呼び出しを要したタスク。さらに2つのルールは、期待値を誰も記述することなく、同じエージェントが同じケースで過去に実行した内容と比較します。過去の実行では一度も行われなかったアクションと、過去のすべての実行で行われたのに今回行われなかったステップです。軌跡は tool_calls として、または OpenTelemetry の TOOL スパンとして渡せます。Zod スキーマでカスタムルールを追加できます。
LLM-as-JudgeAnthropic または OpenAI による任意の意味的スコアリング。API キーは各自で用意してください。テンプレートは7種類。IRIS_RELEVANCE_JUDGE_MODEL を設定すると、answers_the_ask が relevance の判定を要求し、話題から外れた回答を失敗とします。設定しない場合、ルールは質問を語彙的に読み取り、助言を返します。評価ごとの厳格なコスト上限(IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL、デフォルトは $0.25)を設け、評価ごとの料金を結果に表示します。
コストの可視化任意の期間における全エージェントの合計コスト。予算のしきい値を設定し、エージェントの超過支出を検出できます。トークン数とモデルは送信するもののコストを送信しないトレース(OpenTelemetry やフレームワークのトレースの多く)は、モデルの定価で計算され、表示される箇所すべてで推定値と明記されます。組み込みテーブルにないモデルの料金は、config.json 内の pricing.models で設定できます。docs/cost.md。
Web ダッシュボード失敗を最初に表示するリアルタイムのダークモード UI。最悪のものと最新のものが先頭に表示されます。すべてのトレースのテキストを対象とする全文検索付きのトレース可視化、評価結果、コストの内訳、独自のルール、トレース、評価を検索するコマンドパレット(⌘K)を備えています。
ローカル優先すべてのデータはディスク上の SQLite に保存されます。セルフホスト型サーバーにアカウントや登録は不要で、テレメトリーも送信しません。外部への HTTP 通信が発生するのは、任意で有効にした場合のみです。独自の LLM-as-Judge キー、引用の取得、設定した OTel エクスポーター、または設定した Webhook が該当します。

今後の方向性:機能マップ — Iris があらゆる対象について答えられる質問と、持っている情報・不足している情報 — および3つのトラック。

主張ではなく、測定結果

組み込みルールはすべて、公開済みの適合率・再現率・F1と95%信頼区間を持ち、それらはこのリポジトリ内にあるラベル付きコーパス(proof/corpus/)で測定され、1つのコマンド — npm run proof — でオフラインかつキーもモデルも介さずに再生成されます。これらの数値は2種類あり、このページでは決してそれらを合算しません。一部のルールは、失敗そのものを読んでモデルが付けたラベルに対して測定されており、これは検出を測るものです。残りは、独立に適用された各ルール自身の文書化された定義に対して検証され、コードがその数式を実装していることを示すものであって、その数式が失敗を捉えられるかどうかについては何も語りません。proof/RESULTS.md と proof ページが各ルールを区別して示しています。CI はプルリクエストごとに測定を再実行し、コミットされた数値がコードの生成する値と異なれば失敗するため、ルールは数値を伴わずに変更することはできません。数値は iris-eval.com/proof と proof/RESULTS.md にあり、コーパスの作り方、それが何ではないか、区間の読み方は docs/proof.md にあります。コーパスは合成データでモデルがラベル付けしたものであり、人間によるブラインドラベル付けは保留中であると、このページには明記されています。node proof/blind-sample.mjs がそれを決着させる再現可能なサンプルを抽出します。

MCP ツール

Iris は、MCP 互換のエージェントが呼び出せる12個のツールを登録します — トレースとルールのライフサイクル、実行間の比較、LLM-as-judge、意味的引用検証です。

  • 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)。7つのテンプレート: 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。evaluate_with_llm_judge と同じ BYOK 要件です。
  • compare_runs — 変更によってエージェントは悪化したか? 保存された評価の2つの実行を比較します。実行がケースキーを共有する場合はペアの正確検定、そうでない場合は差に対する区間、必要となるケース数を示した正直な「判断できない」、または「マージン内で同等」。各ルールは自身の片側検定を持ち、まとめて補正される(Benjamini–Hochberg)ため、20個のルールが回帰を捏造することはできません
  • compare_traces — エージェントは同じ質問にどれだけ信頼性高く答えるか? ケースごとの合格率と区間、不安定なケースを先頭に、繰り返しを考慮した全体の率
  • evaluate_runs — 実行内のすべてのトレースを今日のルールで再スコアリングして新しい実行にし、ルールの変更がエージェントの変更として読まれないようにします

LLM ジャッジを有効にする(任意。決定的ルールには決して不要)

  1. Anthropic または OpenAI から API キーを取得します。
  2. それを、シェルだけでなく Iris を実行するプロセスの環境に設定します。Claude Code、Claude Desktop、Cursor およびほとんどの MCP クライアント: MCP 設定の iris-eval エントリの "env" ブロック — "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 を起動する前に export します。
  3. MCP セッションを再起動します。実行中のプロセスは、起動後に設定された変数を決して認識しません。
  4. クライアント内から確認します: iris://capabilities を読み、そこで judge.enabled が true でなければなりません。シェルで export されたキーは、その設定に記載されていない限り、クライアントが起動するプロセスには渡されません。マシン上では、npx @iris-eval/mcp-server --self-test がそのシェル用のジャッジ行を出力し、GET /api/v1/health が実行中のダッシュボードで judge.enabled を報告します。
  5. 支出ガード: 各呼び出しは IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL(デフォルト 0.25 USD)で上限が設けられ、最悪ケースがそれを超える場合は支出前に拒否されます。Iris があなたのキーで行うすべてのジャッジ呼び出しは、1つの日次予算 IRIS_LLM_JUDGE_DAILY_BUDGET_USD(デフォルトは UTC 1日あたり 1 USD)を消費します。それを超えると、UTC の深夜まで呼び出しは行われません。Iris はあなたのキーでプロバイダを直接呼び出し、決してプロキシしません。
  6. 任意: IRIS_RELEVANCE_JUDGE_MODEL に価格設定済みのモデル ID(例えば claude-haiku-4-5)を設定すると、answers_the_ask が各回答がその問いに対応しているかをジャッジに尋ね、的外れなものを失敗させます。これは入力を持つ評価ごとに1回のジャッジ呼び出しで、あなたのキーで上記の上限の下で行われます。キーだけでは決して有効になりません。各呼び出しはその入力と出力をモデルのプロバイダに送信し、個人データと認証情報は先に no_pii フラグで置換されます(IRIS_RELEVANCE_JUDGE_REDACT=off はそのまま送信します)。それはその日次予算を消費し、リクエストあたり最大 IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST 回の呼び出し(デフォルト 20)を行います。いずれかを超えると、answers_the_ask は問いを字句的に読み取り、その理由を述べます。

IRIS_OTEL_ENDPOINT が設定されている場合、log_trace の呼び出しは、任意の OpenTelemetry コレクタ(Jaeger、Grafana Tempo、Datadog OTLP、Honeycomb など)へのベストエフォートの OTLP/HTTP JSON エクスポートも行います。docs/otel-integration.md を参照してください。

passed はどのように決定されるか

evaluate_output は score と passed のフラグの両方を返します — それらは異なる問いに答えます。

  • score(0..1)は、実行されたルール全体の加重平均です — 品質の勾配です。
  • passed は出荷/不出荷の判定であり、スコアはそれには決して参照されません。コンポーザは各ルールを、それが行う主張の種類によって読み取ります。あなたが設定したポリシーはゲートします。クリティカルな検出器は拒否権を行使します。問われたが答えられなかったクリティカルなチェックは、判定をクリーンではなく unknown(passed: false)にします。残りのすべての検出器は、出力が悪いという1つの確率に統合され、eval.falsePassCost で述べる損失比と比較衡量されます(デフォルト 1 なので、カットは 0.5)。verdict.basis は決定したレイヤーを、verdict.by はルールを名指しし、verdict.also は同様に決定したであろう後続のすべてのレイヤーを列挙します。interpretations[] は、失敗したルールがなぜ決定しなかったか、どの設定がそれを変えるかを述べ、判定されなかったあらゆる問いと、それを可能にする入力を名指しします。

真正な安全性違反はハードフェイルします。デフォルトでは no_pii、no_injection_patterns、no_blocklist_words が クリティカルルール です。1つが失敗すると、他のルールがどれほど高くスコアしても、評価は passed: false を報告し、レスポンスは critical_failures で原因を名指しします。漏洩した SSN は平均で消し去ることはできません。どの組み込みルールがクリティカルかはデプロイ設定(eval.criticalRules / eval.nonCriticalRules)であり、どの検出器が報告のみを行うか(eval.advisoryRules)も同様です。すべてのルール結果は有効な critical フラグと criticalSource を持ち、list_rules はこのサーバが適用する名簿を報告します。severity: "high" または "critical" でデプロイされたカスタムルールも同様にハードフェイルします。low/medium の重大度はスコアにのみ影響します。すべてのサーフェスで同じように述べられる、知っておくべき境界が1つあります。スキップしたクリティカルルール(コンテキストの欠如、壊れた定義、またはサンドボックス予算で打ち切られた正規表現)は出力を判定しておらず、拒否権を行使しません — そのようなルールはすべて critical_skipped で名指しされます。フェイルクローズしなければならないゲートは、空でない critical_skipped をクリーンではなく unknown として扱います。また、rule_results 内のあらゆる budgetExceeded スキップを同じように扱ってもかまいません。

CI ゲートの場合: eval_type を省略すると、すべてのバンドルが実行されます — 完全性、関連性、安全性、コスト、およびあらゆるカスタムルール — そしてレスポンスは、デフォルトが実行されたことを示す note とともに eval_type: "all" を述べ、さらにバンドルごとの categories マップを返します。各行は state を持ちます。これはそのバンドルが保持するルールについて読まれた判定であり、行が評価を失敗させたルールに対して passed と読まれることは決してありません。判定するものが何もないバンドル(cost_usd なしのコスト、input なしの関連性)は、そこで state: "unknown" と passed: null を報告します — 評価されず、失敗もせず — そして判定に決して数えられません。レスポンスは常に実行された eval_type をエコーするため、ゲートはカバレッジを検証できます。判定には passed をキーにし、より狭い実行を望む場合にのみバンドルを名指ししてください。

カスタムルールの作成

ルールを追加する方法は2つあります。インラインルールは1回の evaluate_output 呼び出しに同乗します(custom_rules、呼び出しあたり最大10個)。それらは選択した eval_type バンドルと並んで発火するか、eval_type: "custom" で単独で発火します。デプロイ済みルールは deploy_rule で一度登録され、Iris ホーム配下の custom-rules.json に永続化され、その evalType の将来のすべての evaluate_output で発火します。定義はどちらの場合も同じ形です。

フィールド必須内容
nameはい1〜80文字。結果では ruleName として現れます
typeはいregex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold のいずれか
configはいその型のキー: 2つの正規表現型には pattern(+ 任意の flags)· min_length / max_length(文字数)· 2つのキーワード型には keywords(+ 任意の threshold、0〜1、デフォルト 1 = すべてが現れなければならない)· json_schema には {} · cost_threshold には USD での max_cost
weightいいえスコアにおける重み。デフォルト 1

deploy_rule は定義を name、任意の description、evalType(completeness · relevance · safety · cost · custom)、および severity で包みます。重大度は失敗が何を意味するかを述べます。low/medium はスコアを下げるだけです。high/critical は加重スコアが何を言おうと評価をハードフェイルします — passed: false、ルールは critical_failures で名指しされます。スキップするルール(cost_usd のない cost_threshold ルール、または 100 ms のサンドボックス予算で打ち切られた正規表現)は出力を判定しておらず、代わりに 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" }
  }
}

レスポンスは永続化されたルールです — delete_rule のために id を保持してください。

{ "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"] されます。組み込みの安全ルール5つすべてに合格し、加重スコアが0.895であっても同様です。正規表現パターンはデプロイ時にReDoSチェックに合格する必要があり、必ずハードな100 msの期限を設けたサンドボックスワーカー内で実行されます。list_rules はデプロイ済みの内容を示します。ダッシュボードのルール作成ツールは、クリックした失敗から同じ形式を作成します。完全なリファレンス、タイプごとのスコアリング、実例については、docs/custom-rules.md を参照してください。

ツールスキーマと設定の全容:iris-eval.com

セルフホストと無料利用

Irisはお使いのマシンまたは独自のインフラストラクチャ上で動作します。オープンソースのコアは無料で、MITライセンスのもと、利用制限もアカウント登録も不要です。ホスト型ストレージ、チームで共有する履歴、アラート機能は検討中であり、開発中ではありません。役立ちそうであれば、hello@iris-eval.com までお知らせください。

2つの約束を守ります。現在無料の機能を有料化することはありません。また、取得する前にコンプライアンス認証を取得済みと主張することはありません。

例

コミュニティ

設定とセキュリティ

CLI引数

フラグデフォルト説明
--transportstdioトランスポートの種類:stdioまたはhttp
--port3000HTTPトランスポートのポート
--db-path~/.iris/iris.dbSQLiteデータベースのパス
--config~/.iris/config.json設定ファイルのパス
--api-key—HTTP認証用APIキー(トランスポートとダッシュボード。POST /api/v1/tracesを含む)
--dashboardfalseWebダッシュボードを有効化します。また、POST /api/v1/traces ingestエンドポイントを起動する唯一の方法です。--transport httpとともに暗黙的に起動することはありません
--dashboard-port6920ダッシュボードのポート
--dashboard-host127.0.0.1ダッシュボードのバインドアドレス。デフォルトはループバックです。--api-keyが設定されていない場合、ダッシュボードには認証がないため、ループバック以外にバインドするとトレース履歴全体が公開されます
--demofalseデモ用データベース(実際のトレースとは別)を作成し、それを使ってダッシュボードを提供します
--demo-clearfalseデモ用データベースを削除して終了します
--self-testfalse分離された一時ホームディレクトリでオフラインインストール診断を実行して終了します(0 = 正常、1 = チェック失敗)。設定済みのデータベースも読み取り専用で確認し、このバージョンまたは固定されたMCPクライアントで開けない場合は失敗します
--purgefalse設定済みデータベースから保存済みのトレース、スパン、評価をすべて削除し、ファイルを圧縮して先行書き込みログを切り詰め、削除したテキストがディスク上に残らないようにして終了します。デプロイ済みルール、監査ログ、設定は保持されます。取り消しはできません。実行中のIrisサーバーを先に停止してください。ファイルはインプレースで圧縮されます。--demo、--demo-clear、--self-testとの併用は拒否されます
--version—バージョンのみ(例:1.2.3)を標準出力に表示して、終了コード0で終了します。Irisのホームディレクトリ内は何も読み取りません

3つのコマンドはそれぞれ独自の引数を受け取り、実行後に終了します。iris-eval ingestはファイルまたは標準入力からトレースを読み込み(サーバー不要のCIゲート)、iris-eval export traces|evaluations --format csv|jsonlはダッシュボードのリストと同じフィルターを適用した保存データを標準出力または--outに書き込み(docs/api-reference.md)、iris-eval install <client>はIrisをMCPクライアントの設定に書き込みます。--uninstallは削除、--listはこのマシンで見つかったクライアントと、それぞれが実行するIrisを表示、--upgradeはIrisを実行するすべてのクライアントをこのバージョンに切り替えます(独自のエージェントを接続する、更新)。いずれもサーバーを起動しません。

config.jsonはIrisの起動時に検証されます。 Irisが読み取らないキー(eval.critcalRulesのようなタイプミスや、別のツール用のキー)、または型が正しくない値があると、完全なキー名、最も可能性の高い意図したキー、または期待される型を示す1文とともに起動が拒否されます。ファイル内の内容が黙って無視されることはありません。

環境変数

すべての変数は--helpに記載されています。CLIフラグと環境変数の両方が設定されている場合は、CLIフラグが優先されます。

VariableDescription
IRIS_TRANSPORTトランスポートの種類(stdio または http)
IRIS_HOSTHTTP トランスポートのバインドアドレス(デフォルト 127.0.0.1)
IRIS_PORTHTTP トランスポートのポート(1-65535、デフォルト 3000)
IRIS_HOMEユーザーごとのすべてのファイルを格納するディレクトリ:config.json、iris.db、custom-rules.json、audit.log、preferences.json(デフォルト ~/.iris)
IRIS_DB_PATHSQLite データベースのパス(DB のみについて IRIS_HOME を上書き)
IRIS_SQLITE_DRIVERデータベースを保持する SQLite ドライバー:native(better-sqlite3、デフォルト)または node(Node 組み込みの node:sqlite、Node 22.13+)。未設定の場合は native。ネイティブモジュールを読み込めない場合(またはこの Node で異常終了するビルドの場合)、Iris は警告を一度だけ出して組み込みドライバーにフォールバックします
IRIS_SEARCH_BUDGET_MS1 回のトレース検索(q)が、見つかった時点までの一致結果と search.complete: false を返すまでに読み込める時間(ミリ秒、50~60000、デフォルト 1000)。検索中は読み込みの間、ほかのリクエストが待たされるため、これが待ち時間の上限にもなります。また、config.json の storage.searchBudgetMs
IRIS_SEARCH_INDEXon(デフォルト)または off。off はトレースの全文検索インデックスを保持しません。書き込み時にはトレースだけを保存し、それ以外は行いません。トレース検索(q)では、IRIS_SEARCH_BUDGET_MS 内に新しいものから順にトレース自体を読み込むため、大規模なストアでは一致結果の一部だけを返すことがあります(search.complete: false)。無効にすると、データベースに保持されていたインデックスが削除されます。再度有効にすると、新しいインデックスがバックグラウンドで作成されます。また、config.json の storage.searchIndex
IRIS_LOG_LEVELログレベル:debug、info、warn、error
IRIS_DASHBOARDtrue/1/yes/on は Web ダッシュボードを有効にします。false/0/no/off は無効にします(config.json の dashboard.enabled も上書き)
IRIS_DASHBOARD_PORTダッシュボードのポート(1-65535、デフォルト 6920)
IRIS_WEBHOOK_URLmoment 発生時に実行される webhook の送信先(config.json の notify.webhook にマージされます(docs/webhooks.md)
IRIS_WEBHOOK_SECRETwebhook の署名キー(任意の文字列、または whsec_ + base64)。iris 形式では、キーがないと起動できません
IRIS_DASHBOARD_HOSTダッシュボードのバインドアドレス(デフォルト 127.0.0.1)
IRIS_API_KEYHTTP 認証用の API キー。HTTP トランスポートまたはダッシュボードをループバック以外(0.0.0.0、LAN アドレス、コンテナ)にバインドする場合に必須です。設定されていない場合、サーバーは起動を拒否します
IRIS_API_KEY_FILE内容の前後の空白を除去した値を API キーとして使うファイルのパス。Docker や Kubernetes でマウントするシークレットファイルの方式で、キーを環境変数ブロックに置かずに済みます。IRIS_API_KEY とどちらか一方だけを設定してください
IRIS_ALLOW_UNAUTHENTICATED意図的にキーなしでループバック以外のアドレスにバインドするには、1 に設定します(起動拒否を解除します。その場合、ネットワークが境界になります)
IRIS_ALLOWED_ORIGINSカンマ区切りのオリジン許可リスト。ダッシュボード:CORS ヘッダー(http://localhost:* などの glob に対応)。HTTP トランスポート:DNS リバインディング対策の完全一致 Origin 許可リスト(glob は無視されます。サーバー自身のループバックオリジンは常に許可されます)
IRIS_MAX_INPUT_ELEMENTS検証前に 1 つの入力に含められる配列要素とオブジェクトキーの最大数(整数、デフォルト 100000):すべてのトランスポートにおけるツール呼び出しの引数、およびダッシュボードポートのリクエスト本文(API の JSON 本文と POST /v1/traces、JSON または protobuf)が対象です。上限を超えたツール呼び出しにはエラー結果が返され、本文は 413。デフォルト値は、リクエスト全体が 1 MB に達する場合も含め、測定した正当な JSON 入力をすべて許容します。POST /v1/traces の protobuf 本文には独自の上限があり、security.requestSizeLimit 5 バイトごとに 1 要素(1 MB で 209,716 個)、またはこの設定がそれより大きい場合はその値となります。そのため、リクエストサイズ内のエクスポーターのバッチが要素数の多さを理由に拒否されることはありません(実測した最も密度の高いエクスポーター本文では 7.5 バイトごとに 1 要素です)。コレクターのより大きなバッチに合わせて requestSizeLimit を引き上げると、この上限も引き上がります。また、config.json の security.maxInputElements
IRIS_MAX_TOOL_INPUT_ELEMENTS0.21.0 より前の IRIS_MAX_INPUT_ELEMENTS の名前。新しい名前が未設定の場合に読み込まれます(同様に config.json の security.maxToolInputElements)
IRIS_NO_AUTO_LAUNCH初回起動時のダッシュボード自動起動を無効にするには、1 に設定します
IRIS_ANTHROPIC_API_KEYprovider=anthropic を使う evaluate_with_llm_judge + verify_citations で必須
IRIS_OPENAI_API_KEYprovider=openai を使う evaluate_with_llm_judge + verify_citations で必須
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVALLLM judge の呼び出しごとのハードコスト上限(デフォルト 0.25)。max_cost_usd で呼び出しごとに引き下げられますが、引き上げることはできません
IRIS_RELEVANCE_JUDGE_MODEL価格設定済みの judge モデル ID(例:claude-haiku-4-5)。設定され、該当プロバイダーのキーがある場合、answers_the_ask は入力を伴うすべての評価でこの LLM judge に問い合わせ、関連性の判定結果に基づいて判定します。評価ごとに judge を 1 回呼び出し、上記のコスト上限と以下の 2 つの制限が適用されます。このような評価では、入力と出力がそのモデルのプロバイダー(Anthropic または OpenAI)にあなたのキーを使って送信されます。送信前に、no_pii フラグが付いた個人データと認証情報は置き換えられます。未設定(デフォルト)の場合、answers_the_ask は質問を語彙的に読み取って助言するだけで、何も送信しません(docs/llm-as-judge.md)
IRIS_LLM_JUDGE_DAILY_BUDGET_USDテナントごとに、UTC 日単位で judge 呼び出し全体が使用できる金額(デフォルト 1):関連性 judge、evaluate_with_llm_judge、verify_citations で共有されます。データベースに保存されるため、再起動してもリセットされません。最悪の場合のコストが残額内に収まる場合にのみ呼び出しが行われます。上限を超えると、answers_the_ask は質問を語彙的に読み取り(judge.withheld: "daily_budget")、judge ツールは IRIS_BUDGET_EXCEEDED を返します(引用、daily_budget_reached)。0 はすべての呼び出しを停止します
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD0.21.0 より前の IRIS_LLM_JUDGE_DAILY_BUDGET_USD の名前。関連性 judge のみを制限していた名前です。新しい名前が未設定の場合に読み込まれ、以降はすべての judge 呼び出しを制限します。サーバーは起動時にその旨を通知します
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST1 つのリクエストで実行できる関連性 judge の呼び出し回数(デフォルト 20):OTLP バッチまたは evaluate_runs の再スコアリングでは、最初の 20 件のトレースを judge で評価し、残りは語彙的に読み取ります(judge.withheld: "request_cap")
IRIS_RELEVANCE_JUDGE_REDACTon(デフォルト):入力と出力に含まれる各スパンの no_pii フラグ(個人データと認証情報)は、関連性 judge に送信する前に [REDACTED:<kind>#<n>] マーカーに置き換えられます。off はそのまま送信します
IRIS_CITATION_ALLOW_FETCHverify_citations での送信 HTTP を許可するには、1 に設定します(デフォルトでは無効)。ツール引数で呼び出しごとに無効にはできますが、有効にはできません
IRIS_CITATION_DOMAINSverify_citations 用のカンマ区切りホスト名許可リスト(サフィックス一致)。ツール引数で範囲を狭めることはできますが、追加はできません
IRIS_CITATION_MAX_COST_USD_TOTAL1 回の verify_citations 呼び出しで judge 呼び出しに使用できる最大額(デフォルト 1)。max_cost_usd_total で呼び出しごとに引き下げられますが、引き上げることはできません
IRIS_OTEL_ENDPOINTこのコレクター URL へのベストエフォートの OTLP/HTTP JSON トレースエクスポートを有効にします
IRIS_OTEL_SERVICE_NAMEOTel エクスポート用の service.name リソース属性(デフォルト iris-eval)
IRIS_OTEL_HEADERSOTel エクスポート用のカンマ区切り k=v ヘッダー(例:authorization=Bearer abc)
IRIS_OTEL_TIMEOUT_MSエクスポートごとのタイムアウト(デフォルト 15000)
RATE_LIMIT_SALTWeb サイト専用 — iris-eval.com のプレイグラウンドのレート制限で保持されるアドレスハッシュにソルトを加えます。サーバーがこれを読み取ることはありません

セキュリティ

HTTP トランスポートを使用する場合、Iris には次の機能が含まれます。

  • タイミングセーフな比較による API キー認証(API クライアントには Bearer、ブラウザーからのダッシュボードへのサインインには ?key=)
  • デフォルトでは CORS を localhost に制限
  • クライアントアドレスおよび分単位のレート制限:ダッシュボード API へのリクエストは 600 件(security.rateLimit.api)、MCP エンドポイントへのリクエストは 20 件(security.rateLimit.mcp)。どちらも config.json で設定します。MCP リクエストが上限を超えると、キー名を示す JSON-RPC エラーが返されます
  • Helmet セキュリティヘッダー
  • すべてのルートで Zod 入力検証
  • カスタム eval ルール用の ReDoS セーフな正規表現
  • すべてのトランスポートでリクエストサイズ上限を 1 MB に統一(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 はキーを HttpOnly、SameSite=Lax のセッション Cookie と交換し、アドレスバーからキーを削除した同じページにリダイレクトします。セッションなしで開いたページにはサインインフォームが表示され、同じ交換処理が行われます。キーがブラウザーに保存されることはありません。セッションはサーバープロセス内にのみ保持されます(同時に有効なセッションは最大 256 件。すべてが有効な状態でサインインしようとすると、既存のセッションを追い出すのではなく拒否されます)。

本番環境

複数のキーと、途切れのないローテーション。 config.json の security.apiKeys には、追加のキーを任意の数だけ設定できます。各キーには id と、keyFile(内容の前後の空白を除去した値をキーとして使うファイル)または keyHash(キーの sha256 形式の 16 進数。設定ファイルにシークレットを含めずに済みます — 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 経由でもブラウザーのサインイン経由でも認証に使えます。起動ログには ID が記録されます。security.rateLimit.mcpKeyBy: "apiKey" を設定すると、MCP エンドポイントの分単位の予算はクライアントアドレスごとではなくキーごとに計算されるため、同じアドレスの背後にいる複数のエージェントがそれぞれ独自の分単位の予算を利用できます。

複数のクライアント。 --transport http は、同じアドレスで任意の数の MCP クライアントを処理できます。各 initialize は、1 つのエンジンとストアを共有しながら、それぞれ独自のセッションを開き、同時に最大 256 セッションまで利用できます。stdio では各クライアントが独自のサーバープロセスを起動し、それらのプロセスは Iris のホームディレクトリを共有します。あるプロセスでデプロイ、無効化、削除されたルールは 20 ms 以内にほかのすべてのプロセスにも反映され、あるプロセスで書き込まれたラベルはほかのプロセスからすぐに読み取れます。また、2 つのプロセスが同時にルールを変更しても、どちらの変更も失われません。 Iris は、HTTP トランスポートまたはダッシュボードがループバック以外(0.0.0.0、LAN アドレス、コンテナ)にバインドされていて、API キーがない場合、起動を拒否し、IRIS_API_KEY の名前を挙げてその旨を一文で伝えます。これには、イメージの単独の docker run も含まれます。これはコンテナ内で 0.0.0.0 にバインドされます。ループバックには公開ポート経由で到達できないためです。キーなしのループバックは引き続き動作します(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 になります。それ以外の場合は HTTP 503 とともに degraded となり、Docker イメージ独自の HEALTHCHECK がこれを読み取ります。それ以外のすべてには Authorization: Bearer <key> またはブラウザーセッションが必要です。保持期間の処理はすべてのサーバーで実行されます。起動時、サーバーが応答を開始した後、さらに retention.sweepIntervalHours ごとに、retention.days より古いトレースと評価(デフォルトは 30)が削除されます。処理は短い単位で行われ、リクエストを長時間待たせることはありません。--self-test はこのインストールのポリシーを表示し、iris://capabilities / GET /api/v1/capabilities はそれを retention として伝えます。

Webhook は特定のイベントで発火します(0.16.0)。config.json 内の notify.webhook(または IRIS_WEBHOOK_URL と IRIS_WEBHOOK_SECRET)で受信先を指定すると、判定が失敗したとき、重大な検出によって拒否されたとき、コストが外れ値になったとき、ルールの失敗率が変化したとき、またはケースが初めて両方の方法で回答されたときに、Iris は署名付きメッセージを1件送信します。含まれるのは ID、判定、ルール、数値であり、エージェントのテキストは含まれません。Standard Webhooks と GitHub の両方の方式で署名し、バックオフ付きで再試行し、エージェントとルールごとにクールダウンを設けます。評価の妨げにはなりません。Slack と Discord の本文形式は組み込みです。docs/webhooks.md。

ディスク上のデータ

Iris が保存するすべてのデータは、Iris のホームディレクトリ(~/.iris または IRIS_HOME)にあります。iris.db は、各トレースの input と output をそのまま保持します。これには、no_pii が後でフラグを立てるテキストも含まれます。検出機能は、明示的に要求しない限り、テキストを編集しません。config.json 内の storage.redact: "critical_spans" は、各評価の出力を保存し、重大な検出器がフラグを立てたスパンを [REDACTED:<pattern>] に置き換えます(デフォルトでは無効。証拠のオフセットは引き続き呼び出し元が見たテキストを参照します)。書き込みがディスクに反映されるタイミングは storage.synchronous で設定します。デフォルトの normal は各チェックポイントで先行書き込みログを同期するため、Iris がクラッシュしてもデータは失われず、ファイルも破損しません。ただし、停電やオペレーティングシステムのクラッシュでは、最後の同期以降の書き込みが取り消されることがあります。full は各コミットを同期し、停電とクラッシュのどちらが起きても書き込みを保持しますが、書き込みごとに約1.5 ms余分にかかります。起動時と、その後は retention.sweepIntervalHours ごと(デフォルトは 24、0 でタイマーを無効化)に、config.json で設定された retention.days より古いトレースと評価(デフォルトは 30、0 で無効化)が削除され、先行書き込みログがチェックポイント処理されます。保持期間を過ぎても残るものが1つあります。ピン留めされたベースライン実行とその評価です。これは、後続のすべての実行との比較に使われるためです。一部を保持する各削除処理は、実行と件数をログに記録します。実行のピン留めを解除すると、次回の削除処理で削除されます。データセットのケースとラベルはトレースや評価ではないため、削除対象になりません。delete_trace または削除処理によってトレースを削除すると、それに関連付けられたすべての評価のテキスト(出力、期待されるテキスト、ルールメッセージ)が消去され、erased_at が記録されます。判定、スコア、証拠のオフセットは残ります。削除のたびに、処理が戻る前に先行書き込みログがチェックポイント処理されるため、削除されたテキストが iris.db や iris.db-wal から読み取れる状態で残ることはありません(その時点で検索がファイルを読み取っている場合や、別のプロセスが読み書きしている場合、削除は待たずに戻り、処理が完了するとテキストはファイルから消えます)。今すぐすべてを削除するには、サーバーを停止して --purge を実行します。保存されているすべてのトレース、スパン、評価を削除し、データベースを圧縮して先行書き込みログを切り詰め、テキストをディスクから消去します。デプロイ済みルール、監査ログ、設定は保持されます。リリースが既存の iris.db にマイグレーションを適用する前に、ファイルの隣にコピーを作成します(iris.db.<from>-to-<to>.<time>.bak、所有者のみアクセス可能、最新の3つを保持。ダウングレード)。コピーにはトレースがそのまま保存されるため、保持期間の削除処理は retention.days より古いものを削除し、--purge はすべて削除します。サーバーはクライアントへの応答後、専用スレッドでコピーとマイグレーションを実行します。その間に到着したツール呼び出し、リソース読み取り、HTTP リクエストは、それぞれ最大30秒待機した後、サーバーが実行中の処理を説明する文とともに拒否されます(IRIS_STORAGE_ERROR、再試行可能。HTTP 503 と Retry-After)。ヘルスチェックはその間も応答し、アップグレードの進行状況を伝えます。0.19.0 から、各トレースがエージェントループである10万件のトレースを処理した場合、コピーとマイグレーションには約6秒かかりました。iris-eval ingest、--purge、--self-test は、ほかの処理を行う前に引き続きアップグレードします。

Iris は保存データを暗号化しません。iris.db とその先行書き込みログファイルは所有者のみアクセス可能なモード600で作成され、Iris のホームディレクトリはモード700で作成されます(Windows ではファイル ACL が適用されます)。データベースに LLM プロバイダーキーは保存されません。IRIS_ANTHROPIC_API_KEY と IRIS_OPENAI_API_KEY は環境変数から読み取られ、ディスクには書き込まれません。一方、トレースの入力と出力はそのまま保存されるため、Iris のホームディレクトリは暗号化ディスクまたは暗号化ボリュームに置いてください(FileVault、BitLocker、LUKS、または Docker イメージの /data マウント用の暗号化クラウドボリューム)。

エクスポート(ダッシュボードの「Traces」ページと「Evaluations」ページにある Export ボタン、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 が指定された、.npmrc 内の ignore-scripts=true(企業のマシンでよくあります)、または 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 でインストール済みのバージョンを確認できます。

更新

1台のマシン上のすべての MCP クライアントは1つのデータベース(~/.iris/iris.db)を共有し、install によって各クライアントは設定を書き込んだリリースに固定されます。リリースによってデータベースのスキーマが変更されると、そのリリースで最初にファイルを開いたプロセスがアップグレードを行います。その後、古いリリースに固定されたクライアントは起動を拒否します。そのため、アップグレードの前または直後に、すべてのクライアントをまとめて更新してください。

npx -y @iris-eval/mcp-server@latest install --upgrade

このコマンドは、このマシン上で Iris を実行するすべてのクライアント設定を見つけ、各固定バージョンをそのリリースに変更します(--dashboard や env ブロックなど、エントリーに追加した内容は保持します)。より新しいリリースへの固定や、npm パッケージ以外を実行するエントリーには手を加えず、実行した内容を一覧表示します。表示されたクライアントを再起動してください。install --list で各クライアントが実行する Iris を確認できます。

これらのファイル以外にあるインストールは2つあります。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 のホームディレクトリにある iris.db.<from>-to-<to>.<time>.bak です(<from> はファイルのスキーマを最後に変更したリリース、<to> はアップグレードを行ったリリースです。正確なパスは起動時のログに表示されます)。元に戻すには、次の手順を実行します。

  1. すべての MCP クライアントと、データベースを使用するほかの Iris プロセスを停止します。
  2. アップグレード済みのファイルは、後で戻す場合に備えて残します。iris.db を iris.db.upgraded に名前変更し、iris.db-wal と iris.db-shm があれば削除します。
  3. バックアップを iris.db にコピーします。cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db。
  4. 各クライアントを古いリリースに戻します。各クライアントで 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 では Visual Studio の C++ ビルドツール)、npm はビルドエラーを表示し、モジュールをスキップしてインストールを完了します。その後 Iris は Node 組み込みの SQLite で動作し、その旨を通知します。起動時に stderr に理由を示す1行が表示され、--self-test には driver node: better-sqlite3 is not installed … と表示されます。ネイティブドライバーを再び使うには、事前ビルド済みバイナリまたはツールチェーンが利用できる環境にインストールしてください(プロジェクト内では npm install better-sqlite3。グローバルインストールの場合は、ツールチェーンが利用可能になった後に npm install -g @iris-eval/mcp-server を使って Iris を再インストールします)。CI では、変更のたびにネイティブビルドを強制的に失敗させた状態でパッケージ済みサーバーをインストールし、インストールが完了することと、セルフテストで組み込みドライバーを使ってトレースを保存・読み取りできることを必須としています。 Iris はすべてを 1 つの SQLite ファイルに保存し、better-sqlite3(Node とプラットフォームに合わせてダウンロードまたはコンパイルされるネイティブアドオン)で開きます。このモジュールを読み込めない場合、Iris は Node 組み込みの SQLite(node:sqlite、Node 22.13 以降)にフォールバックし、stderr に警告を 1 回出力します。そのため、事前ビルドがない場合は起動が遅くなるだけで、起動に失敗することはありません。Node 24.19 以降のヘッダーを使ってマシン上でコンパイルし、Node 24.19~24.21 で実行する better-sqlite3 についても、読み込む前に同じ処理を行います。この範囲では、そのようなバイナリはステートメントを初めて解放するときにプロセス全体を異常終了させるためです(Assertion failed: (env) != nullptr、nodejs/node#65446)。Node 24.22.0 には修正が含まれており、Iris はそこでバイナリを読み込みます。npm rebuild better-sqlite3 はそれを事前ビルド済みバイナリに置き換えます。これはすべてのバージョンで安全です。IRIS_SQLITE_DRIVER=node は意図的に組み込み版を選択し、native はフォールバックを禁止します。組み込み版は拡張機能の読み込みと trusted_schema を無効にして開きます。読み込み時には Node 自身が stderr に ExperimentalWarning: SQLite is an experimental feature の行を出力し、Iris はそれを抑制しません。--self-test と GET /health は使用中のドライバーを示します。証明ページの数値はすべてネイティブドライバーで測定されており、CI ではテストスイートを両方のドライバーで実行します。

Node.js のバージョン

Iris には Node.js 22.13 以降が必要です。Node 20 は 2026-04-30 にサポート終了となっており、サポート対象外です。Node 18 は 2025 年 4 月にサポート終了となりました。

最低バージョンが 22.0 ではなく 22.13 なのは、node:sqlite を同梱する最初のリリースが 22.13.0 だからです。これにより、サポート対象となるすべての Iris インストールで、2 つ目のストレージドライバーが利用できる最初のバージョンとなります。ネイティブの better-sqlite3 アドオンを読み込めない場合、Iris は起動に失敗するのではなく、Node 組み込みの SQLite にフォールバックします。22.13 より前、そして Node 20 の全期間を通じて、ドライバーは 1 つしかなく、事前ビルドがないと起動できませんでした。

node --version  # Must be v22.13.0 or newer

Windows: cmd /c は不要

Claude Code の /doctor は、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 が役に立ったら、リポジトリへのスターをご検討ください。ほかの人が見つけやすくなります。

Star on GitHub

MIT ライセンス。