evals-mcp-server

---

概述

使用服务端强制执行的评分器构建可验证的评测记录。为记录草拟自带可执行评分器，逐字段修订，并通过提交关卡：该关卡要求标准答案通过、负例失败，且独立检查结果一致。可导出为 JSONL、CSV、Inspect AI 或 lm-evaluation-harness。

工具

工具	描述
evals_describe_schema	返回某种任务类型的必填字段、可选字段和评分器选项。请在草拟前调用。
evals_create_draft	创建带有自身评分器的评测记录草稿；返回解析后的记录、审核流程和验证子 Agent 提示词。
evals_get_record	按 ID 读取草稿或已提交的记录；提交前后 ID 保持不变。
evals_revise_draft	按点分路径对草稿应用精确的 set / append / unset 补丁；并重新运行自洽性检查。
evals_discard_draft	按 ID 删除草稿记录。仅适用于草稿。
evals_run_check	对候选答案运行评分器规范，并获取每个候选答案的 PASS/REJECT 结果；与任何已保存记录解耦。
evals_submit_draft	通过可提交性关卡最终确定草稿，然后将其冻结。
evals_list_records	按状态、领域、任务类型或标签浏览和筛选记录。每条记录均返回精简摘要。
evals_export_records	将已提交记录编译为 JSONL、CSV、Inspect AI 或 lm-evaluation-harness，并将产物写入 exports/。

资源

资源	描述
eval://record/{id}	按 id 查询单条草稿或已提交记录——对于支持资源的客户端，其载荷与 evals_get_record 返回的相同。

所有记录数据也都可通过工具接口访问——使用 evals_get_record 获取单条记录，使用 evals_list_records 浏览记录。资源只是为支持资源的客户端提供的便捷镜像，并非访问途径。

功能参考

evals_describe_schema _工具

• 接受 task_type：numeric、exact_answer、set_answer、mcq、regex_answer、json_answer 或 free_response。
• 返回静态模式中的标准答案结构、评分器类型、必填/可选字段和编写说明；mcq 必须提供 choices，free_response 必须提供 llm_rubric。

---

evals_create_draft _工具

• 接受包含评分器和区分案例的记录，以及可选的 verification 和 captures（EvalsIDs）；mcq 必须提供 choices，free_response 必须提供 llm_rubric。
• 评分器运行后，将记录保存为 draft，并返回规范化记录、审核协议、验证子 Agent 提示词，以及提交操作仍需满足的条件。即使草稿的标准答案未通过评分器，也仍会保存。
• 类型化错误：grader_unexecutable、task_type_constraint、mcq_choice_mismatch。

---

evals_get_record _工具

• 按 id 读取草稿或已提交记录；提交后该 id 仍保持不变。
• 返回完整的评分器、区分案例和验证证据；not_found 会指向 evals_list_records。

---

evals_revise_draft _工具

• 按点分隔路径对草稿应用 set、append 和 unset 操作；无法更改 task_type 和服务端管理的字段，数组只能整体替换或追加，不能按索引编辑。
• 写入前会重新验证记录和评分器，然后返回记录以及 changed 条目（op、path、before、after）。未知路径会导致整个补丁被拒绝。
• 类型化错误：not_found、已提交 id 对应的 record_frozen、invalid_patch_path、grader_unexecutable、task_type_constraint、mcq_choice_mismatch。

---

evals_discard_draft _工具

• 按 draft_id 删除草稿，并返回 discarded: true。
• 对已提交的记录会返回 record_frozen；id 不存在或已被丢弃时会返回 not_found。

---

evals_run_check _工具

• 对一个或多个 candidates 运行评分器，无需保存记录；对于 exact_match，请提供 gold，而 numeric 和 mcq 等目标嵌入类型会忽略它。
• 返回每个候选项的 PASS/REJECT、detail 和已解析的 resolved 引用。此处无法运行 llm_rubric。
• 数值评分仅接受有限实数值；带单位、复数、非有限值和非标量候选项都会被拒绝。units 仅供文档说明使用。
• 类型化错误：grader_unexecutable、mcq_choice_mismatch。

---

evals_submit_draft _工具

• 按 draft_id 完成提交：标准答案必须通过（PASS），至少一个负例必须被拒绝（REJECTED），且去相关验证必须一致。还会检查 captures 是否符合 EVALS_CAPTURE_DIR，拒绝重复的 content_hash，并可通过 confirm 或 EVALS_REQUIRE_CONFIRMATION 请求确认。
• 成功后会冻结记录，写入 submitted_at 和 checksum，并返回 status: submitted；拒绝提交时草稿保持不变。free_response 记录仅依赖验证，并标记为 server_verified: false。
• 类型化错误：not_found、record_frozen、verification_incomplete、grader_failed_on_gold、verification_disagrees_with_gold、missing_negative_case、negative_case_passed、duplicate、decorrelation_violation、capture_unresolved、submit_declined。

