Iris
resmiServer evaluasi agen dan observabilitas native MCP dengan pencatatan jejak, evaluasi kualitas output, pelacakan biaya, 12 aturan evaluasi bawaan, dasbor real-time, dan deteksi PII
Apa yang bisa Anda lakukan dengan Iris MCP?
- Catat dan beri skor pada run — Minta asisten Anda mencatat run agen ke Iris dan mengevaluasi output-nya, lalu lihat verdict dan skornya di dasbor.
- Periksa aturan keselamatan dan biaya — Jalankan 28 aturan deterministik bawaan untuk PII, injeksi prompt, penanda halusinasi, dan ambang biaya tanpa panggilan LLM.
- Periksa dan edit aturan — Tampilkan daftar aturan bawaan dan tinjau atau ubah aturan tersebut, karena setiap aturan dapat diperiksa dan diedit.
- Tambahkan aturan kustom — Muat aturan yang Anda tulis sebagai kode melalui
eval.pluginsdiconfig.json, yang dipatok berdasarkan hash file. - Bandingkan run — Buka dua run dengan pertanyaan yang sama secara berdampingan dengan interval di tampilan Runs pada dasbor.
- Jadikan verdict sebagai syarat CI — Jalankan
ingestdengan--evaluate --fail-on anyagar job gagal jika verdict apa pun bukan pass.
Dokumentasi
Iris — berhenti merilis agen berdasarkan firasat
Kirimkan proses agen ke Iris dan minta penilaian atas kualitas, keamanan, dan biayanya — di mesin Anda, tanpa SDK dan tanpa akun. Sebagian besar proyek agen memeriksa kualitas dengan menjalankan beberapa prompt yang diingat lalu menilai hasilnya sekilas. Iris menggantinya dengan angka yang dapat Anda audit: proses agen Anda tersimpan di database SQLite pada disk Anda, 28 aturan bawaan menilainya secara deterministik — PII, injeksi prompt, penanda halusinasi, ambang biaya, dan pemanggilan alat oleh agen itu sendiri — gratis, tanpa pemanggilan LLM, sementara juri LLM opsional dengan batas biaya tegas per evaluasi menangani pertanyaan semantik. Setiap aturan dapat diperiksa dan diedit, karena juri yang tidak dapat Anda audit hanyalah firasat yang diberi angka. Berlisensi MIT, tanpa telemetri. Tidak ada yang meninggalkan mesin Anda kecuali jika Anda mengaktifkan salah satu opsi ini: endpoint OpenTelemetry (IRIS_OTEL_ENDPOINT), yang mengekspor trace ke collector yang Anda tentukan; juri LLM dengan kunci Anda sendiri, yang mengirim teks yang dinilainya ke penyedia tersebut, dan pemeriksaan sitasinya mengambil halaman yang dirujuk oleh keluaran; atau webhook, yang mengirim ID, penilaian, dan nama aturan — tidak pernah teks — ke alamat yang Anda tetapkan.
Memerlukan Node.js 22.13 atau yang lebih baru. Periksa dengan node --version.

