Iris

Iris — 別再憑感覺交付 Agent

Iris 為每次 agent 執行評分品質、安全性與成本——在你的機器上執行，無需 SDK、無需帳號。 多數 agent 專案用幾個記得的提示詞跑一遍、肉眼看看輸出，就當作品質檢查。Iris 用你可以稽核的數字取代這套做法：你的 agent 執行記錄會存入你磁碟上的 SQLite 資料庫，13 條內建規則以確定性方式為它們評分——PII、提示注入、幻覺標記、成本門檻——完全免費，不需呼叫 LLM，另有選用的 LLM 評審（設有每次評估的硬性成本上限）處理語意層面的問題。每一條規則都可檢視、可編輯，因為一個你無法稽核的評審，不過是掛上數字的感覺罷了。MIT 授權，無遙測；你的追蹤軌跡永遠不會離開你的機器。

需要 Node.js 20 或更新版本。 用 node --version 檢查。

60 秒內在螢幕上看到失敗案例

不需要接 agent、不需要設定——一行指令：

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

這會建立一個示範資料庫——少數幾個小型 agent 加上一週的執行記錄——並在 http://localhost:6920 提供儀表板（首次執行時瀏覽器會自動開啟）。儀表板預設停在 Failures（失敗）頁面：顯示哪些失敗了，最嚴重的排最前、最新的排最前。值得點進去看看——一條被安全規則攔截的 PII 外洩、一筆被標記的提示注入嘗試，以及一個失敗的 LLM 評審分數及其理由。

示範資料存放在獨立的資料庫中（位於你的 Iris 主目錄下的 demo.db——macOS/Linux 為 ~/.iris，Windows 為 %USERPROFILE%\.iris），絕不會與你的真實追蹤軌跡混在一起。用一行指令就能全部清除：

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

接上你自己的 agent

將 Iris 加入你的 MCP 設定。支援 Claude Desktop、Claude Code、Cursor、Windsurf、Continue、VS Code、Cline、Zed、Codex CLI、Gemini CLI——以及任何其他相容 MCP 的 agent。一個設定區塊，儀表板隨附在內：

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

你的 agent 在連線時會發現 Iris 的九個工具，儀表板則在 http://localhost:6920. 提供服務。現在把這段話貼給你的 agent：

把剛剛那項任務記錄到 Iris 並評估輸出。

追蹤軌跡會連同評分一起出現在儀表板上。偏好無頭模式（headless）的 MCP 伺服器？從參數中移除 --dashboard 即可——你隨時可以用 npx @iris-eval/mcp-server --dashboard 開啟同一個儀表板。

有一件事值得先知道： MCP 工具是在模型決定呼叫它們時才被呼叫。Iris 不會攔截你的 agent，所以追蹤軌跡是在你的 agent 要求記錄時才會被記錄——無論是你叫它記錄，還是你的程式碼直接呼叫工具。叫你的 agent「把這個記錄到 Iris 並評估」它就會照做。如果你想要不依賴模型選擇的擷取方式，POST /api/v1/traces 正是做這件事的——你的程式碼透過純 HTTP 傳送追蹤軌跡，模型不參與其中（見 docs/http-ingest.md）。路線圖 上的 CLI 和 SDK 將是同一端點的輕量客戶端。

透過 HTTP 擷取（模型不參與）

只要儀表板在執行，任何能傳送 HTTP 請求的東西都可以記錄追蹤軌跡——也可以在同一個請求中選擇性地執行確定性評估：

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 與評估結果。此端點接受與 log_trace 工具相同的要求主體，並與儀表板其餘部分共用同一套僅限 loopback 的中介軟體堆疊。完整的契約、欄位參考與錯誤語意：docs/http-ingest.md。

檢查安裝

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

離線安裝診斷：儲存來回寫入、確定性評估、儀表板 + DNS-rebinding 防護——全部在隔離的暫存家目錄中執行，因此你的真實資料庫絕不會被打開。結束代碼 0 = 正常，1 = 有檢查項目失敗。

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

其他安裝方式

# 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

提示： 全域安裝（npm install -g）會將追蹤軌跡持久儲存在 ~/.iris/iris.db。使用 npx 時，追蹤軌跡會持久儲存在相同位置，但由於套件解析的關係，啟動速度較慢。

你獲得的功能

接下來要往哪裡走：路線圖。

MCP 工具

Iris 註冊了九個工具，任何相容 MCP 的 agent 都可以呼叫——完整的規則 + 追蹤軌跡生命週期 + LLM 評審 + 語意引用驗證：

