Iris

Iris — berhenti mengirim agen berdasarkan perasaan

Iris memberi skor pada setiap eksekusi agen untuk kualitas, keamanan, dan biaya — di mesin Anda, tanpa SDK dan tanpa akun. Kebanyakan proyek agen memeriksa kualitas dengan menjalankan beberapa prompt yang diingat lalu melihat hasilnya secara sekilas. Iris menggantinya dengan angka yang bisa Anda audit: eksekusi agen Anda tersimpan di basis data SQLite di disk Anda, 13 aturan bawaan memberi skor secara deterministik — PII, penyuntikan prompt, penanda halusinasi, ambang biaya — gratis, tanpa panggilan LLM, dan juri LLM opsional dengan batas biaya keras per-evaluasi menangani pertanyaan semantik. Setiap aturan dapat diperiksa dan diedit, karena juri yang tidak bisa Anda audit hanyalah perasaan yang diberi angka. Lisensi MIT, tanpa telemetri; jejak Anda tidak pernah meninggalkan mesin Anda.

Membutuhkan Node.js 20 atau lebih baru. Periksa dengan node --version.

Kegagalan di layar dalam 60 detik

Tanpa pengaturan agen, tanpa konfigurasi — satu perintah:

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

Ini mengisi basis data demo — segelintir agen kecil dengan satu minggu eksekusi — dan menyajikan dasbor untuk itu di http://localhost:6920 (browser Anda terbuka otomatis pada eksekusi pertama). Dasbor mendarat di Failures: apa yang gagal, terburuk dan terbaru lebih dulu. Layak diklik — kebocoran PII yang tertangkap aturan keamanan, percobaan penyuntikan prompt yang ditandai, dan skor juri LLM yang gagal beserta alasannya.

Data demo tersimpan di basis datanya sendiri (demo.db di direktori utama Iris Anda — ~/.iris di macOS/Linux, %USERPROFILE%\.iris di Windows) dan tidak pernah tercampur dengan jejak asli Anda. Hapus semuanya dengan satu perintah:

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

Hubungkan agen Anda sendiri

Tambahkan Iris ke konfigurasi MCP Anda. Berfungsi dengan Claude Desktop, Claude Code, Cursor, Windsurf, Continue, VS Code, Cline, Zed, Codex CLI, Gemini CLI — dan agen lain yang kompatibel dengan MCP. Satu blok, dasbor sudah termasuk:

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

Agen Anda menemukan sembilan alat Iris saat terhubung, dan dasbor tersaji di http://localhost:6920. Sekarang tempel ini ke agen Anda:

Catat tugas terakhir itu ke Iris dan evaluasi keluarannya.

Jejak tersebut mendarat di dasbor beserta skornya. Lebih suka server MCP tanpa kepala? Hapus --dashboard dari argumen — Anda bisa 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 jejak dicatat saat agen Anda memintanya untuk dicatat — baik karena Anda menyuruhnya, atau karena kode Anda memanggil alat tersebut secara langsung. Minta agen Anda untuk "catat ini ke Iris dan evaluasi" dan ia akan melakukannya. Jika Anda ingin penangkapan yang tidak bergantung pada pilihan model, POST /api/v1/traces melakukan hal itu — kode Anda mengirim jejak melalui HTTP biasa, tanpa model dalam proses (lihat docs/http-ingest.md). CLI dan SDK di peta jalan akan menjadi klien tipis di atas endpoint yang sama.

Penangkapan melalui HTTP (tanpa model dalam proses)

Dengan dasbor berjalan, apa pun yang bisa mengirim permintaan HTTP dapat mencatat jejak — dan secara opsional menjalankan evaluasi deterministik dalam permintaan yang sama:

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. Endpoint menerima badan yang sama dengan alat log_trace dan berada di belakang middleware stack loopback-only yang sama dengan dasbor lainnya. Kontrak lengkap, referensi bidang, dan semantik kesalahan: docs/http-ingest.md.

Periksa instalasi

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

Diagnostik instalasi luring: round-trip penyimpanan, evaluasi deterministik, dasbor + pelindung DNS-rebinding — semuanya di dalam home temp terisolasi, jadi basis data asli Anda tidak pernah dibuka. Kode keluar 0 = sehat, 1 = ada pemeriksaan yang gagal.

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

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

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

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

Metode Instalasi Lainnya

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

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

Tips: Instalasi global (npm install -g) menyimpan jejak secara persisten di ~/.iris/iris.db. Dengan npx, jejak tersimpan di lokasi yang sama, tetapi startup lebih lambat karena resolusi paket.

Yang Anda Dapatkan

Ke mana arah selanjutnya: peta jalan.

Alat MCP

Iris mendaftarkan sembilan alat yang dapat dipanggil oleh agen apa pun yang kompatibel dengan MCP — siklus hidup aturan + jejak lengkap + LLM-sebagai-juri + verifikasi sitasi semantik:

• log_trace — Mencatat eksekusi agen dengan span, panggilan alat, pemakaian token, dan biaya
• evaluate_output — Memberi skor kualitas keluaran terhadap aturan kelengkapan, relevansi, keamanan, dan biaya (heuristik, deterministik, gratis)
• get_traces — Menanyakan jejak tersimpan dengan pemfilteran, pembagian halaman, dan dukungan rentang waktu
• list_rules — Menghitung aturan evaluasi kustom yang diterapkan (hanya-baca)
• deploy_rule — Mendaftarkan aturan evaluasi kustom baru agar aktif pada setiap evaluate_output dari kategori itu
• delete_rule — Menghapus aturan kustom yang diterapkan (destruktif, idempoten)
• delete_trace — Menghapus satu jejak tersimpan berdasarkan ID (destruktif, terlingkup-tenant)
• evaluate_with_llm_judge — Evaluasi semantik melalui LLM (Anthropic atau OpenAI). Lima templat: akurasi, kebermanfaatan, keamanan, kebenaran, kesetiaan. Berbatas biaya, harga per-evaluasi diungkapkan. Bawa kunci API Anda sendiri (IRIS_ANTHROPIC_API_KEY atau IRIS_OPENAI_API_KEY) — Iris tidak mem-proxy atau meneruskan panggilan LLM.
• verify_citations — Mengekstrak sitasi dari keluaran (bernomor, penulis-tahun, URL, DOI), mengambil sumber di belakang resolver berpelindung-SSRF + daftar-putih-domain, dan menggunakan juri LLM untuk memeriksa apakah setiap sumber benar-benar mendukung klaim yang disitasi. HTTP keluar bersifat ikut-serta. Persyaratan BYOK yang sama dengan evaluate_with_llm_judge.

Saat IRIS_OTEL_ENDPOINT dikonfigurasi, panggilan log_trace juga mengeluarkan ekspor JSON OTLP/HTTP sebaik-mungkin ke kolektor OpenTelemetry mana pun (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, dll.). Lihat docs/otel-integration.md.

Bagaimana passed ditentukan

evaluate_output mengembalikan bendera score dan passed — keduanya menjawab pertanyaan yang berbeda:

• score (0..1) adalah rata-rata tertimbang di seluruh aturan yang berjalan — gradien kualitas.
• passed adalah vonis kirim/jangan-kirim: true hanya saat skor melewati ambang kelulusan (default 0,7) dan tidak ada aturan kritis yang gagal.

Pelanggaran keamanan yang sesungguhnya gagal-keras. no_pii, no_injection_patterns, dan no_blocklist_words adalah aturan kritis: jika satu gagal, evaluasi melaporkan passed: false tidak peduli seberapa baik aturan lain memberi skor, dan respons menyebutkan pelakunya di critical_failures. SSN yang bocor tidak bisa dirata-ratakan. Aturan kustom yang diterapkan dengan severity: "high" atau "critical" gagal-keras dengan cara yang sama; tingkat keparahan low/medium hanya memengaruhi skor. Satu batasan yang perlu diketahui: aturan kritis yang dilewati (konteks hilang, atau penyebab lain dari lompatan) belum menilai keluaran dan tidak memveto — rule_results menampilkan setiap lompatan beserta alasannya, sehingga pintu gerbang yang harus gagal-tertutup pada non-vonis bisa melakukannya.

Satu kendala untuk gerbang CI: jika Anda menghilangkan eval_type, kumpulan default completeness yang berjalan — aturan keamanan tidak ikut. Respons menggema eval_type (plus note saat itu di-default-kan) sehingga gerbang Anda dapat memverifikasi kumpulan mana yang benar-benar berjalan. Kunci pada passed untuk vonis dan eval_type: "safety" untuk cakupan.

Skema alat lengkap dan konfigurasi: iris-eval.com

Fitur ter-hosting

Iris berjalan sepenuhnya di mesin Anda saat ini, dan semua yang dilakukannya gratis dan berlisensi MIT tanpa batasan dan tanpa akun.

Penyimpanan ter-hosting, riwayat tim bersama, dan pemberitahuan sedang dipertimbangkan, bukan sedang dibangun. Tidak ada harga, dan tidak ada yang bisa dibeli. Jika riwayat bersama berguna bagi Anda, daftar tunggu adalah cara kami mengetahui apakah itu layak dibangun — itu tidak mengikat Anda pada apa pun.

Dua komitmen tetap berlaku apa pun yang terjadi: tidak ada yang gratis hari ini yang akan dipindahkan ke balik paywall, dan tidak ada sertifikasi kepatuhan yang akan diklaim sebelum dimiliki.

Contoh

• Pengaturan Claude Desktop — konfigurasi MCP untuk mode stdio dan HTTP
• TypeScript — klien SDK MCP — hubungkan dan panggil alat
• Transport HTTP (TS + Python) — kode klien lengkap untuk integrasi gaya REST
• Instrumentasi LangChain (Python, konseptual) — kerangka yang menunjukkan bentuknya; membutuhkan kode agen Anda agar dapat dijalankan
• Instrumentasi CrewAI (Python, konseptual) — kerangka; peringatan yang sama

Komunitas

• GitHub Issues — Laporan bug dan permintaan fitur
• GitHub Discussions — Pertanyaan dan ide
• Contributing Guide — Cara berkontribusi
• HTTP Ingest — Penangkapan jejak deterministik melalui POST /api/v1/traces
• Roadmap — Apa yang akan datang

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

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

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

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

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

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

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

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

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

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

Jika Iris berguna bagi Anda, pertimbangkan untuk memberi bintang pada repo — ini membantu orang lain menemukannya.

Dilisensikan MIT.