Database demo, direkam oleh scripts/demo-media.mts; sumbernya adalah demo.mp4. Gambar diam: dashboard-overview.png.
Kegagalan tampil di layar dalam 60 detik
Tanpa menghubungkan agen, tanpa konfigurasi — cukup satu perintah:
npx @iris-eval/mcp-server --demo
Perintah ini mengisi database demo — lima agen kecil, proses selama dua minggu, semua penilaian berasal dari mesin evaluasi itu sendiri — lalu menyajikan dasbor di http://localhost:6920 (browser Anda terbuka otomatis saat pertama kali dijalankan). Dasbor menampilkan Failures: apa yang gagal, diurutkan dari yang terburuk dan terbaru, setiap kartu menyebutkan aturan dan buktinya. Ada baiknya Anda mengekliknya — kebocoran PII yang tertangkap oleh aturan keamanan, arahan tersembunyi dalam kiriman forum yang dipatuhi peringkas, angka yang tidak pernah disebutkan dokumen sumber, dua proses pada dua belas pertanyaan yang sama dibandingkan dengan interval (Runs), aturan khusus yang diterapkan dan aturan yang dijeda beserta baris auditnya, serta skor juri LLM yang gagal dengan alasannya.
Data demo berada di database tersendiri (demo.db di direktori beranda Iris Anda — ~/.iris di macOS/Linux, %USERPROFILE%\.iris di Windows) dan tidak pernah bercampur dengan trace asli Anda. Hapus semuanya dengan satu perintah:
npx @iris-eval/mcp-server --demo-clear
Hubungkan agen Anda sendiri
Pertama, pastikan instalasi berfungsi di mesin ini — prosesnya berjalan offline dan tidak membuka apa pun milik Anda:
npx @iris-eval/mcp-server --self-test # exit 0 = healthy
Lalu tambahkan Iris ke klien MCP Anda. Satu perintah menulis ke file konfigurasi milik klien, mempertahankan semua server lain di dalamnya, dan mengunci versinya ke versi yang Anda jalankan:
npx -y @iris-eval/mcp-server install claude-code
Klien: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list menampilkan klien yang ditemukan di mesin ini, versi Iris yang dijalankan masing-masing, dan file yang dibacanya; install <client> --uninstall menghapus Iris lagi. Semua klien menggunakan satu database bersama, jadi setelah pemutakhiran, pindahkan semuanya sekaligus dengan install --upgrade (Memperbarui). Mulai ulang klien untuk memuatnya.
Claude Desktop: satu klik. Setiap rilis mulai 0.20.0 menyertakan iris-eval.mcpb, sebuah MCP Bundle: unduh versi terbaru, buka, lalu Claude Desktop akan menampilkan dialog instalasi. Tidak ada yang wajib diisi — kunci Anthropic atau OpenAI untuk juri LLM bersifat opsional, dan dasbor adalah sakelar yang awalnya nonaktif. Bundle ini memuat paket npm beserta dependensinya, jadi tidak perlu memasang apa pun lagi: Claude Desktop menjalankannya dengan Node yang disertakan jika Node tersebut versi 22.13 atau lebih baru (Claude Desktop 1.1.6679 menyertakan 24.13), dan Iris menyimpan trace menggunakan SQLite bawaan Node, di ~/.iris yang sama dengan yang digunakan semua instalasi lainnya. Catatan rilis menjelaskan cara memverifikasi tanda tangan dan atestasi build-nya.
Iris berjalan di klien MCP mana pun, dan setiap klien yang disebutkan memiliki baris yang menjelaskan cara pengujiannya. Diverifikasi pada setiap proses CI: Claude Code, Gemini CLI — klien sebenarnya menjalankan Iris dari konfigurasi yang ditulis oleh penginstal dan melaporkan bahwa koneksi berhasil (claude mcp list, gemini mcp list), di Linux, macOS, dan Windows; hook plugin perekaman Claude Code juga dijalankan melalui skrip sebenarnya. Dikonfigurasi berdasarkan dokumentasi MCP masing-masing klien — penginstal menulis file yang didokumentasikan oleh setiap klien, di jalur yang didokumentasikan dan dalam formatnya sendiri (blok mcpServers, servers milik VS Code, context_servers milik Zed, TOML milik Codex), dengan mempertahankan komentar dan semua server lainnya, dan pengujian unit memastikan setiap jalur dan setiap penulis format sesuai dengan dokumentasi tersebut: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Setiap baris mencantumkan sumber dan tanggal sumber tersebut dibaca: https://iris-eval.com/clients. Jika ingin melakukannya secara manual, gunakan satu blok, termasuk dasbor:
{
"mcpServers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
}
}
}
Klien Anda menampilkan dua belas alat Iris saat terhubung, dan dasbor tersedia di http://localhost:6920. Sekarang tempelkan ini ke agen Anda:
Catat tugas terakhir itu ke Iris dan evaluasi hasilnya.
Trace akan muncul di dasbor beserta skornya. Lebih suka server MCP tanpa antarmuka? Hapus --dashboard dari argumen — Anda dapat membuka dasbor yang sama kapan saja dengan npx @iris-eval/mcp-server --dashboard.
Satu hal yang perlu diketahui sejak awal: alat MCP dipanggil saat model memutuskan untuk memanggilnya. Iris tidak mencegat agen Anda, jadi trace dicatat saat agen meminta Iris mencatatnya — baik karena Anda memintanya maupun karena kode Anda memanggil alat secara langsung. Minta agen Anda untuk “catat ini ke Iris dan evaluasi”, dan agen akan melakukannya. Jika Anda ingin perekaman yang tidak bergantung pada pilihan model, POST /api/v1/traces melakukan hal itu — kode Anda mengirim trace melalui HTTP biasa, tanpa model dalam prosesnya (lihat docs/http-ingest.md). CLI dan hook host dalam peta jalan akan menjadi klien tipis yang menggunakan endpoint yang sama.
Rekam melalui HTTP (tanpa model dalam prosesnya)
Endpoint ingest berada di port dasbor — 6920 secara default, bukan port transport MCP — dan hanya tersedia saat dasbor berjalan. Teruskan --dashboard (atau tetapkan IRIS_DASHBOARD=true); --transport http saja tidak memulainya, dan permintaan ke port transport akan mengembalikan 404. Saat dasbor aktif, apa pun yang dapat mengirim permintaan HTTP bisa mencatat trace — dan secara opsional menjalankan evaluasi deterministik dalam permintaan yang sama. GET /api/v1/capabilities di port yang sama menjelaskan apa yang dapat dinilai server ini, kebutuhan setiap aturan, status juri beserta langkah untuk mengaktifkannya, dan batasannya — objek yang sama dengan yang disediakan oleh resource MCP iris://capabilities — sehingga pemanggil HTTP mendapatkan konteks yang diterima klien MCP saat inisialisasi:
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"
}'
Mengembalikan 201 dengan trace_id yang tersimpan dan hasil evaluasi (dalam mode --demo, endpoint menolak penulisan dengan 403, sehingga data demo tidak pernah bercampur dengan data Anda). Endpoint menerima isi permintaan yang sama dengan alat log_trace dan berada di balik tumpukan middleware yang sama dengan bagian dasbor lainnya: pengikatan loopback dan perlindungan DNS rebinding secara default, serta autentikasi Bearer jika Anda menetapkannya. Dua fakta sederhana tentangnya: endpoint menerima penulisan tanpa autentikasi kecuali Iris dijalankan dengan --api-key (atau IRIS_API_KEY) — pengikatan loopback yang secara default membatasinya ke mesin Anda, jadi tetapkan kunci sebelum mengikatnya di luar loopback; dan data yang disimpannya adalah teks persis seperti yang diterima — input dan output disimpan di iris.db persis seperti yang dikirim, termasuk teks apa pun yang kemudian ditandai oleh no_pii. Kontrak lengkap, referensi kolom, dan semantik kesalahan: docs/http-ingest.md.
Rekam setiap giliran Claude Code (opsional)
/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval
Plugin kedua yang dipasang secara terpisah: hook-nya merekam prompt setiap giliran, pemanggilan alat (termasuk yang gagal, beserta kesalahan yang diterima agen) dan jawaban akhir, dengan kunci berdasarkan prompt, sehingga pemanggilan dari giliran yang terputus dan subagen latar belakang juga dikirim ke iris-eval ingest, secara terpisah, dengan rentang kritis disamarkan dalam teks evaluasi yang disimpan — perekaman yang tidak bergantung pada keputusan model untuk memanggil alat. Giliran yang berakhir dengan kesalahan API disimpan tanpa dinilai; jika model juga mencatat giliran tersebut, kedua trace disimpan dan trace milik plugin diberi nama sesuai nama model. Plugin ini tidak pernah mencetak apa pun, menghalangi proses, atau mengirim apa pun ke mana pun. Memasang iris-eval saja tidak mengubah alur giliran Anda. Batasan dan cara menghapusnya: 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": []}
Klien tipis di atas HTTP API server versi 0.16.0 dan yang lebih baru, dengan versinya sendiri — iris_eval.__version__ dan halaman PyPI mencantumkan versinya, yang berbeda dari versi server: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), sinkron dan asinkron, jawaban bertipe, kalimat server sendiri saat menolak — serta plugin pytest: fixture iris dan assert_iris(output, expect="pass") yang memeriksa status penilaian. packages/python/README.md.
Catat setiap pemanggilan OpenAI dan 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' });
Bungkus klien penyedia sekali saja, lalu setiap pemanggilan model menjadi satu span OpenTelemetry GenAI yang dikirim ke endpoint OTLP, disimpan bersama input, output, penggunaan token, dan pemanggilan alatnya, lalu dinilai: perekaman yang tidak bergantung pada model untuk memanggil alat. wrap_openai / wrap_anthropic di klien Python; wrapOpenAI, wrapAnthropic dan irisMiddleware untuk Vercel AI SDK di @iris-eval/sdk. Keduanya belum dipublikasikan (rilis iris-eval berikutnya di PyPI; @iris-eval/sdk dibuat dari sumber hingga rilis npm pertamanya). Stream, helper stream SDK, dan pemanggilan alat tercakup, klien asli tidak diubah, dan jika Iris tidak aktif, pemanggilan tetap berjalan — packages/sdk/README.md, packages/python/README.md.
Nilai setiap proses LangChain dan LangGraph
from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})
Setiap proses tingkat teratas menjadi satu trace (proses itu, pemanggilan modelnya, pemanggilan alatnya, dan node grafnya sebagai span GenAI) beserta input, output, pemanggilan alat, penggunaan token, dan penilaian. Python di klien (pip install iris-eval, 0.2.0 dan yang lebih baru), JavaScript sebagai @iris-eval/langchain (di repositori ini, belum dipublikasikan ke npm). Keduanya dibuktikan di CI menggunakan aplikasi LangGraph sungguhan dengan model berskrip; ekspor OpenTelemetry bawaan LangSmith juga dibuktikan dengan cara yang sama — docs/otel-recipes.md.
Gerbang CI, tanpa server
npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any
any menggagalkan job untuk setiap penilaian yang bukan lulus: kegagalan, serta penilaian yang belum diperiksa. Sebagai gantinya, tentukan satu dasar (--fail-on detector_veto) agar hanya penilaian berdasarkan dasar itu yang menggagalkan job.
Atau gunakan GitHub Action (0.16.0), yang menggagalkan job untuk penilaian yang Anda tentukan, menulis tanda terima ke ringkasan job, dan mengirimkannya sebagai satu komentar pull request yang diperbarui di tempat: uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 dengan traces: traces.ndjson — docs/ci-gate.md.
Pintu keempat (0.15.0): POST /v1/traces pada port dashboard menerima JSON atau protobuf OTLP/HTTP yang sudah dihasilkan oleh instrumentasi OpenTelemetry Anda (exporter SDK Python hanya berbicara protobuf, jadi ini juga pintu untuk Python), dan setiap trace OTLP menjadi trace Iris beserta span-nya — docs/otel-integration.md; satu resep untuk setiap framework (Pydantic AI, Google ADK, LangGraph via LangSmith, CrewAI, OpenAI Agents SDK dalam Python dan JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK, dan Mastra), masing-masing dibuktikan dengan fixture, di docs/otel-recipes.md. ingest membaca satu trace JSON (atau NDJSON, satu per baris) dari stdin atau file, menyimpannya, mengevaluasinya dengan aturan yang persis sama seperti yang dijalankan evaluate_output, mencetak satu baris JSON per trace berisi verdict dan dasarnya, lalu keluar dengan kode 1 jika verdict cocok dengan --fail-on. --dataset <id|label> membatasi gate tersebut hanya pada kunci kasus dalam dataset (POST /api/v1/datasets mempromosikan kunci kasus dari suatu run menjadi satu dataset), sehingga job hanya gagal pada kasus yang Anda pilih. Resep lengkap, kode keluar, dan delapan dasar verdict tersedia di docs/ci-gate.md.
Tulis aturan sebagai kode
eval.plugins di config.json memuat aturan yang Anda tulis — modul ES dengan ekspor default berupa { name, kind, mechanism, version, needs, evaluate(ctx) } — yang dipatok berdasarkan sha256 file, sehingga jika file berubah sejak dipatok, startup akan ditolak alih-alih menjalankannya. Plugin yang dimuat berjalan seperti aturan bawaan dan ditampilkan di list_rules di bawah plugins. Kontrak, resep hash, dan nilai yang boleh dikembalikan plugin: docs/plugins.md.
Gunakan engine dalam proses Anda sendiri
Engine evaluasi dapat diimpor — tanpa server, tanpa database, tanpa model:
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
Engine yang sama, aturan yang sama, dan composer yang sama dengan yang dijalankan server; builtInRules(), createCustomRule(), compose() dan pembaca akurasi yang dipublikasikan juga diekspor bersamanya.
Klien bertipe untuk rute 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
Satu body untuk setiap pintu: inilah yang diterima oleh log_trace dan iris-eval ingest. Penolakan akan melempar IrisClientError dengan kalimat dan status dari server itu sendiri. Kedua subpath diperiksa dari tarball yang dikemas pada setiap build.
Verifikasi instalasi Anda
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 terlebih dahulu membuat home Iris jika belum ada dan memeriksa apakah home tersebut dapat ditulisi (keluar dengan kode 1 dan menyebutkan path jika tidak), melaporkan lokasi indeks pencarian database Anda (utuh, jumlah trace yang telah diindeks oleh build latar belakang sejauh ini, atau tidak ada FTS5 pada SQLite ini), membaca skema database Anda (keluar dengan kode 1 beserta perbaikannya jika versi ini atau klien MCP yang dipatok ke rilis lebih lama tidak dapat membukanya), lalu menjalankan pemeriksaannya — round-trip penyimpanan, SSN dan injeksi yang sengaja ditanam dan tertangkap oleh aturan keselamatan, startup dashboard, serta perlindungan DNS rebinding — di dalam home sementara yang terisolasi. Database Anda yang sebenarnya hanya dibaca, tidak pernah diubah. Semua yang ditulis Iris berada di satu direktori, home Iris Anda: ~/.iris secara default (%USERPROFILE%\.iris di Windows), atau di mana pun IRIS_HOME mengarah. Di sanalah iris.db, config.json, custom-rules.json, audit.log, preferences.json dan file demo berada; arahkan IRIS_HOME ke direktori sementara untuk mencoba Iris tanpa menyentuh data Anda yang sebenarnya.
Penyiapan per alat
| Klien | Status | Artinya | Baca |
|---|---|---|---|
| Claude Code | terverifikasi | sebuah pengujian menjalankan klien sebenarnya pada setiap proses CI | 2026-09-25 |
| Claude Desktop | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Cursor | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Devin Desktop (Windsurf) | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Continue | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| VS Code | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Cline | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Zed | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| OpenAI Codex CLI | diklaim | dikonfigurasi berdasarkan dokumentasi MCP milik klien; path dan format penginstalnya diuji dengan unit test | 2026-09-25 |
| Gemini CLI | terverifikasi | sebuah pengujian menjalankan klien sebenarnya pada setiap proses CI | 2026-09-25 |
Setiap baris beserta hal yang diperiksa: iris-eval.com/clients. Tidak ada klien yang disebut didukung tanpa baris.
npx -y @iris-eval/mcp-server install <client> menuliskan semua ini untuk Anda. Secara manual, untuk setiap klien:
Claude Desktop
Edit file konfigurasi MCP Anda:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Tambahkan konfigurasi JSON di atas, lalu mulai ulang Claude Desktop.
Claude Code
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
Lalu mulai ulang sesi (/clear atau jalankan ulang) agar alat dimuat.
Catatan Windows: Jangan gunakan wrapper
cmd /c— wrapper ini menyebabkan masalah penguraian path. Perintahnpxdapat digunakan langsung.
Cursor
Tambahkan konfigurasi JSON di atas ke ~/.cursor/mcp.json (setiap proyek) atau .cursor/mcp.json di ruang kerja, dengan "type": "stdio" pada entri iris-eval — dokumentasi Cursor menyatakannya wajib.
Devin Desktop (Windsurf)
Tambahkan konfigurasi JSON di atas ke mcp_config.json: ~/.config/devin/mcp_config.json di macOS dan Linux, %APPDATA%\devin\mcp_config.json di Windows.
Continue
Simpan konfigurasi JSON di atas sebagai file tersendiri di folder mcpServers milik Continue: ~/.continue/mcpServers/iris-eval.json (setiap ruang kerja) atau .continue/mcpServers/iris-eval.json di salah satunya.
VS Code (MCP native)
Tambahkan ke .vscode/mcp.json di ruang kerja Anda (catatan: VS Code menggunakan servers, bukan mcpServers):
{
"servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"]
}
}
}
Cline
Buka panel MCP Servers Cline → Configure MCP Servers, lalu tambahkan konfigurasi JSON mcpServers di atas ke cline_mcp_settings.json (~/.cline/data/settings/cline_mcp_settings.json, yang digunakan bersama oleh Cline di VS Code, JetBrains, dan CLI).
Zed
Tambahkan ke settings.json Zed:
{
"context_servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"],
"env": {}
}
}
}
OpenAI Codex CLI
Tambahkan ke ~/.codex/config.toml:
[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]
Gemini CLI
Tambahkan konfigurasi JSON mcpServers di atas ke ~/.gemini/settings.json. Gemini CLI hanya terhubung ke server MCP di folder yang dipercayainya: jika gemini mcp list menampilkan iris-eval sebagai Disabled, jalankan /permissions di folder tersebut.
Apa pun yang mendukung MCP
Iris adalah server MCP stdio standar — satu perintah npx @iris-eval/mcp-server, tanpa SDK, tanpa perubahan kode. Jika klien Anda mendukung MCP, klien tersebut mendukung Iris. Format konfigurasi klien dapat berubah; jika ragu, periksa dokumentasi MCP klien Anda dan arahkan ke perintah tersebut.
Metode Instalasi Lainnya
# 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
Tips: Instalasi global (
npm install -g) menyimpan trace secara persisten di~/.iris/iris.db. Dengannpx, trace tetap tersimpan di lokasi yang sama, tetapi startup lebih lambat karena resolusi paket.
Image container dan direktori MCP yang mencantumkan Iris:
Yang Anda Dapatkan
| Pencatatan Trace | Pohon span hierarkis dengan latensi per pemanggilan alat, penggunaan token, dan biaya dalam USD. Disimpan di SQLite, dapat dikueri seketika. |
| Evaluasi Output | 28 aturan bawaan dalam 4 kategori: kelengkapan, relevansi, keselamatan, biaya. Deteksi PII (21 pola: SSN, kartu kredit, telepon, email, IBAN, DOB, MRN, IP, kunci API, paspor, serta token AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean, kredensial di dalam URL, penetapan bernama rahasia, blok kunci privat PEM dan frasa seed; tanggal lahir, nomor rekam medis, paspor, dan frasa seed hanya terpicu jika berada di dekat labelnya, sesuai rancangan), injeksi prompt (38 pola, frasa + struktural), deteksi output stub, deteksi halusinasi (25 sinyal fabrikasi/kontradiksi yang berlandaskan konteks — berikan input untuk mencocokkannya dengan materi sumber agen), dan enam aturan trajektori yang membaca apa yang DILAKUKAN agen: pemanggilan alat gagal yang tidak diakui, pemanggilan berulang (berdasarkan pemanggilan, urutan berulang, atau target setelah Anda mengirim tools), pemanggilan dengan argumen yang ditolak oleh JSON Schema milik alat itu sendiri dan tidak dicoba ulang oleh agen, file, direktori, atau URL yang dikutip dalam jawaban tetapi tidak muncul dalam apa pun yang dibaca agen, instruksi yang datang di dalam HASIL ALAT lalu dipatuhi oleh pemanggilan berikutnya, dan tugas yang memerlukan lebih banyak pemanggilan alat daripada anggaran langkah Anda. Dua aturan lainnya membandingkan suatu run dengan run sebelumnya dari agen yang sama untuk kasusnya, tanpa ada yang menulis ekspektasi: tindakan yang tidak dilakukan oleh run sebelumnya, dan langkah yang dilakukan oleh setiap run sebelumnya tetapi tidak dilakukan oleh run ini. Trajektori dapat diterima sebagai tool_calls atau sebagai span TOOL OpenTelemetry. Tambahkan aturan kustom dengan skema Zod. |
| LLM sebagai Juri | Penilaian semantik opsional melalui Anthropic atau OpenAI — gunakan kunci API Anda sendiri. Tujuh templat. Jika IRIS_RELEVANCE_JUDGE_MODEL disetel, answers_the_ask meminta juri relevance dan menggagalkan jawaban yang melenceng dari topik; tanpanya, aturan membaca permintaan secara leksikal dan memberikan saran. Batas biaya ketat per evaluasi (IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL, default $0.25), harga per evaluasi dicantumkan dalam hasil. |
| Visibilitas Biaya | Biaya agregat semua agen dalam rentang waktu apa pun. Tetapkan ambang batas anggaran. Dapatkan penanda saat agen membelanjakan terlalu banyak. Trace yang mengirim jumlah token dan model tetapi tanpa biaya (sebagian besar trace OpenTelemetry dan framework) diberi harga berdasarkan harga daftar model dan ditandai sebagai estimasi di semua tempat kemunculannya; pricing.models di config.json menetapkan harga untuk model yang tidak tercakup tabel bawaan — docs/cost.md. |
| Dashboard Web | UI mode gelap real-time yang langsung menampilkan kegagalan, dengan yang terburuk dan terbaru lebih dahulu — visualisasi trace dengan pencarian teks lengkap di seluruh teks setiap trace, hasil evaluasi, perincian biaya, dan palet perintah (⌘K) untuk mencari aturan, trace, dan evaluasi Anda sendiri. |
| Lokal sebagai Prioritas | Semuanya tersimpan di SQLite pada disk Anda. Server yang di-host sendiri tidak memerlukan akun atau pendaftaran dan tidak mengirim telemetri. HTTP keluar hanya terjadi jika Anda memilihnya: kunci juri LLM Anda sendiri, pengambilan sitasi, exporter OTel yang Anda konfigurasi, atau webhook yang Anda tetapkan. |
Arah pengembangan selanjutnya: peta kapabilitas — setiap pertanyaan yang dapat diajukan kepada Iris tentang setiap subjek, beserta hal yang dimiliki dan belum dimilikinya — dan tiga jalur.
Terukur, bukan sekadar klaim
Setiap aturan bawaan memiliki presisi, recall, dan F1 yang dipublikasikan beserta interval kepercayaan 95%, diukur pada korpus berlabel yang tersimpan di repositori ini (proof/corpus/) dan dapat dibuat ulang dengan satu perintah — npm run proof — secara offline, tanpa kunci dan tanpa model yang terlibat. Angka-angka tersebut berasal dari dua jenis pengukuran yang berbeda, dan halaman ini tidak pernah menjumlahkannya: sebagian aturan diukur terhadap label yang diberikan model setelah membaca kegagalan itu sendiri, yang mengukur deteksi; sisanya diperiksa berdasarkan definisi terdokumentasinya sendiri, yang diterapkan secara independen, untuk menunjukkan bahwa kode mengimplementasikan rumusnya dan tidak mengatakan apa pun tentang apakah rumus tersebut menangkap kegagalan. proof/RESULTS.md dan halaman bukti menandai setiap aturan. CI mengulangi pengukuran pada setiap pull request dan gagal jika angka yang dikomit berbeda dari hasil yang dihasilkan kode, sehingga aturan tidak dapat berubah tanpa angka-angkanya ikut berubah. Angka-angka tersebut tersedia di iris-eval.com/proof dan di proof/RESULTS.md; cara korpus dibuat, hal-hal yang bukan bagian darinya, dan cara membaca interval dijelaskan di docs/proof.md. Korpus ini sintetis dan diberi label oleh model — pelabelan buta oleh manusia masih menunggu, dan halaman tersebut menyatakannya; node proof/blind-sample.mjs mengambil sampel yang dapat direproduksi untuk menuntaskannya.
MCP Tools
Iris mendaftarkan dua belas alat yang dapat dipanggil oleh agen apa pun yang kompatibel dengan MCP — siklus hidup trace dan aturan, perbandingan antar-run, LLM-as-judge, serta verifikasi kutipan semantik:
log_trace— Catat eksekusi agen dengan span, pemanggilan alat, penggunaan token, dan biaya; teruskanevaluate: trueuntuk menilainya dalam pemanggilan yang samaevaluate_output— Nilai kualitas output berdasarkan aturan kelengkapan, relevansi, keamanan, dan biaya (heuristik, deterministik, gratis)get_traces— Kueri trace tersimpan dengan dukungan pemfilteran, paginasi, dan rentang waktu, serta temukan run saat agen mengatakan sesuatu denganq: pencarian teks lengkap pada input, output, nilai pemanggilan alat, dan metadata, diurutkan berdasarkan peringkat, dengan kata yang cocok ditandailist_rules— Daftarkan aturan evaluasi kustom yang diterapkan (hanya-baca)deploy_rule— Daftarkan aturan evaluasi kustom baru agar dijalankan pada setiapevaluate_outputdalam kategori tersebutdelete_rule— Hapus aturan kustom yang diterapkan (destruktif, idempoten)delete_trace— Hapus satu trace tersimpan berdasarkan ID (destruktif, cakupan tenant)evaluate_with_llm_judge— Evaluasi semantik melalui LLM (Anthropic atau OpenAI). Tujuh templat: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance. Biaya dibatasi, harga per evaluasi diinformasikan. Gunakan kunci API Anda sendiri (IRIS_ANTHROPIC_API_KEYatauIRIS_OPENAI_API_KEY) — Iris tidak memproksi atau meneruskan panggilan LLM.verify_citations— Ekstrak kutipan dari output (bernomor, penulis-tahun, URL, DOI), ambil sumber melalui resolver yang dilindungi dari SSRF dan hanya mengizinkan domain tertentu, lalu gunakan penilai LLM untuk memeriksa apakah setiap sumber benar-benar mendukung klaim yang dikutip. HTTP keluar bersifat opsional. Persyaratan BYOK yang sama sepertievaluate_with_llm_judge.compare_runs— Apakah perubahan membuat agen menjadi lebih buruk? Membandingkan dua run evaluasi tersimpan: uji eksak berpasangan jika run memiliki kunci kasus yang sama, interval selisih jika tidak, jawaban jujur “tidak dapat dipastikan” beserta jumlah kasus yang diperlukan, atau “setara dalam batas margin”. Setiap aturan memiliki uji satu sisinya sendiri, dikoreksi secara bersamaan (Benjamini–Hochberg) agar dua puluh aturan tidak dapat menciptakan regresi semucompare_traces— Seberapa andal agen menjawab pertanyaan yang sama? Tingkat kelulusan per kasus beserta interval, kasus yang hasilnya tidak konsisten ditampilkan lebih dahulu, dan tingkat keseluruhan yang memperhitungkan pengulanganevaluate_runs— Nilai ulang setiap trace dalam sebuah run menggunakan aturan saat ini ke dalam run baru, agar perubahan aturan tidak pernah disalahartikan sebagai perubahan agen
Aktifkan penilai LLM (opsional; aturan deterministik tidak pernah memerlukannya)
- Dapatkan kunci API dari Anthropic atau OpenAI.
- Masukkan kunci tersebut ke lingkungan proses yang menjalankan Iris, bukan hanya ke shell Anda. Claude Code, Claude Desktop, Cursor, dan sebagian besar klien MCP: blok "env" pada entri iris-eval di konfigurasi MCP Anda — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY untuk kunci OpenAI). Docker: -e IRIS_ANTHROPIC_API_KEY=... pada perintah run. HTTP atau CI: ekspor variabel tersebut sebelum memulai iris-eval.
- Mulai ulang sesi MCP. Proses yang sedang berjalan tidak akan melihat variabel yang ditetapkan setelah proses dimulai.
- Konfirmasikan dari dalam klien Anda: baca iris://capabilities — judge.enabled harus bernilai true di sana. Kunci yang diekspor di shell Anda tidak diteruskan ke proses yang dijalankan oleh klien, kecuali konfigurasinya mencantumkan kunci tersebut. Di mesin,
npx @iris-eval/mcp-server --self-testmencetak baris penilai untuk shell tersebut, dan GET /api/v1/health melaporkan judge.enabled pada dasbor yang sedang berjalan. - Batas pengeluaran: setiap pemanggilan dibatasi oleh IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (default 0.25 USD) dan ditolak sebelum ada pengeluaran jika biaya terburuknya akan melampaui batas tersebut. Setiap pemanggilan penilai yang dilakukan Iris menggunakan kunci Anda mengambil dana dari satu anggaran harian, IRIS_LLM_JUDGE_DAILY_BUDGET_USD (default 1 USD per hari UTC); setelah anggaran habis, tidak ada pemanggilan yang dilakukan hingga tengah malam UTC. Iris memanggil penyedia secara langsung dengan kunci Anda dan tidak pernah memproksikannya.
- Opsional: tetapkan IRIS_RELEVANCE_JUDGE_MODEL ke ID model berharga tertentu (misalnya claude-haiku-4-5) agar answers_the_ask meminta penilai memeriksa apakah setiap jawaban menanggapi pertanyaannya, lalu menggagalkan jawaban yang melenceng dari topik. Ini berarti satu pemanggilan penilai per evaluasi yang menyertakan input, menggunakan kunci Anda dan tunduk pada batas di atas; kunci saja tidak akan mengaktifkannya. Setiap pemanggilan mengirim input dan output tersebut ke penyedia model, dengan flag no_pii untuk data pribadi dan kredensial diganti terlebih dahulu (IRIS_RELEVANCE_JUDGE_REDACT=off mengirimkannya apa adanya). Pemanggilan ini menggunakan anggaran harian tersebut dan melakukan paling banyak IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST pemanggilan per permintaan (default 20); jika salah satu batas terlampaui, answers_the_ask membaca pertanyaan secara leksikal dan menjelaskan alasannya.
Jika IRIS_OTEL_ENDPOINT dikonfigurasi, pemanggilan log_trace juga melakukan ekspor OTLP/HTTP JSON best-effort ke kolektor OpenTelemetry mana pun (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, dll.). Lihat docs/otel-integration.md.
Cara passed ditentukan
evaluate_output mengembalikan score dan flag passed — keduanya menjawab pertanyaan yang berbeda:
score(0..1) adalah rata-rata tertimbang dari aturan yang dijalankan — gradien kualitas.passedadalah keputusan boleh/tidaknya rilis, dan skor tidak pernah dipertimbangkan untuk keputusan ini. Komposer membaca setiap aturan berdasarkan jenis klaim yang dibuatnya: kebijakan yang Anda konfigurasikan menjadi gerbang; detektor kritis dapat memveto; pemeriksaan kritis yang diminta tetapi tidak dapat memberikan jawaban membuat keputusan menjadi unknown (passed: false), bukan bersih; setiap detektor lainnya digabungkan menjadi satu probabilitas bahwa output buruk, lalu dibandingkan dengan rasio kerugian yang Anda nyatakan dieval.falsePassCost(default 1, sehingga ambangnya 0.5).verdict.basismenyebut lapisan yang mengambil keputusan danverdict.bymenyebut aturannya, sedangkanverdict.alsomencantumkan setiap lapisan berikutnya yang juga akan mengambil keputusan;interpretations[]menjelaskan mengapa aturan yang gagal tidak mengambil keputusan dan pengaturan mana yang akan mengubahnya, serta menyebut pertanyaan apa pun yang tidak dinilai dan input yang diperlukan agar pertanyaan itu dapat dinilai.
Pelanggaran keamanan yang nyata selalu menyebabkan kegagalan. Secara default, no_pii, no_injection_patterns, dan no_blocklist_words adalah aturan kritis: jika salah satunya gagal, evaluasi melaporkan passed: false terlepas dari seberapa baik skor aturan lainnya, dan respons menyebutkan penyebabnya di critical_failures. SSN yang bocor tidak dapat diimbangi dengan rata-rata. Aturan bawaan mana yang bersifat kritis merupakan pengaturan deployment (eval.criticalRules / eval.nonCriticalRules), begitu pula detektor mana yang hanya melaporkan (eval.advisoryRules); hasil setiap aturan menyertakan flag critical dan criticalSource yang berlaku, dan list_rules melaporkan daftar aturan yang diterapkan server ini. Aturan kustom yang diterapkan dengan severity: "high" atau "critical" menyebabkan kegagalan dengan cara yang sama; tingkat keparahan low/medium hanya memengaruhi skor. Satu batasan yang perlu diketahui, dinyatakan dengan cara yang sama di setiap antarmuka: aturan kritis yang dilewati (konteks tidak tersedia, definisi rusak, atau regex dihentikan karena batas sandbox) belum menilai output dan tidak memveto — setiap aturan semacam itu disebutkan di critical_skipped. Gerbang yang harus gagal secara tertutup memperlakukan critical_skipped yang tidak kosong sebagai unknown, bukan bersih, dan dapat memperlakukan setiap aturan yang dilewati dengan budgetExceeded di rule_results dengan cara yang sama.
Untuk gerbang CI: jika Anda tidak menyertakan eval_type, semua bundel dijalankan — kelengkapan, relevansi, keamanan, biaya, dan aturan kustom apa pun — dan respons menyatakan eval_type: "all" dengan note yang menunjukkan bahwa default dijalankan, serta peta categories per bundel. Setiap baris menyertakan state: keputusan untuk aturan yang dimiliki bundel tersebut, sehingga suatu baris tidak pernah menyatakan lulus jika aturan yang menyebabkan evaluasi gagal dilewati. Bundel yang tidak memiliki apa pun untuk dinilai (biaya tanpa cost_usd, relevansi tanpa input) melaporkan state: "unknown" dan passed: null di sana — tidak dievaluasi, bukan gagal — dan tidak pernah diperhitungkan dalam keputusan. Respons selalu menggemakan eval_type yang dijalankan, sehingga gerbang Anda dapat memverifikasi cakupan; gunakan passed untuk keputusan dan sebutkan bundel hanya jika Anda menginginkan cakupan yang lebih sempit.
Menulis aturan kustom
Ada dua cara untuk menambahkan aturan. Aturan inline disertakan dalam satu pemanggilan evaluate_output (custom_rules, hingga 10 per pemanggilan); aturan tersebut dijalankan bersama bundel eval_type yang Anda pilih, atau sendiri dengan eval_type: "custom". Aturan terpasang didaftarkan sekali dengan deploy_rule, disimpan di custom-rules.json dalam direktori home Iris Anda, dan dijalankan pada setiap evaluate_output berikutnya dari evalType-nya. Bentuk definisinya sama untuk kedua cara:
| Field | Wajib | Keterangan |
|---|---|---|
name | ya | 1–80 karakter; muncul sebagai ruleName dalam hasil |
type | ya | salah satu dari regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold |
config | ya | kunci untuk jenis tersebut: pattern (+ flags opsional) untuk dua jenis regex · min_length / max_length (jumlah karakter) · keywords (+ threshold opsional, 0–1, default 1 = semuanya harus muncul) untuk dua jenis kata kunci · {} untuk json_schema · max_cost dalam USD untuk cost_threshold |
weight | tidak | bobot dalam skor; default 1 |
deploy_rule membungkus definisi dengan name, description opsional, evalType (completeness · relevance · safety · cost · custom), dan severity. Tingkat keparahan menjelaskan arti kegagalan: low/medium hanya menurunkan skor; high/critical menyebabkan evaluasi gagal — passed: false, dengan aturan disebutkan di critical_failures — apa pun skor tertimbangnya. Aturan yang dilewati (aturan cost_threshold tanpa cost_usd, atau regex yang dihentikan karena batas sandbox 100 ms) belum menilai output dan dicantumkan di critical_skipped. Terapkan aturan kritis yang melarang nama host internal dalam apa pun yang dikatakan agen:
{
"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" }
}
}
Responsnya adalah aturan yang tersimpan — simpan id untuk delete_rule:
{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }
Mulai dari evaluate_output berikutnya dengan eval_type: "safety", output yang menyebut db-primary.internal.example akan kembali passed: false dengan critical_failures: ["no_internal_hostnames"] — meskipun kelima aturan keamanan bawaan lolos dan skor tertimbangnya 0.895. Pola regex harus lolos pemeriksaan ReDoS saat deployment dan selalu dijalankan di worker sandbox dengan batas waktu ketat 100 ms. list_rules menunjukkan apa yang di-deploy; penyusun aturan di dasbor membangun bentuk yang sama dari kegagalan yang Anda klik. Referensi lengkap, penilaian per jenis, dan contoh yang dikerjakan: docs/custom-rules.md.
Skema alat dan konfigurasi lengkap: iris-eval.com
Dihosting sendiri dan gratis
Iris berjalan di mesin atau infrastruktur Anda sendiri. Inti sumber terbukanya gratis dan berlisensi MIT, tanpa batas penggunaan dan tanpa akun. Penyimpanan terhosting, riwayat tim bersama, dan pemberitahuan sedang dipertimbangkan, bukan sedang dikembangkan; jika fitur tersebut berguna bagi Anda, beri tahu kami di hello@iris-eval.com.
Dua komitmen tetap berlaku: tidak ada yang gratis hari ini yang akan dipindahkan ke balik paywall, dan tidak ada sertifikasi kepatuhan yang akan diklaim sebelum benar-benar diperoleh.
Contoh
- Penyiapan Claude Desktop — konfigurasi MCP untuk mode stdio dan HTTP
- TypeScript — klien MCP SDK — menghubungkan dan memanggil alat
- Transport HTTP (TS + Python) — kode klien lengkap untuk integrasi bergaya REST
- Agen LangGraph, run dinilai satu per satu (Python) —
IrisCallbackHandlerdi callback graph; CI menjalankan graph yang sama dengan model berskrip - Kru CrewAI melalui OpenTelemetry (Python) — instrumentor OpenInference langsung ke endpoint OTLP Iris, resep CrewAI sebagai skrip
- Agen OpenAI Agents SDK melalui OpenTelemetry (Python) dan (JavaScript), serta agen LlamaIndex — setiap resep berupa skrip yang dijalankan CI terhadap server Iris sungguhan
Komunitas
- GitHub Issues — Laporan bug dan permintaan fitur
- GitHub Discussions — Pertanyaan dan ide
- Mendapatkan bantuan — Tempat bertanya, melaporkan bug, atau melaporkan kerentanan
- Panduan Kontribusi — Cara berkontribusi; AGENTS.md adalah panduan yang sama untuk agen coding
- Tata kelola — Siapa yang memutuskan, bagaimana perubahan diterapkan, dan bagaimana rilis dibuat serta diverifikasi
- HTTP Ingest — Pengambilan trace deterministik melalui
POST /api/v1/traces - Peta kapabilitas — Semua pertanyaan yang dapat diajukan kepada Iris, dan hal-hal yang belum dimilikinya
- Kebijakan versi — Janji setiap nomor versi, dan hal-hal yang harus terpenuhi sebelum 1.0
Konfigurasi & Keamanan
Argumen CLI
| Flag | Default | Deskripsi |
|---|---|---|
--transport | stdio | Jenis transport: stdio atau http |
--port | 3000 | Port transport HTTP |
--db-path | ~/.iris/iris.db | Jalur basis data SQLite |
--config | ~/.iris/config.json | Jalur file konfigurasi |
--api-key | — | Kunci API untuk autentikasi HTTP (transport dan dasbor, termasuk POST /api/v1/traces) |
--dashboard | false | Aktifkan dasbor web. Ini juga satu-satunya cara endpoint ingest POST /api/v1/traces dijalankan — endpoint tersebut tidak pernah dijalankan secara implisit bersama --transport http |
--dashboard-port | 6920 | Port dasbor |
--dashboard-host | 127.0.0.1 | Alamat bind dasbor. Secara default menggunakan loopback — dasbor tidak memiliki autentikasi kecuali --api-key ditetapkan, jadi bind di luar loopback akan mengekspos seluruh riwayat trace Anda |
--demo | false | Isi basis data demo (terpisah dari trace sungguhan Anda) dan sajikan dasbor menggunakan basis data tersebut |
--demo-clear | false | Hapus basis data demo dan keluar |
--self-test | false | Jalankan diagnostik instalasi offline di direktori home sementara yang terisolasi, lalu keluar (0 = sehat, 1 = pemeriksaan gagal). Diagnostik ini juga membaca basis data yang dikonfigurasi dalam mode hanya-baca, dan gagal jika versi ini atau klien MCP yang dipatok tidak dapat membukanya |
--purge | false | Hapus semua trace, span, dan evaluasi yang tersimpan dari basis data yang dikonfigurasi, padatkan file, lalu potong log write-ahead agar teks yang dihapus tidak tertinggal di disk, kemudian keluar. Aturan yang di-deploy, log audit, dan preferensi tetap dipertahankan. Tidak dapat dibatalkan. Hentikan server Iris yang sedang berjalan terlebih dahulu — file dipadatkan di tempat. Menolak untuk digabungkan dengan --demo, --demo-clear, atau --self-test |
--version | — | Cetak versi tanpa hiasan (misalnya 1.2.3) ke stdout lalu keluar dengan kode 0. Tidak membaca apa pun di direktori home Iris Anda |
Tiga perintah menerima argumennya sendiri lalu keluar: iris-eval ingest memuat trace dari file atau stdin (Gerbang CI, tanpa server), iris-eval export traces|evaluations --format csv|jsonl menulis data yang tersimpan, difilter seperti daftar di dasbor, ke stdout atau --out (docs/api-reference.md), dan iris-eval install <client> menulis Iris ke konfigurasi klien MCP — --uninstall menghapusnya, --list menampilkan klien yang ditemukan di mesin ini dan Iris yang dijalankan masing-masing, --upgrade memindahkan setiap klien yang menjalankan Iris ke versi ini (Hubungkan agen Anda sendiri, Memperbarui). Tidak satu pun menjalankan server.
config.json divalidasi saat Iris dimulai. Jika Iris menemukan kunci yang tidak dibacanya — salah ketik seperti eval.critcalRules, kunci dari alat lain — atau nilai dengan tipe yang salah, proses startup ditolak dengan satu kalimat yang menyebutkan kunci lengkap, kunci yang kemungkinan dimaksud, atau tipe yang diharapkan. Tidak ada isi file yang diabaikan secara diam-diam.
Variabel Lingkungan
Setiap variabel didokumentasikan oleh --help. Flag CLI lebih diutamakan daripada variabel lingkungan jika keduanya ditetapkan.
| Variabel | Deskripsi |
|---|---|
IRIS_TRANSPORT | Jenis transport (stdio atau http) |
IRIS_HOST | Alamat bind transport HTTP (default 127.0.0.1) |
IRIS_PORT | Port transport HTTP (1-65535, default 3000) |
IRIS_HOME | Direktori untuk semua file per pengguna: config.json, iris.db, custom-rules.json, audit.log, preferences.json (default ~/.iris) |
IRIS_DB_PATH | Jalur database SQLite (menggantikan IRIS_HOME hanya untuk DB) |
IRIS_SQLITE_DRIVER | Driver SQLite mana yang menyimpan database: native (better-sqlite3, default) atau node (bawaan Node, node:sqlite, Node 22.13+). Jika tidak disetel: native, dan jika modul native tidak dapat dimuat (atau merupakan build yang akan menyebabkan proses berhenti pada Node ini), Iris memberi peringatan sekali lalu beralih ke driver bawaan |
IRIS_SEARCH_BUDGET_MS | Berapa lama satu pencarian trace (q) boleh membaca sebelum menjawab dengan kecocokan yang ditemukan sejauh ini dan search.complete: false, dalam milidetik (50 hingga 60000, default 1000). Pencarian menahan permintaan lain selama membaca, jadi ini juga merupakan waktu terlama permintaan lain harus menunggu. Juga storage.searchBudgetMs di config.json |
IRIS_SEARCH_INDEX | on (default) atau off. off tidak menyimpan indeks teks lengkap untuk trace: penulisan hanya menyimpan trace, tanpa hal lain, dan pencarian trace (q) membaca trace itu sendiri dalam batas IRIS_SEARCH_BUDGET_MS, dari yang terbaru, sehingga pada penyimpanan besar pencarian dapat menjawab dengan sebagian kecocokan (search.complete: false). Menonaktifkannya akan menghapus indeks yang disimpan database; mengaktifkannya kembali akan membuat indeks baru di latar belakang. Juga storage.searchIndex di config.json |
IRIS_LOG_LEVEL | Level log: debug, info, warn, error |
IRIS_DASHBOARD | true/1/yes/on mengaktifkan dasbor web; false/0/no/off menonaktifkannya (juga menggantikan dashboard.enabled di config.json) |
IRIS_DASHBOARD_PORT | Port dasbor (1-65535, default 6920) |
IRIS_WEBHOOK_URL | Penerima webhook yang dipicu pada suatu momen — digabungkan dengan notify.webhook di config.json (docs/webhooks.md) |
IRIS_WEBHOOK_SECRET | Kunci penandatanganan webhook (string apa pun, atau whsec_ + base64); format iris tidak akan berjalan tanpa kunci |
IRIS_DASHBOARD_HOST | Alamat bind dasbor (default 127.0.0.1) |
IRIS_API_KEY | Kunci API untuk autentikasi HTTP. Wajib diisi untuk melakukan bind transport HTTP atau dasbor di luar loopback (0.0.0.0, alamat LAN, container): tanpa kunci ini, server menolak untuk dimulai |
IRIS_API_KEY_FILE | Jalur ke file yang isinya setelah spasi di awal dan akhir dihapus menjadi kunci API — pola file rahasia yang dipasang oleh Docker dan Kubernetes, sehingga kunci tidak pernah berada di blok lingkungan. Setel ini atau IRIS_API_KEY, jangan keduanya |
IRIS_ALLOW_UNAUTHENTICATED | Setel ke 1 untuk sengaja menjalankan bind non-loopback tanpa kunci (membatalkan penolakan; jaringan menjadi batas keamanan Anda) |
IRIS_ALLOWED_ORIGINS | Daftar izin origin yang dipisahkan koma. Dasbor: header CORS (mendukung glob, mis. http://localhost:*). Transport HTTP: daftar izin Origin yang harus cocok persis untuk perlindungan DNS rebinding (glob diabaikan; origin loopback milik server sendiri selalu diizinkan) |
IRIS_MAX_INPUT_ELEMENTS | Jumlah maksimum elemen array dan kunci objek yang boleh dimuat satu input sebelum divalidasi (bilangan bulat, default 100000): argumen pemanggilan tool pada setiap transport, dan isi permintaan pada port dasbor (isi JSON API dan POST /v1/traces, JSON atau protobuf). Pemanggilan tool yang melampaui batas ini menghasilkan respons error; isi permintaan, 413. Default ini mencakup setiap input JSON yang sah berdasarkan pengukuran, bahkan yang memenuhi seluruh permintaan 1 MB. Isi protobuf pada POST /v1/traces memiliki batas tersendiri, yaitu satu elemen per 5 byte security.requestSizeLimit (209,716 pada 1 MB) atau nilai setelan ini jika lebih tinggi, sehingga batch eksportir yang masih dalam batas ukuran permintaan tidak ditolak karena kepadatannya (isi eksportir nyata terpadat yang diukur memuat satu elemen per 7.5 byte); menaikkan requestSizeLimit untuk batch kolektor yang lebih besar juga menaikkan batas ini. Juga security.maxInputElements di config.json |
IRIS_MAX_TOOL_INPUT_ELEMENTS | Nama IRIS_MAX_INPUT_ELEMENTS sebelum 0.21.0, dibaca jika nama baru tidak disetel (dan security.maxToolInputElements di config.json, demikian pula) |
IRIS_NO_AUTO_LAUNCH | Setel ke 1 untuk menonaktifkan peluncuran otomatis dasbor saat pertama kali dijalankan |
IRIS_ANTHROPIC_API_KEY | Wajib diisi oleh evaluate_with_llm_judge + verify_citations dengan provider=anthropic |
IRIS_OPENAI_API_KEY | Wajib diisi oleh evaluate_with_llm_judge + verify_citations dengan provider=openai |
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL | Batas biaya keras per pemanggilan juri LLM (default 0.25). max_cost_usd dapat menurunkannya untuk suatu pemanggilan, tetapi tidak dapat menaikkannya |
IRIS_RELEVANCE_JUDGE_MODEL | ID model juri berbayar (mis. claude-haiku-4-5). Jika disetel, dengan kunci penyedia tersebut, answers_the_ask meminta juri LLM ini pada setiap evaluasi yang membawa input dan menerapkan keputusan relevansinya — satu pemanggilan juri per evaluasi, dalam batas biaya di atas dan dua batas di bawah. Input dan output setiap evaluasi tersebut dikirim ke penyedia model itu (Anthropic atau OpenAI) menggunakan kunci Anda, setelah data pribadi dan kredensial yang ditandai oleh no_pii diganti terlebih dahulu. Jika tidak disetel (default), answers_the_ask membaca permintaan secara leksikal dan memberi saran, tanpa mengirimkan apa pun (docs/llm-as-judge.md) |
IRIS_LLM_JUDGE_DAILY_BUDGET_USD | Jumlah yang boleh dibelanjakan semua pemanggilan juri secara keseluruhan per hari UTC, per tenant (default 1): juri relevansi, evaluate_with_llm_judge dan verify_citations berbagi batas ini. Disimpan di database, sehingga restart tidak mengatur ulang batasnya. Pemanggilan hanya dilakukan jika biaya terburuknya masih sesuai dengan sisa batas; setelah itu, answers_the_ask membaca permintaan secara leksikal (judge.withheld: "daily_budget") dan tool juri menjawab IRIS_BUDGET_EXCEEDED (sebuah kutipan, daily_budget_reached). 0 menghentikan semua pemanggilan |
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD | Nama IRIS_LLM_JUDGE_DAILY_BUDGET_USD sebelum 0.21.0, saat variabel itu hanya membatasi juri relevansi. Dibaca jika nama baru tidak disetel, dan kemudian membatasi setiap pemanggilan juri; server menyatakannya saat startup |
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST | Jumlah pemanggilan juri relevansi yang boleh dilakukan satu permintaan (default 20): batch OTLP atau penilaian ulang evaluate_runs meminta penilaian juri untuk 20 trace pertamanya dan membaca sisanya secara leksikal, dengan judge.withheld: "request_cap" |
IRIS_RELEVANCE_JUDGE_REDACT | on (default): setiap flag no_pii (data pribadi dan kredensial) pada span di input dan output diganti dengan penanda [REDACTED:<kind>#<n>] sebelum dikirim ke juri relevansi. off mengirimkannya apa adanya |
IRIS_CITATION_ALLOW_FETCH | Setel ke 1 untuk mengizinkan HTTP keluar di verify_citations (nonaktif secara default). Argumen tool dapat menonaktifkannya untuk suatu pemanggilan, tetapi tidak dapat mengaktifkannya |
IRIS_CITATION_DOMAINS | Daftar izin nama host yang dipisahkan koma untuk verify_citations (pencocokan sufiks). Argumen tool dapat mempersempitnya, tetapi tidak dapat menambahkan nama host |
IRIS_CITATION_MAX_COST_USD_TOTAL | Jumlah maksimum yang boleh dibelanjakan satu pemanggilan verify_citations untuk pemanggilan juri (default 1). max_cost_usd_total dapat menurunkannya untuk suatu pemanggilan, tetapi tidak dapat menaikkannya |
IRIS_OTEL_ENDPOINT | Aktifkan ekspor trace OTLP/HTTP JSON dengan upaya terbaik ke URL kolektor ini |
IRIS_OTEL_SERVICE_NAME | Atribut resource service.name untuk ekspor OTel (default iris-eval) |
IRIS_OTEL_HEADERS | Header k=v yang dipisahkan koma untuk ekspor OTel (mis. authorization=Bearer abc) |
IRIS_OTEL_TIMEOUT_MS | Batas waktu per ekspor (default 15000) |
RATE_LIMIT_SALT | Hanya situs web — memberi salt pada hash alamat yang disimpan oleh pembatasan laju playground iris-eval.com; server tidak pernah membacanya |
Keamanan
Saat menggunakan transport HTTP, Iris menyertakan:
- Autentikasi kunci API dengan perbandingan yang aman terhadap serangan timing (Bearer untuk klien API; login browser ke dasbor melalui
?key=) - CORS dibatasi ke localhost secara default
- Pembatasan laju per alamat klien dan per menit: 600 permintaan ke API dasbor (
security.rateLimit.api) dan 20 ke endpoint MCP (security.rateLimit.mcp), keduanya diatur dalamconfig.json; permintaan MCP yang melampaui batas mendapat error JSON-RPC yang menyebutkan kuncinya - Header keamanan Helmet
- Validasi input Zod pada semua rute
- Regex aman dari ReDoS untuk aturan eval kustom
- Satu batas ukuran permintaan 1MB pada setiap transport (
security.requestSizeLimit): HTTP menjawab413, stdio menjawab dengan error JSON-RPC dan mempertahankan sesi tetap terbuka - Satu batas 100,000 elemen array dan kunci objek dalam input, dihitung sebelum divalidasi (
security.maxInputElements): argumen pemanggilan tool pada setiap transport menghasilkan respons error jika melampaui batas, sedangkan isi permintaan dasbor atau OTLP menghasilkan413 - Error validasi mengembalikan maksimal 20 masalah beserta jumlah totalnya (
issueCount), sehingga respons tetap kecil betapa pun salahnya permintaan
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard
Jika kunci disetel, klien API — klien MCP, SDK capture, POST /api/v1/traces — mengirim Authorization: Bearer <key>. Untuk membuka dasbor di browser, tambahkan kunci sekali ke URL dasbor mana pun, http://localhost:6920/?key=<api key>: Iris menukarnya dengan cookie sesi HttpOnly, SameSite=Lax lalu mengalihkan ke halaman yang sama dengan kunci dihapus dari bilah alamat. Halaman yang dibuka tanpa sesi menampilkan formulir login yang melakukan pertukaran yang sama. Kunci tidak pernah disimpan di browser, dan sesi hanya hidup di proses server (maksimal 256 sesi aktif sekaligus; login yang mendapati semuanya aktif akan ditolak, bukan menggusur salah satunya).
Produksi
Beberapa kunci, dan rotasi tanpa jeda. security.apiKeys di config.json menampung sejumlah kunci tambahan, masing-masing dengan id dan tepat satu dari keyFile (file yang isinya setelah spasi di awal dan akhir dihapus menjadi kunci) atau keyHash (nilai hex sha256 dari kunci, sehingga file konfigurasi tidak menyimpan rahasia — printf %s "$KEY" | openssl dgst -sha256), serta expiresAt opsional (ISO 8601) yang menentukan kapan kunci berhenti cocok. Untuk melakukan rotasi: tambahkan kunci baru, pindahkan klien Anda, lalu hapus kunci lama. Kunci di config.json dan di file kunci berlaku tanpa restart (0.20.0): pada setiap permintaan, server memeriksa apakah config.json atau file kunci yang dirujuknya telah berubah, dan jika ya, membaca ulang kunci sebelum menjawab. Menghapus kunci dari security.apiKeys, atau menghapus file kuncinya, mencabut kunci tersebut pada permintaan berikutnya: permintaan itu ditolak, dan setiap sesi browser yang dibuka dengan kunci tersebut akan dikeluarkan. config.json yang tidak dapat dibaca (misalnya, karena penulisan belum selesai) akan gagal secara tertutup, dan sampai diperbaiki hanya kunci dari IRIS_API_KEY atau --api-key yang diterima. Kunci di IRIS_API_KEY atau --api-key sendiri, serta status autentikasi aktif atau tidak, tetap hanya berubah setelah restart. Setiap kunci dapat digunakan untuk autentikasi sampai dihapus atau kedaluwarsa, baik melalui jalur Bearer maupun login browser; log startup mencantumkan ID-nya. security.rateLimit.mcpKeyBy: "apiKey" menghitung anggaran per menit endpoint MCP per kunci, bukan per alamat klien, sehingga beberapa agen di balik satu alamat masing-masing mendapat jatah per menit sendiri.
Beberapa klien. --transport http melayani sejumlah klien MCP di satu alamat: setiap initialize membuka sesinya sendiri melalui satu engine dan penyimpanan yang sama, hingga 256 sesi sekaligus. Dengan stdio, setiap klien memulai proses servernya sendiri, dan proses-proses tersebut berbagi direktori utama Iris: aturan yang diterapkan, dinonaktifkan, atau dihapus melalui satu proses berlaku di semua proses lain dalam 20 ms; label yang ditulis melalui satu proses langsung dapat dibaca oleh proses lain; dan jika dua proses mengubah aturan pada saat yang sama, tidak ada perubahan yang hilang.
Iris menolak untuk memulai ketika transport HTTP atau dasbor terikat di luar loopback — 0.0.0.0, alamat LAN, kontainer — tanpa kunci API, dan menyatakannya dalam satu kalimat yang menyebut IRIS_API_KEY. Ini termasuk docker run image yang berdiri sendiri, yang mengikat 0.0.0.0 di dalam kontainer karena loopback tidak dapat dijangkau melalui port yang dipublikasikan. Loopback tanpa kunci tetap berfungsi (dengan peringatan pada transport HTTP): batas mesin adalah kontrol paparan di sana.
# 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
Terbuka secara desain, pada server berkunci: GET /health pada transport dan GET /api/v1/health pada dasbor menjawab tanpa kunci dan di luar semua batas laju, dengan satu bentuk: status, versi, waktu aktif, driver SQLite, checks untuk penyimpanan, file aturan yang diterapkan dan migrasi (diterapkan terhadap yang diketahui), status indeks pencarian (search: siap, atau sejauh mana proses build telah berjalan sebagai bagian dari jumlah trace), dan apakah kunci juri tersedia — tidak pernah kuncinya, tidak pernah trace, tidak pernah jumlahnya. status adalah ok hanya jika semua pemeriksaan demikian; jika tidak, nilainya degraded dengan HTTP 503, yang dibaca oleh HEALTHCHECK milik image Docker. Semua hal lainnya memerlukan Authorization: Bearer <key> atau sesi browser. Retensi berjalan di setiap server: trace dan evaluasi yang lebih lama dari retention.days (default 30) dihapus saat startup, setelah server mulai menjawab, dan setiap retention.sweepIntervalHours, dalam langkah-langkah singkat yang tidak pernah membuat permintaan menunggu lama; --self-test mencetak kebijakan instalasi ini, dan iris://capabilities / GET /api/v1/capabilities membawanya sebagai retention.
Webhook terpicu pada suatu momen (0.16.0): notify.webhook di config.json (atau IRIS_WEBHOOK_URL dan IRIS_WEBHOOK_SECRET) menentukan penerima, dan Iris mengirim satu pesan bertanda tangan ketika verdict gagal, deteksi kritis memveto, biaya menjadi pencilan, tingkat kegagalan aturan berubah, atau kasus dijawab dengan kedua cara untuk pertama kalinya — ID, verdict, aturan, dan angka, tidak pernah teks agen. Ditandatangani sekaligus dengan cara Standard Webhooks dan GitHub, dicoba ulang dengan jeda bertahap, didinginkan per agen dan aturan, dan tidak pernah mengganggu evaluasi; isi Slack dan Discord tersedia bawaan. docs/webhooks.md.
Data Anda di disk
Semua yang disimpan Iris berada di bawah direktori home Iris Anda (~/.iris, atau IRIS_HOME). iris.db menyimpan input dan output setiap trace apa adanya — termasuk teks apa pun yang kemudian ditandai oleh no_pii; deteksi tidak menyamarkan teks kecuali Anda memintanya: storage.redact: "critical_spans" di config.json menyimpan keluaran setiap evaluasi dengan rentang yang ditandai oleh detektor kritis diganti dengan [REDACTED:<pattern>] (nonaktif secara default; offset bukti tetap mengindeks teks yang dilihat pemanggil). storage.synchronous menentukan kapan penulisan mencapai disk: normal (default) menyinkronkan log tulis-depan pada setiap checkpoint, sehingga jika Iris mengalami crash tidak ada yang hilang dan file tidak dapat rusak, tetapi pemadaman listrik atau crash sistem operasi dapat membatalkan penulisan sejak sinkronisasi terakhir; full menyinkronkan setiap commit dan mempertahankannya saat kedua jenis gangguan terjadi, dengan tambahan sekitar 1,5 ms per penulisan. Saat startup, lalu setiap retention.sweepIntervalHours (default 24, 0 menonaktifkan timer), trace dan evaluasi yang lebih lama dari retention.days (default 30, 0 menonaktifkan, diatur dalam config.json) dihapus dan log tulis-depan di-checkpoint. Satu hal dipertahankan melewati jangka waktu tersebut: eksekusi baseline yang disematkan, beserta evaluasinya, karena itulah yang menjadi pembanding bagi setiap eksekusi berikutnya. Setiap pembersihan yang mempertahankan sebagian data akan mencatatnya di log beserta eksekusi dan jumlahnya; lepaskan sematan eksekusi tersebut dan pembersihan berikutnya akan menghapusnya. Kasus dan label dataset bukan trace atau evaluasi, sehingga tidak ikut dibersihkan. Menghapus trace — melalui delete_trace atau pembersihan — menghapus teks setiap evaluasi yang tertaut dengannya (keluaran, teks yang diharapkan, dan pesan aturan) serta memberi cap erased_at; verdict, skor, dan offset bukti tetap ada. Setiap penghapusan melakukan checkpoint pada log tulis-depan sebelum selesai, sehingga teks yang dihapus tidak tertinggal dalam keadaan dapat dibaca di iris.db atau iris.db-wal (jika pencarian sedang membaca file saat itu, atau proses lain sedang membaca atau menulisnya, penghapusan selesai tanpa menunggu dan teks akan hilang dari file segera setelah proses tersebut selesai). Untuk menghapus semuanya sekarang, hentikan server dan jalankan --purge: perintah ini menghapus setiap trace, span, dan evaluasi yang tersimpan, memadatkan basis data, serta memotong log tulis-depan agar teks hilang dari disk, sambil mempertahankan aturan yang diterapkan, log audit, dan preferensi Anda. Sebelum rilis menerapkan migrasi ke iris.db yang sudah ada, rilis tersebut menyalin file ke sebelahnya (iris.db.<from>-to-<to>.<time>.bak, hanya untuk pemilik; tiga yang terbaru dipertahankan; Menurunkan versi): salinan itu menyimpan trace seperti semula, sehingga pembersihan retensi menghapus yang lebih lama dari retention.days dan --purge menghapus semuanya. Server membuat salinan dan menjalankan migrasi setelah menjawab kliennya, pada thread tersendiri: pemanggilan tool, pembacaan resource, dan permintaan HTTP yang tiba sementara itu menunggu, paling lama 30 dtk masing-masing, lalu ditolak dengan kalimat yang menjelaskan apa yang sedang dilakukan server (IRIS_STORAGE_ERROR, dapat dicoba ulang; HTTP 503 dengan Retry-After). Pemeriksaan kesehatan tetap menjawab selama proses berlangsung dan menyatakan apa yang sedang dilakukan saat peningkatan. Mulai 0.19.0, pada 100.000 trace yang masing-masing merupakan loop agen, penyalinan dan migrasi memerlukan sekitar 6 dtk. iris-eval ingest, --purge dan --self-test tetap melakukan peningkatan sebelum melakukan hal lain.
Iris tidak mengenkripsi data saat disimpan. iris.db dan file log tulis-depannya dibuat hanya untuk pemilik (mode 600), dan direktori home Iris dibuat dengan mode 700 (di Windows, ACL file yang mengatur). Basis data tidak menyimpan kunci penyedia LLM: IRIS_ANTHROPIC_API_KEY dan IRIS_OPENAI_API_KEY dibaca dari lingkungan dan tidak pernah ditulis ke disk. Namun, basis data menyimpan input dan output trace apa adanya, jadi tempatkan direktori home Iris di disk atau volume terenkripsi (FileVault, BitLocker, LUKS, atau volume cloud terenkripsi untuk mount /data milik image Docker).
Ekspor — tombol Ekspor pada halaman Trace dan Evaluasi di dasbor, GET /api/v1/traces/export dan /api/v1/evaluations/export, atau iris-eval export — membawa teks tersimpan apa adanya, sama seperti yang ditampilkan dasbor: input dan output trace apa adanya, keluaran evaluasi dengan storage.redact diterapkan. Perlakukan file yang diekspor seperti basis data asalnya.
Pemecahan masalah
Langkah pertama: jalankan uji mandiri
npx @iris-eval/mcp-server --self-test
Uji ini memeriksa penyimpanan, evaluasi deterministik, dan dasbor dalam direktori home sementara yang terisolasi, lalu mencetak verdict untuk setiap langkah — keluaran kegagalan menyebutkan langkah yang bermasalah. Kode keluar 0 berarti instalasi sehat.
Iris tidak mau memulai / ERR_MODULE_NOT_FOUND
Mungkin Anda memiliki versi lama yang tersimpan di cache. Bersihkan cache npx dan coba lagi:
npx --yes @iris-eval/mcp-server@latest
Atau instal secara global untuk sepenuhnya menghindari masalah cache:
npm install -g @iris-eval/mcp-server@latest
npm install --ignore-scripts merusak binding SQLite
Iris menyimpan trace dengan better-sqlite3, modul native yang mengambil atau mengompilasi binding-nya dalam skrip instalasi. Jika skrip tersebut dilewati — --ignore-scripts pada baris perintah, ignore-scripts=true dalam .npmrc (umum di mesin perusahaan), atau mirror registry yang menghapus postinstall — startup gagal dengan keluaran panjang "Could not locate the bindings file" yang mencantumkan belasan jalur yang telah dicoba. Bangun ulang modul tersebut:
npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3
Tool tidak muncul di Claude Code
Tool MCP hanya dimuat saat sesi dimulai. Setelah menambahkan iris-eval, mulai ulang sesi dengan /clear atau luncurkan ulang terminal.
Pemeriksaan versi
npx @iris-eval/mcp-server --version
Baris pertama log startup juga memuatnya (Starting Iris MCP server vX.Y.Z), dan --self-test mencetaknya dalam ringkasan. Untuk instalasi global, npm ls -g @iris-eval/mcp-server menampilkan versi yang terinstal.
Memperbarui
Setiap klien MCP di sebuah mesin berbagi satu basis data, ~/.iris/iris.db, dan install mengunci setiap klien ke rilis yang menulis konfigurasinya. Ketika sebuah rilis mengubah skema basis data, proses pertama dari rilis tersebut yang membuka file akan meningkatkannya, dan sejak saat itu klien yang masih terkunci ke rilis lama akan menolak untuk memulai. Jadi pindahkan semua klien sekaligus, sebelum atau tepat setelah Anda melakukan peningkatan:
npx -y @iris-eval/mcp-server@latest install --upgrade
Perintah ini menemukan setiap konfigurasi klien di mesin ini yang menjalankan Iris, memindahkan setiap penguncian ke rilis tersebut (sambil mempertahankan apa pun yang Anda tambahkan ke entri, seperti --dashboard atau blok env), membiarkan penguncian ke rilis yang lebih baru dan entri yang menjalankan sesuatu selain paket npm tetap apa adanya, lalu mencantumkan tindakan yang dilakukan. Mulai ulang klien yang disebutkan. install --list menunjukkan Iris yang dijalankan setiap klien.
Dua instalasi berada di luar file-file tersebut: ekstensi Claude Desktop (iris-eval.mcpb) berpindah saat Anda membuka bundel yang lebih baru, dan plugin Claude Code dengan claude plugin marketplace update iris-eval lalu claude plugin update iris-eval@iris-eval (serta claude plugin update iris-eval-capture@iris-eval untuk plugin capture).
Meningkatkan dari 0.19.x ke 0.20.0. 0.20.0 menambahkan indeks pencarian dan tambahan lainnya ke basis data (migrasi 015 dan seterusnya). Setelah proses 0.20.0 mana pun membuka ~/.iris/iris.db (ekstensi Claude Desktop, npx iris-eval, atau npx @iris-eval/mcp-server tanpa versi), klien yang terkunci ke 0.19.x akan berhenti dengan This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, …. Pesan itu berasal dari 0.19.x dan tidak dapat diubah; solusinya adalah perintah di atas. Sebelum peningkatan, 0.20.0 menyalin file ke sebelahnya, jadi Anda juga dapat kembali ke versi sebelumnya (di bawah).
Startup yang meningkatkan basis data mencetak tindakan yang dilakukan ke stderr: salinan yang dibuat, rilis lama mana yang tidak lagi dapat membuka file, dan klien mana di mesin ini yang masih terkunci ke salah satunya, beserta perintahnya. --self-test membaca basis data tanpa mengubahnya dan menyampaikan hal yang sama sebelum Anda memulai apa pun.
Untuk instalasi global, npm update -g @iris-eval/mcp-server, lalu iris-eval install --upgrade.
Menurunkan versi
Rilis yang meningkatkan basis data akan menyalinnya terlebih dahulu ke sebelahnya: iris.db.<from>-to-<to>.<time>.bak di direktori home Iris Anda (<from> adalah rilis yang terakhir mengubah skema file, <to> adalah rilis yang meningkatkannya; baris startup mencetak jalur persisnya). Untuk kembali:
- Hentikan semua klien MCP dan proses Iris lain yang menggunakan basis data.
- Simpan file yang telah ditingkatkan, untuk berjaga-jaga jika Anda kembali: ubah nama
iris.dbmenjadiiris.db.upgraded, lalu hapusiris.db-waldaniris.db-shmjika ada. - Salin cadangan ke
iris.db:cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db. - Kunci kembali setiap klien ke rilis yang lebih lama:
npx -y @iris-eval/mcp-server@0.19.0 install <client>untuk masing-masing (install --upgradetidak pernah memindahkan klien kembali).
Trace yang disimpan setelah peningkatan berada di iris.db.upgraded, bukan di cadangan. Jika tidak ada salinan yang dibuat (baris startup menyebutkan alasannya, misalnya disk penuh), rilis yang lebih lama tidak dapat membuka file yang telah ditingkatkan, dan langkah selanjutnya adalah install --upgrade.
Driver penyimpanan
Pada platform tanpa better-sqlite3 yang telah dibangun sebelumnya, instalasi tetap berhasil. better-sqlite3 adalah dependensi opsional: ketika npm tidak dapat mengunduh biner yang telah dibangun sebelumnya untuk Node dan platform Anda maupun mengompilasinya (kompilasi memerlukan Python dan toolchain C++ — Visual Studio C++ build tools di Windows), npm mencetak kesalahan build, melewati modul tersebut, dan menyelesaikan instalasi. Iris kemudian berjalan menggunakan SQLite bawaan Node, dan menyatakannya: startup mencetak satu baris ke stderr yang menyebutkan alasannya, dan --self-test menampilkan driver node: better-sqlite3 is not installed …. Untuk mengaktifkan kembali driver native, instal di lingkungan yang memiliki prebuild atau toolchain (npm install better-sqlite3 di proyek; untuk instalasi global, instal ulang Iris dengan npm install -g @iris-eval/mcp-server setelah toolchain tersedia). CI menginstal server yang telah dipaketkan dengan build native yang dipaksa gagal pada setiap perubahan, dan mengharuskan instalasi selesai serta uji mandiri menyimpan dan membaca trace menggunakan driver bawaan.
Iris menyimpan semuanya dalam satu file SQLite, yang dibuka oleh better-sqlite3 — addon native yang diunduh atau dikompilasi untuk Node dan platform Anda. Jika modul tersebut tidak dapat dimuat, Iris beralih ke SQLite bawaan Node (node:sqlite, Node 22.13 atau yang lebih baru) dengan satu peringatan di stderr, sehingga prebuild yang tidak tersedia hanya membuat proses mulai lebih lambat, bukan gagal total. Iris melakukan hal yang sama sebelum memuatnya untuk better-sqlite3 yang dikompilasi di mesin Anda menggunakan header Node 24.19 atau yang lebih baru, lalu dijalankan pada Node 24.19 hingga 24.21: pada versi tersebut, biner seperti itu akan menghentikan seluruh proses saat pertama kali membebaskan sebuah statement (Assertion failed: (env) != nullptr, nodejs/node#65446). Node 24.22.0 menyertakan perbaikannya, dan Iris memuat biner tersebut di sana. npm rebuild better-sqlite3 menggantinya dengan biner prebuilt yang aman di semua versi. IRIS_SQLITE_DRIVER=node sengaja memilih versi bawaan, sedangkan native melarang fallback. Versi bawaan dibuka dengan pemuatan ekstensi dinonaktifkan dan trusted_schema dinonaktifkan; Node mencetak baris ExperimentalWarning: SQLite is an experimental feature miliknya sendiri di stderr saat memuatnya, dan Iris tidak menyembunyikannya. --self-test dan GET /health menunjukkan driver yang sedang digunakan; setiap angka di halaman bukti diukur menggunakan driver native, dan rangkaian pengujian dijalankan pada keduanya di CI.
Versi Node.js
Iris memerlukan Node.js 22.13 atau yang lebih baru. Node 20 mencapai akhir masa pakainya pada 2026-04-30 dan tidak didukung; Node 18 berakhir pada April 2025.
Batas minimumnya adalah 22.13, bukan 22.0, karena 22.13.0 adalah rilis pertama yang menyertakan node:sqlite. Dengan demikian, ini adalah versi pertama yang menyediakan driver penyimpanan kedua untuk setiap instalasi Iris yang didukung: ketika addon native better-sqlite3 tidak dapat dimuat, Iris beralih ke SQLite bawaan Node alih-alih gagal memulai. Di bawah 22.13 — dan sepanjang masa pakainya pada Node 20 — hanya ada satu driver, dan prebuild yang tidak tersedia menyebabkan proses gagal dimulai.
node --version # Must be v22.13.0 or newer
Windows: cmd /c tidak diperlukan
/doctor milik Claude Code mungkin menyarankan untuk membungkus npx dengan cmd /c. Ini tidak diperlukan dan menyebabkan masalah penguraian path. Gunakan npx secara langsung:
# 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"
Jika Iris bermanfaat bagi Anda, pertimbangkan untuk memberi bintang pada repo — ini membantu orang lain menemukannya.
Dilisensikan dengan MIT.