Iris

Iris — หยุดส่ง agents ไปบนความรู้สึก

Iris ให้คะแนนทุกการรันของ agent ในด้านคุณภาพ ความปลอดภัย และค่าใช้จ่าย — บนเครื่องของคุณ โดยไม่ต้องใช้ SDK และไม่ต้องมีบัญชี โปรเจกต์ agent ส่วนใหญ่ตรวจสอบคุณภาพด้วยการรันพรอมต์ที่จำไว้สองสามอันแล้วดูผลลัพธ์ด้วยตา Iris แทนที่สิ่งนั้นด้วยตัวเลขที่คุณตรวจสอบได้: การรันของ agent ของคุณจะถูกเก็บในฐานข้อมูล SQLite บนดิสก์ของคุณ กฎในตัว 25 ข้อให้คะแนนแบบ deterministic — PII, prompt injection, สัญญาณของ hallucination, เกณฑ์ค่าใช้จ่าย และการเรียกใช้ tool ของ agent เอง — ฟรี ไม่มีการเรียก LLM และมี LLM judge แบบเลือกได้พร้อมเพดานค่าใช้จ่ายต่อการประเมินแบบตายตัวสำหรับคำถามเชิงความหมาย ทุกกฎสามารถตรวจสอบและแก้ไขได้ เพราะ judge ที่คุณตรวจสอบไม่ได้ก็แค่ความรู้สึกที่มีตัวเลขกำกับ ใช้สัญญาอนุญาต MIT ไม่มี telemetry ไม่มีอะไรออกจากเครื่องของคุณเว้นแต่คุณจะเปิดหนึ่งในสิ่งเหล่านี้: ปลายทาง OpenTelemetry (IRIS_OTEL_ENDPOINT) ซึ่งส่ง traces ไปยัง collector ที่คุณระบุ; LLM judge ที่ใช้คีย์ของคุณเอง ซึ่งส่งข้อความที่มันประเมินไปยังผู้ให้บริการนั้น และการตรวจสอบการอ้างอิงของมันจะดึงหน้าที่ผลลัพธ์อ้างถึง; หรือ webhook ซึ่งส่ง id, verdict และชื่อกฎ ไม่เคยส่งข้อความ ไปยังที่อยู่ที่คุณตั้งไว้

ต้องใช้ Node.js 22.13 หรือใหม่กว่า ตรวจสอบด้วย node --version

_{ฐานข้อมูลตัวอย่าง บันทึกโดย scripts/demo-media.mts; แหล่งที่มาคือ demo.mp4 ภาพนิ่ง: dashboard-overview.png}

เห็นความล้มเหลวบนหน้าจอใน 60 วินาที

ไม่ต้องต่อ agent ไม่ต้องตั้งค่า — คำสั่งเดียว:

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

คำสั่งนี้สร้างฐานข้อมูลตัวอย่าง — agent ขนาดเล็กห้าตัว การรันสองสัปดาห์ ทุก verdict มาจากเอนจินของมันเอง — และให้บริการ dashboard กับฐานข้อมูลนั้นที่ http://localhost:6920 (เบราว์เซอร์ของคุณจะเปิดโดยอัตโนมัติในการรันครั้งแรก) dashboard เปิดที่หน้า Failures: อะไรล้มเหลว เรียงจากแย่ที่สุดและใหม่ที่สุดก่อน แต่ละการ์ดระบุกฎและหลักฐานของมัน คุ้มค่าที่จะคลิกเข้าไปดู — การรั่วไหลของ PII ที่กฎความปลอดภัยจับได้, คำสั่งซ่อนเร้นในโพสต์ฟอรัมที่ตัวสรุปปฏิบัติตาม, ตัวเลขที่เอกสารต้นทางไม่เคยพูดถึง, การรันสองครั้งบนคำถามสิบสองข้อเดียวกันที่เปรียบเทียบกับช่วงเวลา (Runs), กฎที่กำหนดเองที่ใช้งานและกฎที่หยุดชั่วคราวพร้อมแถวการตรวจสอบของมัน และคะแนน LLM-judge ที่ล้มเหลวพร้อมเหตุผลของมัน

ข้อมูลตัวอย่างอยู่ในฐานข้อมูลของตัวเอง (demo.db ในไดเรกทอรีบ้านของ Iris — ~/.iris บน macOS/Linux, %USERPROFILE%\.iris บน Windows) และไม่ปะปนกับ traces จริงของคุณ ลบทั้งหมดด้วยคำสั่งเดียว:

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

เชื่อมต่อ agent ของคุณเอง

ก่อนอื่น พิสูจน์ว่าการติดตั้งทำงานบนเครื่องนี้ — มันทำงานแบบออฟไลน์และไม่เปิดอะไรของคุณ:

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

จากนั้นเพิ่ม Iris ไปยัง MCP client ของคุณ คำสั่งเดียวเขียนไฟล์คอนฟิกของ client เอง เก็บเซิร์ฟเวอร์อื่นทั้งหมดไว้ และปักหมุดเวอร์ชันที่คุณรัน:

npx -y @iris-eval/mcp-server install claude-code

Clients: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini install --list แสดงรายการที่พบบนเครื่องนี้ Iris ที่แต่ละตัวรันและไฟล์ที่มันอ่าน; install <client> --uninstall เอา Iris ออกอีกครั้ง ทุก client ใช้ฐานข้อมูลร่วมกัน ดังนั้นหลังอัปเกรดให้ย้ายทั้งหมดพร้อมกันด้วย install --upgrade (การอัปเดต) รีสตาร์ท client เพื่อโหลด

