Iris

官方

MCP原生代理评估与可观测性服务器，具备追踪日志、输出质量评估、成本追踪、12条内置评估规则、实时仪表盘及PII检测功能

文档

Iris — MCP 的智能体评估标准

了解你的 AI 智能体是否真的足够好，可以交付使用。 Iris 是一个开源的 MCP 服务器，能够对所有智能体的输出质量进行评分、捕获安全故障，并强制执行成本预算。任何兼容 MCP 的智能体都能自动发现并使用它——无需 SDK，无需更改代码。

Iris Dashboard

问题所在

你的智能体正在生产环境中运行。基础设施监控看到 200 OK 就认为一切正常。它完全不知道智能体刚刚：

在其响应中泄露了一个社会安全号码
凭空捏造了一个毫无事实依据的答案
单次查询就烧掉了 0.47 美元——是你预算阈值的 4.7 倍
进行了 6 次工具调用，而实际上 2 次就足够了

Iris 会评估所有这些方面。

你能获得什么


追踪日志	带有每次工具调用延迟、令牌使用量和美元成本的分层跨度树。存储在 SQLite 中，可即时查询。
输出评估	涵盖 4 个类别的 13 条内置规则：完整性、相关性、安全性、成本。PII 检测（10 种模式：SSN、信用卡、电话、电子邮件、IBAN、出生日期、MRN、IP、API 密钥、护照），提示注入（13 种模式），存根输出检测，幻觉标记（17 个模糊措辞短语 + 虚构引用启发式方法）。可使用 Zod 模式添加自定义规则。
成本可见性	在任何时间窗口内汇总所有智能体的成本。设置预算阈值。当智能体超支时收到标记。
Web 仪表板	实时深色模式 UI，包含追踪可视化、评估结果和成本明细。

需要 Node.js 20 或更高版本。 使用 node --version 检查。

快速开始

将 Iris 添加到你的 MCP 配置中。适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Cline、Zed、Codex CLI、Gemini CLI——以及任何其他兼容 MCP 的智能体。

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

就是这样。你的智能体会自动发现 Iris 并开始记录追踪。

开启仪表板

Iris 附带一个实时 Web 仪表板，显示追踪、评估结果、成本明细和规则通过率。默认情况下它是关闭的，以保持 MCP 服务器的轻量级——通过一个标志即可开启。

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

然后在你的智能体运行追踪后，打开 **http://localhost:6920**。同样的仪表板也可通过 CLI 使用：

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

按工具设置

Claude Desktop

编辑你的 MCP 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

添加上面的 JSON 配置，然后重启 Claude Desktop。

Claude Code

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

然后重启会话（/clear 或重新启动）以加载工具。

Windows 注意： 请勿使用 cmd /c 包装器——它会导致路径解析问题。npx 命令可以直接使用。

Cursor / Windsurf

使用上面的 JSON 配置，添加到你的工作区 .cursor/mcp.json 或全局 MCP 设置中。

VS Code（原生 MCP）

添加到工作区中的 .vscode/mcp.json（注意：VS Code 使用 servers，而不是 mcpServers）：

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

Cline

打开 Cline 的 MCP 服务器面板 → 配置 MCP 服务器，并将上面的 mcpServers JSON 配置添加到 cline_mcp_settings.json。

Zed

添加到 Zed 的 settings.json：

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

OpenAI Codex CLI

添加到 ~/.codex/config.toml：

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

Gemini CLI

将上面的 mcpServers JSON 配置添加到 ~/.gemini/settings.json。

任何其他支持 MCP 的工具

Iris 是一个标准的 stdio MCP 服务器——只需一个 npx @iris-eval/mcp-server 命令，无需 SDK，无需更改代码。如果你的客户端支持 MCP，它就支持 Iris。客户端配置格式可能会变化；如有疑问，请查阅客户端的 MCP 文档并将其指向该命令。

其他安装方法

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

# Docker
docker run -p 3000:3000 -v iris-data:/data ghcr.io/iris-eval/mcp-server

提示： 全局安装（npm install -g）会将追踪数据持久化存储在 ~/.iris/iris.db。使用 npx 时，追踪数据会持久化在同一位置，但由于包解析，启动速度较慢。