• log_trace — 記錄一次 agent 執行，包含 spans、工具呼叫、token 用量與成本
• evaluate_output — 針對完整性、相關性、安全性與成本規則，為輸出品質評分（啟發式、確定性、免費）
• get_traces — 查詢已儲存的追蹤軌跡，支援篩選、分頁與時間範圍
• list_rules — 列舉已部署的自訂評估規則（唯讀）
• deploy_rule — 註冊新的自訂評估規則，使其在該類別的每次 evaluate_output 時觸發
• delete_rule — 移除已部署的自訂規則（破壞性、冪等）
• delete_trace — 依 ID 移除單一已儲存的追蹤軌跡（破壞性、租戶範圍內）
• evaluate_with_llm_judge — 透過 LLM 進行語意評估（Anthropic 或 OpenAI）。五種模板：準確度、有用性、安全性、正確性、忠實度。有成本上限，每次評估的價格會揭露。使用你自己的 API 金鑰（IRIS_ANTHROPIC_API_KEY 或 IRIS_OPENAI_API_KEY）——Iris 不會代理或轉送 LLM 呼叫。
• verify_citations — 從輸出中擷取引用（編號式、作者-年份、URL、DOI），透過具 SSRF 防護 + 網域白名單的解析器抓取來源，並使用 LLM 評審檢查每個來源是否確實支持被引用的主張。選擇性的對外 HTTP。與 evaluate_with_llm_judge 相同的 BYOK 要求。

當設定了 IRIS_OTEL_ENDPOINT 時，log_trace 呼叫也會以盡力而為的方式發出 OTLP/HTTP JSON 匯出至任何 OpenTelemetry collector（Jaeger、Grafana Tempo、Datadog OTLP、Honeycomb 等）。見 docs/otel-integration.md。

passed 如何決定

evaluate_output 同時回傳 score 與 passed 旗標——它們回答不同的問題：

• score（0..1）是已執行規則的加權平均——一個品質梯度。
• passed 是放行/不放行的判定：只有當分數超過通過門檻（預設 0.7）且沒有任何重大規則失敗時，true 才會成立。

真正的安全違規會直接判定失敗。no_pii、no_injection_patterns 與 no_blocklist_words 是重大規則：只要其中一條失敗，無論其他規則得分多高，評估都會回報 passed: false，且回應會在 critical_failures 中指名肇事者。外洩的 SSN 無法靠平均淡化。使用 severity: "high" 或 "critical" 部署的自訂規則會以相同方式直接判定失敗；low/medium 嚴重度只會影響分數。有一個界線要知道：被跳過的重大規則（缺少脈絡，或其他任何導致跳過的原因）並未評判輸出，因此不會否決——rule_results 會顯示每次跳過及其原因，因此需要對非判定結果採取 fail-closed 的閘門可以據此處理。

CI 閘門有一個常見陷阱：如果你省略了 eval_type，預設的 completeness 規則組合會執行——安全規則不會。回應會回顯 eval_type（加上預設時的 note），因此你的閘門可以驗證實際執行的是哪個規則組合。判定時以 passed 為依據，涵蓋範圍則看 eval_type: "safety"。

完整的工具 schema 與設定：iris-eval.com

雲端代管功能

Iris 目前完全在你的機器上執行，它所做的一切都是免費且 MIT 授權，沒有上限、不需帳號。

雲端代管儲存、團隊共享歷史與警示正在考慮中，尚未動工。目前沒有定價，也沒有任何可購買的東西。如果共享歷史對你有用，等待名單 是我們了解這件事是否值得做的管道——它不會讓你承擔任何義務。

無論如何有兩個承諾不變：今天免費的東西絕不會移到付費牆後面，以及在真正取得合規認證之前，絕不宣稱擁有該認證。

範例

• Claude Desktop 設定 — stdio 與 HTTP 模式的 MCP 設定
• TypeScript — MCP SDK 客戶端 — 連線並呼叫工具
• HTTP 傳輸（TS + Python） — REST 風格整合的完整客戶端程式碼
• LangChain 儀器化（Python，概念性） — 顯示架構的範本；需要你的 agent 程式碼可執行
• CrewAI 儀器化（Python，概念性） — 範本；同樣的注意事項

社群

• GitHub Issues — 錯誤回報與功能請求
• GitHub Discussions — 問題與想法
• Contributing Guide — 如何貢獻
• HTTP Ingest — 透過 POST /api/v1/traces 進行確定性追蹤擷取
• Roadmap — 接下來會推出什麼

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

如果 Iris 對您有用，請考慮為儲存庫加星 — 這有助於其他人找到它。

MIT 授權。