Claude Desktop: คลิกเดียว ทุกรีลีสตั้งแต่ 0.20.0 เป็นต้นไปแนบ iris-eval.mcpb ซึ่งเป็น MCP Bundle: ดาวน์โหลด เวอร์ชันล่าสุด เปิดมัน แล้ว Claude Desktop จะแสดงไดอะล็อกการติดตั้ง ไม่มีอะไรในนั้นที่จำเป็น — คีย์ Anthropic หรือ OpenAI สำหรับ LLM judge เป็นตัวเลือก และ dashboard เป็นสวิตช์ที่ปิดอยู่ตอนเริ่มต้น Bundle เก็บแพ็กเกจ npm และ dependencies ของมัน ดังนั้นไม่ต้องติดตั้งอะไรเพิ่มเติม: Claude Desktop รันมันภายใต้ Node ที่มันมาพร้อมกับเมื่อ Node นั้นเป็น 22.13 หรือใหม่กว่า (Claude Desktop 1.1.6679 มาพร้อม 24.13) และ Iris เก็บ traces ด้วย SQLite ในตัวของ Node ใน ~/.iris เดียวกับการติดตั้งอื่นทั้งหมด บันทึกประจำรุ่นแสดงวิธีตรวจสอบลายเซ็นและการรับรองการ build

มันรันใน MCP client ใดก็ได้ และทุก client ที่มันระบุชื่อมีแถวพร้อมสิ่งที่ตรวจสอบจริง ตรวจสอบแล้วในการรัน CI ทุกครั้ง: Claude Code, Gemini CLI — client จริงเริ่ม Iris จากคอนฟิกที่ตัวติดตั้งเขียนและรายงานว่าเชื่อมต่อแล้ว (claude mcp list, gemini mcp list) บน Linux, macOS และ Windows; ฮุคของ capture plugin ของ Claude Code ก็ขับเคลื่อนผ่านสคริปต์จริงเช่นกัน อ้างจากเอกสาร MCP ของแต่ละ client เอง — ตัวติดตั้งเขียนรูปแบบคอนฟิกที่ client เอกสารไว้ และตัวเขียนนั้นถูกทดสอบกับรูปแบบนั้น; ไม่มีใครฝั่ง Iris เห็นมันเชื่อมต่อ: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI ทุกแถวพร้อมแหล่งที่มาและวันที่ที่อ่าน: https://iris-eval.com/clients. ด้วยมือแทน บล็อกเดียว รวม dashboard:

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

Client ของคุณจะแสดงเครื่องมือสิบสองรายการของ Iris เมื่อเชื่อมต่อ และ dashboard ให้บริการที่ http://localhost:6920. ตอนนี้วางสิ่งนี้ให้ agent ของคุณ:

บันทึกงานสุดท้ายนั้นไปยัง Iris และประเมินผลลัพธ์

Trace จะลงบน dashboard พร้อมคะแนนของมัน ชอบ MCP server แบบ headless ไหม? เอา --dashboard ออกจาก args — คุณสามารถเปิด dashboard เดียวกันได้ทุกเวลาด้วย npx @iris-eval/mcp-server --dashboard

สิ่งหนึ่งที่ควรรู้ล่วงหน้า: เครื่องมือ MCP ถูกเรียกเมื่อโมเดลตัดสินใจเรียกมัน Iris ไม่ดักจับ agent ของคุณ ดังนั้น traces จะถูกบันทึกเมื่อ agent ของคุณขอให้บันทึก — ไม่ว่าคุณจะบอกมัน หรือโค้ดของคุณเรียกเครื่องมือโดยตรง ขอให้ agent ของคุณ "บันทึกสิ่งนี้ไปยัง Iris และประเมินมัน" แล้วมันจะทำ หากคุณต้องการ capture ที่ไม่ขึ้นอยู่กับการเลือกของโมเดล POST /api/v1/traces ทำสิ่งนั้นได้พอดี — โค้ดของคุณส่ง trace ผ่าน HTTP ธรรมดา ไม่มีโมเดลอยู่ในวงจร (ดู docs/http-ingest.md) CLI และฮุคของโฮสต์บน roadmap จะเป็นไคลเอนต์แบบบางบนปลายทางเดียวกัน

Capture ผ่าน HTTP (ไม่มีโมเดลในวงจร)

ปลายทาง ingest อยู่บน พอร์ต dashboard — 6920 โดยค่าเริ่มต้น ไม่ใช่พอร์ต transport ของ MCP — และมันมีอยู่เฉพาะเมื่อ dashboard กำลังรัน ส่ง --dashboard (หรือตั้ง IRIS_DASHBOARD=true); --transport http เพียงอย่างเดียว ไม่ เริ่มมัน และคำขอไปยังพอร์ต transport จะคืนค่า 404 เมื่อ dashboard เปิดอยู่ อะไรก็ตามที่ส่งคำขอ HTTP ได้สามารถบันทึก trace — และเลือกที่จะรันการประเมินแบบ deterministic ในคำขอเดียวกัน GET /api/v1/capabilities บนพอร์ตเดียวกันบอกว่าซerver นี้สามารถประเมินอะไรได้ แต่ละกฎต้องการอะไร สถานะของ judge พร้อมขั้นตอนที่เปิดใช้งานมัน และขีดจำกัด — วัตถุเดียวกับที่ MCP resource iris://capabilities ให้บริการ — ดังนั้นผู้เรียก HTTP จึงมีกรอบที่ MCP client ได้ที่การเริ่มต้น:

curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "input": "What is the refund policy?",
    "output": "Refunds are available within 30 days of purchase.",
    "evaluate": true,
    "eval_type": "safety"
  }'

คืนค่า 201 พร้อม trace_id ที่เก็บไว้และผลการประเมิน (ในโหมด --demo ปลายทางปฏิเสธการเขียนด้วย 403 ดังนั้นข้อมูลตัวอย่างจะไม่ปะปนกับของคุณ) ปลายทางยอมรับ body เดียวกับเครื่องมือ log_trace และอยู่หลัง middleware stack เดียวกับส่วนที่เหลือของ dashboard: การผูก loopback และการป้องกัน DNS-rebinding โดยค่าเริ่มต้น บวก Bearer auth เมื่อคุณตั้งค่า ข้อเท็จจริงธรรมดาสองข้อเกี่ยวกับมัน: มันยอมรับการเขียนที่ไม่มีการรับรองความถูกต้องเว้นแต่ Iris จะเริ่มด้วย --api-key (หรือ IRIS_API_KEY) — การผูก loopback คือสิ่งที่เก็บมันไว้กับเครื่องของคุณโดยค่าเริ่มต้น ดังนั้นตั้งคีย์ก่อนผูกเกิน loopback; และสิ่งที่มันเก็บคือตามที่ส่งมาแบบคำต่อคำ — input และ output ลงใน iris.db ตามที่ส่งพอดี รวมถึงข้อความใดก็ตามที่ no_pii ไปชี้เพิ่มเติม สัญญาเต็ม การอ้างอิงฟิลด์ และความหมายของข้อผิดพลาด: docs/http-ingest.md

Capture ทุกเทิร์นของ Claude Code (ไม่บังคับ)

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

ปลั๊กอินที่ติดตั้งแยกต่างหากตัวที่สอง: ฮุคสามตัวบันทึกพรอมต์ การเรียก tool และคำตอบสุดท้ายของแต่ละเทิร์น และส่งให้ iris-eval ingest แบบแยกออกไป โดยมีช่วงสำคัญที่ถูกปกปิดในข้อความการประเมินที่เก็บไว้ — capture ที่ไม่ขึ้นอยู่กับโมเดลตัดสินใจเรียก tool มันไม่บันทึกเทิร์นที่โมเดลบันทึกแล้ว ไม่พิมพ์ ไม่บล็อก ไม่ส่งอะไรไปที่ไหน การติดตั้ง iris-eval เพียงอย่างเดียวไม่เปลี่ยนอะไรเกี่ยวกับวงจรเทิร์นของคุณ ขีดจำกัดและการลบ: claude-plugin-capture/README.md

Python

pip install iris-eval

from iris_eval import IrisClient
iris = IrisClient()                       # IRIS_URL, or the running dashboard's runtime.json
iris.evaluate_output("…", input="…", agent_name="support-bot")["verdict"]   # {"state": "pass", "basis": "clean", "by": []}

ไคลเอนต์แบบบางเหนือ HTTP API ของเซิร์ฟเวอร์ 0.16.0 ขึ้นไป มีเวอร์ชันของตัวเอง — iris_eval.__version__ และหน้า PyPI มีหมายเลขของมัน ซึ่งไม่ใช่ของเซิร์ฟเวอร์: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), แบบ sync และ async, คำตอบแบบ typed, ประโยคของเซิร์ฟเวอร์เองเมื่อปฏิเสธ — และปลั๊กอิน pytest: ฟิกซ์เจอร์ iris และ assert_iris(output, expect="pass") ที่ยืนยันสถานะของ verdict 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' });

ครอบ client ของผู้ให้บริการครั้งเดียว แล้วการเรียกโมเดลแต่ละครั้งจะกลายเป็น OpenTelemetry GenAI span หนึ่งรายการที่ส่งไปยังประตู OTLP เก็บด้วย input, output, การใช้ token และการเรียก tool ของมัน และให้คะแนน: capture ที่ไม่ขึ้นอยู่กับโมเดลเรียก tool wrap_openai / wrap_anthropic ในไคลเอนต์ Python; wrapOpenAI, wrapAnthropic และ irisMiddleware สำหรับ Vercel AI SDK ใน @iris-eval/sdk ทั้งสองยังไม่ได้เผยแพร่ (รีลีส iris-eval ถัดไปบน PyPI; @iris-eval/sdk สร้างจากซอร์สจนกว่าจะมีการเผยแพร่ npm ครั้งแรก) สตรีม ตัวช่วยสตรีมของ SDK และการเรียก tool ครอบคลุมแล้ว ไคลเอนต์เดิมไม่ถูกเปลี่ยนแปลง และ 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")]})

การรันระดับบนสุดแต่ละครั้งกลายเป็น trace หนึ่งรายการ (การรัน การเรียกโมเดล การเรียก tool และโหนดกราฟของมันเป็น GenAI spans) พร้อม input, output, การเรียก tool, การใช้ token และ verdict Python ในไคลเอนต์ (รีลีสถัดไป ยังไม่ได้เผยแพร่ไปยัง PyPI), JavaScript เป็น @iris-eval/langchain (ยังไม่ได้เผยแพร่ไปยัง npm) ทั้งสองพิสูจน์แล้วใน CI กับแอป LangGraph จริงที่มีโมเดลแบบสคริปต์; การส่งออก OpenTelemetry ของ LangSmith เองก็พิสูจน์ด้วยวิธีเดียวกัน — docs/otel-recipes.md