---

evals_list_records _工具

• 按 status（draft/submitted）、domain、task_type 或 tag 筛选；limit 为正整数，默认值为 50。
• 按时间从新到旧返回摘要（id、status、task_type、domain、tags、时间戳），并包含 shown、cap、totalCount 和 truncated。

---

evals_export_records _工具

• 将 submitted 记录导出为 jsonl（无损）、csv（有损摘要）、inspect（Inspect AI）或 lm-eval（lm-evaluation-harness），并可按 domain、task_type 或 tag 筛选。
• 将文件写入 exports/，并返回路径、记录数、字节大小和预览。

---

eval://record/{id} _资源

• 从 evals_list_records 或草稿/提交响应中读取 id。
• 返回 evals_get_record 的内容，类型为 application/json；如果没有匹配记录，则返回 not_found。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

评测编写：

• 采用 draft → review → surgical-revise → submit 流程；服务既存储记录，也运行每条记录自带的评分器，拒绝不合格的记录
• 七种任务类型：numeric、exact_answer、set_answer、mcq、regex_answer、json_answer、free_response
• 每条记录都序列化保存一个评分器；确定性类型（通过 math.js 执行的 numeric、exact_match、set_match、regex、mcq、json_match）在服务端运行，而 llm_rubric 依赖已记录的独立验证
• 提交门槛：标准答案必须通过自身评分器，至少一个负例必须被拒绝，并且已记录的去相关验证必须与标准答案一致
• EVALS_DATA_DIR 下的纯 JSON 文件；草稿、已提交记录和导出文件分别存放

面向 Agent 的输出：

• evals_create_draft 和 evals_revise_draft 会返回解析后的记录、逐字段审查协议，以及可直接粘贴使用的验证子 Agent 提示词
• 草稿和修订响应会报告每个正例和负例的通过/拒绝结果
• 达到限制时，evals_list_records 会报告 shown / cap / 总数
• 提交门槛失败时，会返回类型化的 reason 和恢复提示

开始使用

将以下内容添加到 MCP 客户端配置文件中。将 EVALS_DATA_DIR 设为可写目录——服务会在该目录下管理 drafts/、submitted/ 和 exports/。

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/evals-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EVALS_DATA_DIR": "/absolute/path/to/evals-data"
      }
    }
  }
}

也可以使用 npx（无需安装 Bun）：

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/evals-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EVALS_DATA_DIR": "/absolute/path/to/evals-data"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "evals-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "evals-data:/usr/src/app/evals-data",
        "ghcr.io/cyanheads/evals-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 EVALS_DATA_DIR=./evals-data bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• EVALS_DATA_DIR 的可写目录。无需外部 API 密钥。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/evals-mcp-server.git

2. 进入目录：

cd evals-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set EVALS_DATA_DIR

配置

所有服务配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。

变量	描述	默认值
EVALS_DATA_DIR	记录 JSON 的根目录；存储服务会在其下管理 drafts/、submitted/ 和 exports/。	./evals-data
EVALS_REQUIRE_CONFIRMATION	为 true 时，evals_submit_draft 会在最终提交前通过多轮输入请求人工确认。	false
EVALS_DEFAULT_LICENSE	草稿未指定许可证时应用的默认 metadata.license（例如 CC-BY-4.0）。	—
EVALS_CAPTURE_DIR	框架写入的工具调用捕获文件目录；设置后，captures EvalsIDs 会解析为完整转储。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless；由于提交确认需要活动会话，因此不接受 stateless。	stateful
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参阅 .env.example。

提交确认会在 10 分钟后过期，且草稿发生更改时必须重新确认。运行多个实例时，请使用共享存储（STORAGE_PROVIDER_TYPE=filesystem 并设置共享的 STORAGE_FILESYSTEM_PATH、supabase 或 cloudflare-d1；不要使用 cloudflare-kv），并在每个实例上设置相同的 MCP_REQUEST_STATE_KEY（至少 32 字节）。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t evals-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio -v evals-data:/usr/src/app/evals-data evals-mcp-server

Dockerfile 默认使用 HTTP 传输、有状态会话模式，并将日志写入 /var/log/evals-mcp-server。将记录存储挂载到 /usr/src/app/evals-data，这是运行时用户拥有的默认目录。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化记录存储与导出器服务。
src/config	使用 Zod 解析并验证服务专用的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/eval-record	记录模式、草稿构建器和提交门控。
src/services/grader	确定性评分器 DSL 执行和可提交性检查。
src/services/record-store	磁盘上的 JSON 记录 CRUD、草稿→已提交的移动操作以及导出写入。
src/services/exporter	将已提交的记录编译为 JSONL/CSV/Inspect/lm-eval。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录；记录由 record-store 服务持久化到磁盘，而非存储在 ctx.state 中
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 服务端是事实来源——验证输入，将评分器作为硬性门槛运行，绝不能仅凭断言就接纳记录

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。