MCP 工具

Iris 注册了九个工具，任何兼容 MCP 的智能体都可以调用——完整的规则 + 追踪生命周期 + LLM 作为评判者 + 语义引用验证：

log_trace — 记录智能体执行情况，包括跨度、工具调用、令牌使用量和成本
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 一样需要自带密钥。

当配置了 IRIS_OTEL_ENDPOINT 时，log_trace 调用还会尽最大努力将 OTLP/HTTP JSON 导出到任何 OpenTelemetry 收集器（Jaeger、Grafana Tempo、Datadog OTLP、Honeycomb 等）。请参阅 docs/otel-integration.md。

完整的工具模式和配置： iris-eval.com

云层级（即将推出）

自托管的 Iris 在你的机器上使用 SQLite 运行。随着你团队评估需求的增长，云层级将增加 PostgreSQL、团队仪表板、质量回归警报以及托管基础设施。

加入等候名单以获取早期访问权限。

示例

Claude Desktop 设置 — stdio 和 HTTP 模式的 MCP 配置
TypeScript — MCP SDK 客户端 — 连接并调用工具
HTTP 传输（TS + Python） — 用于 REST 风格集成的完整客户端代码
LangChain 集成（Python，概念性） — 展示结构的脚手架；需要你的智能体代码才能运行
CrewAI 集成（Python，概念性） — 脚手架；同样的注意事项

社区

GitHub Issues — 错误报告和功能请求
GitHub Discussions — 问题和想法
贡献指南 — 如何贡献
路线图 — 即将推出的内容

配置与安全

CLI 参数

标志	默认值	描述
`--transport`	`stdio`	传输类型：`stdio` 或 `http`
`--port`	`3000`	HTTP 传输端口
`--db-path`	`~/.iris/iris.db`	SQLite 数据库路径
`--config`	`~/.iris/config.json`	配置文件路径
`--api-key`	—	用于 HTTP 认证的 API 密钥
`--dashboard`	`false`	启用 Web 仪表板
`--dashboard-port`	`6920`	仪表板端口

环境变量

变量	描述
`IRIS_TRANSPORT`	传输类型（`stdio` 或 `http`）
`IRIS_PORT`	HTTP 传输端口
`IRIS_HOST`	HTTP 传输主机（默认 `127.0.0.1`）
`IRIS_DB_PATH`	SQLite 数据库路径
`IRIS_LOG_LEVEL`	日志级别：`debug`、`info`、`warn`、`error`
`IRIS_DASHBOARD`	启用 Web 仪表板（`true`/`false`）
`IRIS_DASHBOARD_PORT`	仪表板端口（默认 `6920`）
`IRIS_API_KEY`	用于 HTTP 认证的 API 密钥
`IRIS_ALLOWED_ORIGINS`	逗号分隔的允许的 CORS 来源

当两者都设置时，CLI 标志优先于环境变量。

安全

使用 HTTP 传输时，Iris 包括：

使用时间安全比较的 API 密钥认证
默认限制为 localhost 的 CORS
速率限制（API 100 次请求/分钟，MCP 20 次请求/分钟）
Helmet 安全标头
所有路由上的 Zod 输入验证
用于自定义评估规则的 ReDoS 安全正则表达式
1MB 请求体限制

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

故障排除

Iris 无法启动 / `ERR_MODULE_NOT_FOUND`

你可能缓存了旧版本。清除 npx 缓存并重试：

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

或者全局安装以完全避免缓存问题：

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

工具未在 Claude Code 中显示

MCP 工具仅在会话启动时加载。添加 iris-eval 后，使用 /clear 重启会话或重新启动终端。

版本检查

验证正在运行的版本：

npx @iris-eval/mcp-server --help
# Shows "Iris — MCP-Native Agent Eval 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.js 版本

Iris 需要 Node.js 20 或更高版本。Node 18 已于 2025 年 4 月终止支持，不受支持。

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

Windows：不需要 `cmd /c`

Claude Code 的 /doctor 可能会建议使用 cmd /c 包装 npx。这没有必要，并且会导致路径解析问题。直接使用 npx：

# 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 许可。