ประตู CI ไม่ต้องใช้เซิร์ฟเวอร์

npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on detector_veto

หรือ GitHub Action (0.16.0) ซึ่งทำให้งานล้มเหลวบน verdicts ที่คุณระบุ เขียนใบเสร็จไปยังสรุปงาน และโพสต์เป็นความคิดเห็น pull request หนึ่งรายการที่อัปเดตในที่: uses: iris-eval/mcp-server/.github/actions/gate@v0.19.0 กับ traces: traces.ndjson — docs/ci-gate.md ประตูที่สี่ (0.15.0): POST /v1/traces บนพอร์ตแดชบอร์ดรับ OTLP/HTTP JSON หรือ protobuf ที่เครื่องมือวัด OpenTelemetry ของคุณส่งออกอยู่แล้ว (ตัวส่งออกของ Python SDK พูด protobuf อย่างเดียว ดังนั้นนี่จึงเป็นประตูสำหรับ Python ด้วย) และแต่ละ OTLP trace จะกลายเป็น Iris trace พร้อมสแปนของมัน — docs/otel-integration.md; หนึ่งสูตรต่อเฟรมเวิร์ก (Pydantic AI, Google ADK, LangGraph ผ่าน LangSmith, CrewAI, OpenAI Agents SDK ใน Python และ JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK และ Mastra) แต่ละสูตรพิสูจน์ด้วย fixture ใน docs/otel-recipes.md ingest อ่าน JSON trace หนึ่งรายการ (หรือ NDJSON หนึ่งรายการต่อบรรทัด) จาก stdin หรือไฟล์ จัดเก็บมัน ประเมินมันภายใต้กฎเดียวกับที่ evaluate_output ใช้ พิมพ์ JSON หนึ่งบรรทัดต่อ trace พร้อมคำตัดสินและพื้นฐานของมัน และออกด้วยรหัส 1 เมื่อคำตัดสินตรงกับ --fail-on --dataset <id|label> จำกัดเกตนั้นให้เหลือเฉพาะคีย์กรณีในชุดข้อมูล (POST /api/v1/datasets เลื่อนคีย์กรณีของการรันหนึ่งครั้งเข้าไปในชุดข้อมูล) ดังนั้นงานจะล้มเหลวเฉพาะกรณีที่คุณเลือกเท่านั้น สูตรเต็ม รหัสออก และแปดพื้นฐานอยู่ใน docs/ci-gate.md

เขียนกฎเป็นโค้ด

eval.plugins ใน config.json โหลดกฎที่คุณเขียน — โมดูล ES ที่ค่า export เริ่มต้นคือ { name, kind, mechanism, version, needs, evaluate(ctx) } — ยึดด้วย sha256 ของไฟล์ ดังนั้นไฟล์ที่เปลี่ยนไปตั้งแต่คุณยึดมันจะปฏิเสธการเริ่มต้นแทนที่จะรัน ปลั๊กอินที่โหลดแล้วทำงานเหมือน built-in และแสดงบน 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

เอนจินเดียวกัน กฎเดียวกัน และ composer เดียวกับที่เซิร์ฟเวอร์ใช้; builtInRules(), createCustomRule(), compose() และตัวอ่านความแม่นยำที่เผยแพร่ถูก export อยู่ข้างๆ มัน

ไคลเอนต์แบบมีชนิดสำหรับเส้นทาง 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

หนึ่ง body บนทุกประตู: มันคือสิ่งที่ log_trace และ iris-eval ingest ยอมรับ การปฏิเสธจะโยน IrisClientError พร้อมประโยคและสถานะของเซิร์ฟเวอร์เอง ทั้งสอง subpath ถูกตรวจสอบจาก tarball ที่แพ็กแล้วในทุก build

ตรวจสอบการติดตั้งของคุณ

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 home ของคุณก่อนถ้ามันหายไป และตรวจสอบว่ามันเขียนได้ (ออกด้วยรหัส 1 ระบุเส้นทาง ถ้ามันเขียนไม่ได้) รายงานว่าดัชนีค้นหาของฐานข้อมูลของคุณอยู่ที่ไหน (ทั้งหมด, มีกี่ trace ที่ build พื้นหลังจัดทำดัชนีไว้แล้ว, หรือไม่มี FTS5 บน SQLite นี้) อ่าน schema ของฐานข้อมูลของคุณ (ออกด้วยรหัส 1 พร้อมวิธีแก้ไข เมื่อเวอร์ชันนี้หรือ MCP client ที่ยึดกับรุ่นเก่ากว่าไม่สามารถเปิดมันได้) จากนั้นรันการตรวจสอบของมัน — การเก็บแบบ round-trip, SSN ที่ปลูกไว้ และการฉีดที่ปลูกไว้ซึ่งถูกจับโดยกฎความปลอดภัย, การบูตแดชบอร์ด, การป้องกัน DNS-rebinding — ภายใน temp home ที่แยกออกมา ฐานข้อมูลจริงของคุณถูกอ่านเท่านั้น ไม่เคยถูกเปลี่ยนแปลง ทุกอย่างที่ Iris เขียนอยู่ภายใต้ไดเรกทอรีเดียว นั่นคือ Iris home ของคุณ: ~/.iris โดยค่าเริ่มต้น (%USERPROFILE%\.iris บน Windows) หรือที่ใดก็ตามที่ IRIS_HOME ชี้ นั่นคือที่ที่ iris.db, config.json, custom-rules.json, audit.log, preferences.json และไฟล์สาธิตอยู่; ชี้ IRIS_HOME ไปที่ไดเรกทอรีขูดเพื่อลอง Iris โดยไม่แตะข้อมูลจริงของคุณ

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

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

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

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

วิธีการติดตั้งอื่นๆ

# 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

เคล็ดลับ: การติดตั้งแบบ global (npm install -g) เก็บ traces อย่างถาวรที่ ~/.iris/iris.db ด้วย npx, traces ยังคงอยู่ในตำแหน่งเดียวกัน แต่การเริ่มต้นช้าลงเนื่องจากการแก้ไขแพ็กเกจ

สิ่งที่คุณได้รับ

ที่ที่สิ่งนี้จะไปต่อ: แผนที่ความสามารถ — ทุกคำถามที่ Iris สามารถถูกถามเกี่ยวกับทุกหัวข้อ พร้อมสิ่งที่มันมีและสิ่งที่มันขาด — และ สามแทร็ก

วัดผล ไม่ใช่กล่าวอ้าง

ทุกกฎในตัวมีค่า precision, recall และ F1 ที่เผยแพร่พร้อมช่วงความเชื่อมั่น 95% ซึ่งวัดจากคลังข้อความที่ติดป้ายกำกับซึ่งอยู่ใน repository นี้ (proof/corpus/) และสร้างใหม่ได้ด้วยคำสั่งเดียว — npm run proof — แบบออฟไลน์ โดยไม่ต้องใช้คีย์หรือโมเดลในกระบวนการ ตัวเลขเหล่านั้นมีสองประเภทที่แตกต่างกัน และหน้าเว็บไม่เคยนำมารวมกัน: กฎบางข้อวัดเทียบกับป้ายกำกับที่โมเดลให้โดยการอ่านความล้มเหลวนั้นเอง ซึ่งวัดการตรวจจับ ส่วนที่เหลือตรวจสอบเทียบกับคำนิยามที่บันทึกไว้ของตัวเอง ซึ่งนำไปใช้อย่างอิสระ ซึ่งแสดงว่าโค้ดนำสูตรไปใช้ได้จริง และไม่ได้บอกว่าสูตรจับความล้มเหลวได้หรือไม่ proof/RESULTS.md และหน้าหลักฐานทำเครื่องหมายแต่ละกฎ CI จะรันการวัดซ้ำในทุก pull request และจะล้มเหลวหากตัวเลขที่คอมมิตแตกต่างจากที่โค้ดสร้างขึ้น ดังนั้นกฎจะไม่เปลี่ยนแปลงโดยที่ตัวเลขไม่เปลี่ยนตามไปด้วย ตัวเลขอยู่ที่ iris-eval.com/proof และใน proof/RESULTS.md; วิธีสร้างคลังข้อความ สิ่งที่ไม่ใช่ และวิธีอ่านช่วงความเชื่อมั่นอยู่ใน docs/proof.md คลังข้อความเป็นข้อมูลสังเคราะห์และติดป้ายโดยโมเดล — ป้ายกำกับจากมนุษย์แบบ blinded ยังอยู่ระหว่างดำเนินการ และหน้าเว็บระบุไว้เช่นนั้น; node proof/blind-sample.mjs สุ่มตัวอย่างที่ทำซ้ำได้ซึ่งจะยุติเรื่องนี้

เครื่องมือ MCP

Iris ลงทะเบียนเครื่องมือสิบสองรายการที่เอเจนต์ที่เข้ากันได้กับ MCP ทุกรายการสามารถเรียกใช้ได้ — วงจรชีวิตของ trace และกฎ การเปรียบเทียบข้ามการรัน LLM-as-judge และการตรวจสอบการอ้างอิงเชิงความหมาย:

• log_trace — บันทึกการทำงานของเอเจนต์ด้วย spans, การเรียกเครื่องมือ, การใช้ token และต้นทุน; ส่ง evaluate: true เพื่อให้คะแนนในการเรียกเดียวกัน
• evaluate_output — ให้คะแนนคุณภาพเอาต์พุตเทียบกับกฎความครบถ้วน ความเกี่ยวข้อง ความปลอดภัย และต้นทุน (แบบฮิวริสติก กำหนดตายตัว ไม่มีค่าใช้จ่าย)
• get_traces — ค้นหา trace ที่เก็บไว้ด้วยการกรอง การแบ่งหน้า และการรองรับช่วงเวลา และค้นหารันที่เอเจนต์พูดบางอย่างด้วย q: การค้นหาข้อความเต็มเหนืออินพุต เอาต์พุต ค่าการเรียกเครื่องมือ และ metadata แบบจัดอันดับ โดยทำเครื่องหมายคำที่ตรงกัน
• list_rules — แสดงรายการกฎ eval แบบกำหนดเองที่ใช้งานอยู่ (อ่านอย่างเดียว)
• deploy_rule — ลงทะเบียนกฎ eval แบบกำหนดเองใหม่เพื่อให้ทำงานในทุก evaluate_output ของหมวดหมู่นั้น
• delete_rule — ลบกฎแบบกำหนดเองที่ใช้งานอยู่ (ทำลายล้าง, idempotent)
• delete_trace — ลบ trace ที่เก็บไว้รายการเดียวด้วย ID (ทำลายล้าง, จำกัดเฉพาะ tenant)
• evaluate_with_llm_judge — การประเมินเชิงความหมายผ่าน LLM (Anthropic หรือ OpenAI) เทมเพลตเจ็ดแบบ: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance จำกัดต้นทุน เปิดเผยราคาต่อการประเมิน นำคีย์ API ของคุณเองมา (IRIS_ANTHROPIC_API_KEY หรือ IRIS_OPENAI_API_KEY) — Iris ไม่เป็นพร็อกซีหรือส่งต่อการเรียก LLM
• verify_citations — ดึงการอ้างอิงจากเอาต์พุต (แบบตัวเลข, ผู้แต่ง-ปี, URL, DOI), ดึงแหล่งที่มาผ่านตัวแก้ที่ป้องกัน SSRF + อนุญาตเฉพาะโดเมน และใช้ผู้ตัดสิน LLM เพื่อตรวจสอบว่าแต่ละแหล่งสนับสนุนข้อกล่าวอ้างที่อ้างจริงหรือไม่ การส่ง HTTP ขาออกแบบเลือกใช้ ข้อกำหนด BYOK เดียวกับ evaluate_with_llm_judge
• compare_runs — การเปลี่ยนแปลงทำให้เอเจนต์แย่ลงหรือไม่? เปรียบเทียบสองรันของการประเมินที่เก็บไว้: การทดสอบแบบ paired exact เมื่อรันใช้คีย์เคสเดียวกัน ช่วงความแตกต่างในกรณีอื่น "บอกไม่ได้" อย่างตรงไปตรงมาพร้อมจำนวนเคสที่ต้องใช้ หรือ "เทียบเท่าภายในระยะเผื่อ" ทุกกฎมีการทดสอบแบบด้านเดียวของตัวเอง ซึ่งแก้ไขร่วมกัน (Benjamini–Hochberg) เพื่อให้กฎยี่สิบข้อไม่สามารถสร้างการถดถอยปลอมได้
• compare_traces — เอเจนต์ตอบคำถามเดียวกันได้น่าเชื่อถือแค่ไหน? อัตราผ่านรายเคสพร้อมช่วง ความไม่เสถียรก่อน และอัตราโดยรวมที่เคารพการทำซ้ำ
• evaluate_runs — ให้คะแนนทุก trace ในรันใหม่ภายใต้กฎปัจจุบันเป็นรันใหม่ เพื่อให้การเปลี่ยนแปลงกฎไม่ถูกอ่านว่าเป็นการเปลี่ยนแปลงเอเจนต์

เปิดใช้ผู้ตัดสิน LLM (ไม่บังคับ; กฎกำหนดตายตัวไม่เคยต้องใช้)

1. รับคีย์ API จาก Anthropic หรือ OpenAI
2. ใส่ใน environment ของกระบวนการที่รัน Iris ไม่ใช่แค่ shell ของคุณ Claude Code, Claude Desktop, Cursor และไคลเอ็นต์ MCP ส่วนใหญ่: บล็อก "env" ของรายการ iris-eval ใน config MCP ของคุณ — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY สำหรับคีย์ OpenAI) Docker: -e IRIS_ANTHROPIC_API_KEY=... ในคำสั่งรัน HTTP หรือ CI: export ก่อนเริ่ม iris-eval
3. รีสตาร์ทเซสชัน MCP กระบวนการที่รันอยู่จะไม่เห็นตัวแปรที่ตั้งหลังจากเริ่มต้น
4. ยืนยันจากภายในไคลเอ็นต์ของคุณ: อ่าน iris://capabilities — judge.enabled ต้องเป็น true ที่นั่น คีย์ที่ export ใน shell ของคุณจะไม่ถูกส่งไปยังกระบวนการที่ไคลเอ็นต์ของคุณสร้างขึ้น เว้นแต่ config จะระบุไว้ บนเครื่อง npx @iris-eval/mcp-server --self-test พิมพ์บรรทัดผู้ตัดสินสำหรับ shell นั้น และ GET /api/v1/health รายงาน judge.enabled บนแดชบอร์ดที่รันอยู่
5. การ์ดค่าใช้จ่าย: แต่ละการเรียกถูกจำกัดโดย IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (ค่าเริ่มต้น 0.25 USD) และถูกปฏิเสธก่อนการใช้จ่ายใดๆ หากกรณีเลวร้ายที่สุดจะเกินนั้น Iris เรียกผู้ให้บริการโดยตรงด้วยคีย์ของคุณและไม่เคยเป็นพร็อกซี
6. ไม่บังคับ: ตั้ง IRIS_RELEVANCE_JUDGE_MODEL เป็นรหัสโมเดลที่มีราคา (เช่น claude-haiku-4-5) เพื่อให้ answers_the_ask ถามผู้ตัดสินว่าคำตอบแต่ละข้อตอบคำถามของมันหรือไม่ และล้มเหลวหากนอกประเด็น นั่นคือการเรียกผู้ตัดสินหนึ่งครั้งต่อการประเมินที่มีอินพุต ด้วยคีย์ของคุณและภายใต้การจำกัดข้างต้น; คีย์เพียงอย่างเดียวไม่เคยเปิดใช้งาน แต่ละการเรียกส่งอินพุตและเอาต์พุตนั้นไปยังผู้ให้บริการของโมเดล โดยแทนที่แฟล็ก no_pii สำหรับข้อมูลส่วนบุคคลและข้อมูลรับรองก่อน (IRIS_RELEVANCE_JUDGE_REDACT=off ส่งตามที่เป็น) ใช้จ่ายสูงสุด IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD ต่อวัน UTC (ค่าเริ่มต้น 1 USD) และเรียกสูงสุด IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST ครั้งต่อคำขอ (ค่าเริ่มต้น 20); เกินอย่างใดอย่างหนึ่ง answers_the_ask อ่านคำถามแบบศัพท์และบอกว่าทำไม

เมื่อกำหนดค่า IRIS_OTEL_ENDPOINT แล้ว การเรียก log_trace ยังส่งออก JSON ผ่าน OTLP/HTTP แบบ best-effort ไปยังตัวเก็บ OpenTelemetry ใดๆ (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb ฯลฯ) ดู docs/otel-integration.md

วิธีตัดสิน passed

evaluate_output คืนทั้งแฟล็ก score และ passed — พวกมันตอบคำถามต่างกัน:

• score (0..1) คือค่าเฉลี่ยถ่วงน้ำหนักข้ามกฎที่รัน — การไล่ระดับคุณภาพ
• passed คือคำตัดสิน ship/no-ship และไม่เคยใช้คะแนนสำหรับมัน ตัวประกอบอ่านแต่ละกฎตามประเภทของข้อกล่าวอ้าง: นโยบายที่คุณกำหนดค่าเป็น gate; ตัวตรวจจับวิกฤตเป็น veto; การตรวจสอบวิกฤตที่ถูกขอและตอบไม่ได้ทำให้คำตัดสินเป็น unknown (passed: false) แทนที่จะ clean; ตัวตรวจจับที่เหลือรวมกันเป็นความน่าจะเป็นเดียวว่าเอาต์พุตไม่ดี ชั่งกับอัตราส่วนการสูญเสียที่คุณระบุใน eval.falsePassCost (ค่าเริ่มต้น 1 ดังนั้นจุดตัดคือ 0.5) verdict.basis ระบุเลเยอร์ที่ตัดสินและ verdict.by ระบุกฎ และ verdict.also ระบุทุกเลเยอร์ที่ตามมาที่จะตัดสินมันด้วย; interpretations[] บอกว่าทำไมกฎที่ล้มเหลวจึงไม่ตัดสินและการตั้งค่าใดจะเปลี่ยนสิ่งนั้น และระบุคำถามใดที่ไม่ถูกตัดสินและอินพุตที่จะทำให้ตัดสินได้

การละเมิดความปลอดภัยจริง hard-fail โดยค่าเริ่มต้น no_pii, no_injection_patterns และ no_blocklist_words เป็น กฎวิกฤต: หากหนึ่งล้มเหลว eval รายงาน passed: false ไม่ว่ากฎอื่นจะได้คะแนนดีแค่ไหน และการตอบสนองระบุผู้กระทำผิดใน critical_failures SSN ที่รั่วไม่สามารถเฉลี่ยให้หายไปได้ กฎในตัวใดเป็นวิกฤตคือการตั้งค่าการปรับใช้ (eval.criticalRules / eval.nonCriticalRules); ผลกฎทุกข้อมีแฟล็ก critical ที่มีผลและ criticalSource และ list_rules รายงานรายชื่อที่เซิร์ฟเวอร์นี้ใช้ กฎแบบกำหนดเองที่ปรับใช้ด้วย severity: "high" หรือ "critical" hard-fail ในลักษณะเดียวกัน; ระดับความรุนแรง low/medium มีผลกับคะแนนเท่านั้น ขอบเขตหนึ่งที่ควรรู้ ระบุแบบเดียวกันบนทุกพื้นผิว: กฎวิกฤตที่ ข้าม (บริบทหายไป คำนิยามเสีย หรือ regex ถูกฆ่าที่งบประมาณ sandbox) ไม่ได้ตัดสินเอาต์พุตและไม่ veto — ทุกกฎดังกล่าวถูกระบุชื่อใน critical_skipped gate ที่ต้องปิดเมื่อล้มเหลวถือว่า critical_skipped ที่ไม่ว่างเป็น unknown ไม่ใช่ clean และอาจถือว่าการข้าม budgetExceeded ใดๆ ใน rule_results ในลักษณะเดียวกัน

สำหรับ CI gates: หากคุณละเว้น eval_type ทุก bundle รัน — completeness, relevance, safety, cost และกฎแบบกำหนดเองใดๆ — และการตอบสนองพูด eval_type: "all" พร้อม note ว่าค่าเริ่มต้นรัน บวกแผนที่ categories ต่อ bundle bundle ที่ไม่มีอะไรให้ตัดสิน (cost โดยไม่มี cost_usd, relevance โดยไม่มี input) รายงาน passed: null ที่นั่น — ไม่ถูกประเมิน ไม่ล้มเหลว — และไม่นับรวมในคำตัดสิน การตอบสนองสะท้อน eval_type ที่รันเสมอ เพื่อให้ gate ของคุณตรวจสอบความครอบคลุมได้; ใช้ passed สำหรับคำตัดสินและระบุ bundle เฉพาะเมื่อคุณต้องการรันที่แคบลง

การสร้างกฎแบบกำหนดเอง

สองวิธีในการเพิ่มกฎ Inline กฎมากับการเรียก evaluate_output หนึ่งครั้ง (custom_rules, สูงสุด 10 ต่อการเรียก); พวกมันทำงานพร้อมกับ bundle eval_type ที่คุณเลือก หรือเพียงลำพังด้วย eval_type: "custom" Deployed กฎลงทะเบียนครั้งเดียวด้วย deploy_rule, คงอยู่ใน custom-rules.json ภายใต้ Iris home ของคุณ และทำงานในทุก evaluate_output ในอนาคตของ evalType คำนิยามมีรูปร่างเดียวกันทั้งสองวิธี:

deploy_rule ห่อคำนิยามด้วย name, description ไม่บังคับ, evalType (completeness · relevance · safety · cost · custom) และ severity ระดับความรุนแรงบอกว่า ความล้มเหลว หมายถึงอะไร: low/medium ลดคะแนนเท่านั้น; high/critical hard-fail การประเมิน — passed: false, กฎที่ระบุชื่อใน critical_failures — ไม่ว่าคะแนนถ่วงน้ำหนักจะพูดอะไร กฎที่ข้าม (กฎ cost_threshold โดยไม่มี cost_usd, หรือ regex ที่ถูกฆ่าที่งบประมาณ sandbox 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" }
  }
}

การตอบสนองคือกฎที่คงอยู่ — เก็บ id สำหรับ delete_rule:

{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }

จาก evaluate_output ถัดไปด้วย eval_type: "safety", เอาต์พุตที่กล่าวถึง db-primary.internal.example กลับมาเป็น passed: false พร้อม critical_failures: ["no_internal_hostnames"] — แม้ว่ากฎความปลอดภัยในตัวทั้งห้าผ่านและคะแนนถ่วงน้ำหนักคือ 0.895 รูปแบบ regex ต้องผ่านการตรวจสอบ ReDoS ที่เวลาปรับใช้และรันในเวิร์กเกอร์ sandbox ภายใต้กำหนดเวลา 100 ms เสมอ list_rules แสดงสิ่งที่ปรับใช้; ตัวประกอบกฎของแดชบอร์ดสร้างรูปร่างเดียวกันจากความล้มเหลวที่คุณคลิก ข้อมูลอ้างอิงเต็ม การให้คะแนนต่อประเภท และตัวอย่างที่ใช้งานได้: docs/custom-rules.md

สคีมาเครื่องมือเต็มและการกำหนดค่า: iris-eval.com

ฟีเจอร์โฮสต์

Iris รันบนเครื่องของคุณทั้งหมดในวันนี้ และทุกสิ่งที่ทำฟรีและได้รับอนุญาต MIT โดยไม่มีขีดจำกัดและไม่มีบัญชี โฮสต์สตอเรจ ประวัติทีมที่แชร์ร่วมกัน และการแจ้งเตือน อยู่ระหว่างการพิจารณา ไม่ได้อยู่ระหว่างการพัฒนา ยังไม่มีราคา และไม่มีอะไรให้ซื้อ หากประวัติที่แชร์ร่วมกันมีประโยชน์สำหรับคุณ รายชื่อรอ คือวิธีที่เราจะค้นหาว่ามันคุ้มค่าที่จะสร้างหรือไม่ — มันไม่ได้ผูกมัดคุณแต่อย่างใด

มีข้อผูกมัดสองข้อที่คงไว้ไม่ว่าในกรณีใด: สิ่งที่ฟรีในวันนี้จะไม่ถูกย้ายไปอยู่หลังเพย์วอลล์ และ จะไม่มีการอ้างสิทธิ์การรับรองความสอดคล้องก่อนที่จะได้รับการรับรองจริง

ตัวอย่าง

• การตั้งค่า Claude Desktop — การกำหนดค่า MCP สำหรับโหมด stdio และ HTTP
• TypeScript — MCP SDK client — เชื่อมต่อและเรียกใช้เครื่องมือ
• HTTP transport (TS + Python) — โค้ดไคลเอนต์แบบเต็มสำหรับการผสานรวมแบบ REST
• เอเจนต์ LangGraph ให้คะแนนทีละรัน (Python) — IrisCallbackHandler ใน callbacks ของกราฟ; CI รันกราฟเดียวกันกับโมเดลที่เขียนสคริปต์ไว้
• ทีม CrewAI บน OpenTelemetry (Python) — ตัว instrumentor ของ OpenInference ส่งตรงไปยังประตู OTLP ของ Iris, สูตร CrewAI เป็นสคริปต์
• เอเจนต์ OpenAI Agents SDK บน OpenTelemetry (Python) และ (JavaScript), และ เอเจนต์ LlamaIndex — แต่ละสูตรเป็นสคริปต์ที่ CI รันกับเซิร์ฟเวอร์ Iris จริง

ชุมชน

• GitHub Issues — รายงานบั๊กและคำขอฟีเจอร์
• GitHub Discussions — คำถามและไอเดีย
• คู่มือการมีส่วนร่วม — วิธีมีส่วนร่วม
• HTTP Ingest — การจับ trace แบบกำหนดได้ผ่าน POST /api/v1/traces
• แผนที่ความสามารถ — ทุกคำถามที่ถาม Iris ได้ และสิ่งที่ขาดหายไป
• นโยบายเวอร์ชัน — แต่ละหมายเลขเวอร์ชันสัญญาอะไร และอะไรที่ต้องเป็นจริงก่อนเวอร์ชัน 1.0

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

# 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

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

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

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

npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3

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

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

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

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

If Iris is useful to you, consider starring the repo — it helps others find it.

MIT Licensed.