内容
<div align="center">
<h1>评估记录服务器</h1>
<p><b>通过草稿 → 审查 → 修订 → 提交的循环，验证评估记录，并由服务器强制执行评分器；编译为 JSONL/CSV/Inspect/lm-eval，支持 STDIO 或 Streamable HTTP。</b>
<div>9 个工具 • 1 个资源</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/evals-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/evals-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/evals-mcp-server/releases/latest/download/evals-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=evals-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZXZhbHMtbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22evals-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fevals-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
---
## 工具列表
九个用于创建评估记录的工具，包括草稿循环（创建、修订、丢弃、提交）、独立的确定性检查器，以及读取/列出/导出：
| 工具 | 描述 |
|:---|:---|
| `evals_describe_schema` | 返回给定任务类型的必填和可选字段以及评分器选项。在草拟前调用。 |
| `evals_create_draft` | 创建一个带有自己的评分器的草稿评估记录；返回解析的记录、审查协议和验证子代理提示。 |
| `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/` 下。 |
### `evals_describe_schema`
返回给定 `task_type` 的记录在草拟前所需的内容。
- 静态 - 源自记录和评分器 Zod 模式，无磁盘或运行时状态
- 按类型划分的金色形状、适当的评分器种类（s）、必填/可选字段和作者注释
- `task_type` 是 `numeric`、`exact_answer`、`set_answer`、`mcq`、`regex_answer`、`json_answer`、`free_response` 之一
---
### `evals_create_draft`
创建并持久化草稿评估记录，然后将其反映回作为审查强制功能。
- 验证 `task_type` 区分联合（类型规则：`mcq` 需要 `choices`；`free_response` 需要 `llm_rubric` 评分器）
- 运行廉价的自一致性检查 - 评分器 vs 金色，每个积极的必须通过，每个消极的必须拒绝
- 返回规范化的记录在分割线后面回声，一个按字段的审查协议，一个准备好的验证子代理提示，以及提交前仍需要的内容
- 可选的草稿时间 `verification` 块和 `captures`（EvalsIDs），当您已经拥有出处时
- 保持 `draft` - 通过自一致性证明评分器区分，不意味着金色是正确的
---
### `evals_revise_draft`
对草稿进行手术修补，使每次更改保持可读。
- 明确的 `set`（点路径 → 值）、`append`（点路径 → 数组项）和 `unset`（点路径）操作 - 不是完整的记录重写
- 返回更新的记录、更改的逐项列表和重新运行的自一致性判决
- 重新验证修补后完整的形状和跨字段约束
- 仅限草稿 - 提交的记录是冻结的；`task_type` 不能被修补（开始新草稿以更改判别式）
---
### `evals_run_check`
在不触及保存的记录的情况下，运行评分器对抗一个或多个候选者。
- 每个候选者返回 PASS/REJECT 以及解析的比较值（例如 math.js 评估的数字目标），以便您了解每个匹配或错过的原因
- `candidates` 接受字符串、数字、对象或数组 - 任何评分器种类期望的内容
- 为金色相对种类（`exact_match`）提供 `gold`；对于像 `numeric` 和 `mcq` 这样的目标嵌入种类，它是无操作的
- `llm_rubric` 不能在这里运行 - 它在提交时通过采样进行评分
---
### `evals_submit_draft`
将草稿通过可提交门槛，然后冻结它。
- 门槛运行评分器对抗金色（必须通过），要求 ≥1 个声明的负面案例被拒绝，并要求记录的、去相关的独立验证同意金色
- 解析和嵌入 `captures` EvalsID，当且仅当 `EVALS_CAPTURE_DIR` 被设置时
- 拒绝重复项（已提交的相同 `content_hash`）
- 成功时，将记录翻转为 `submitted`，标记 `submitted_at` 和 `checksum`，并冻结它；否则拒绝并带有类型错误和恢复提示，记录保持草稿状态
- `free_response` `llm_rubric` 通过采样进行判断，当客户端支持时，否则仅凭记录的验证，并标记 `server_verified: false`
---
### `evals_export_records`
将提交的记录编译为下游评估格式。
- `jsonl`（无损，通用语言）、`csv`（扁平化、损耗的电子表格摘要）、`inspect`（UK AISI Inspect AI）、`lm-eval`（EleutherAI lm-evaluation-harness）
- 可选的 `domain` / `task_type` / `tag` 过滤器
- 仅导出已提交的记录 - 草稿被跳过
- 将制品写入 `exports/` 下并返回文件路径、记录计数、字节大小和简短预览，而不是内联转储
## 资源
| 类型 | 名称 | 描述 |
|:---|:---|:---|
| 资源 | `eval://record/{id}` | 按 ID 的单个草稿或提交的记录 - 与 `evals_get_record` 返回的相同有效载荷，供支持资源的客户端使用。 |
所有记录数据也可以通过工具表面访问 - `evals_get_record` 获取单个记录，`evals_list_records` 浏览。
## 功能
基于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)：
- 声明式工具和资源定义 - 每个基元一个文件，框架处理注册和验证
- 统一错误处理 - 处理程序抛出，框架捕获、分类和格式化
- 类型错误合约 - 工具声明其领域故障（原因 + 恢复），呈现给代理
- 可插拔身份验证：`none`、`jwt`、`oauth`
- 带有可选 OpenTelemetry 跟踪的结构化日志记录
- STDIO 和 Streamable HTTP 传输
评估创作：
- 一个 `draft → review → surgical-revise → submit` 循环，服务器充当书记员（规范化、持久化、编译）和对抗检查者（运行记录自己的评分器，拒绝不符合标准的记录）
- 记录是 Zod `discriminatedUnion`，按 `task_type` 键控 - `numeric`、`exact_answer`、`set_answer`、`mcq`、`regex_answer`、`json_answer`、`free_response`
- 带有每个记录序列化的类型化评分器 DSL - 确定性种类（`numeric` 通过 math.js、`exact_match`、`set_match`、`regex`、`mcq`、`json_match`）在服务器端运行；`llm_rubric` 路由到采样
- 提交时的强制提交门槛：金色必须通过其自己的评分器，≥1 个负面案例必须被拒绝，并且记录的、去相关的独立验证必须同意金色
- 可选的舰队接地通过 `captures` EvalsID 字段 - 链接框架编写的工具调用转储，从 `EVALS_CAPTURE_DIR` 解析并与金色交叉检查（无服务器到服务器的调用）
- `EVALS_DATA_DIR` 下的纯 JSON 文件 - 可检查、可区分、可版本控制的记录
- 编译为 JSONL、CSV、Inspect AI 和 lm-evaluation-harness 格式
代理友好输出：
- 两个指令工具（`evals_create_draft`、`evals_revise_draft`）在响应中携带循环的审查机制 - 解析的记录回声、按字段的审查协议和准备好的子代理提示
- 每次草稿和修订的自一致性判决 - 每个积极和每个消极的结果，而不仅仅是一个布尔值
- `evals_list_records` 在达到限制时披露截断，因此永远不会将部分集误认为整个语料库
- 提交门槛拒绝并带有类型 `reason` + 恢复提示，因此被拒绝的记录准确告诉代理需要修复什么
## 入门指南
将以下内容添加到您的 MCP 客户端配置文件中。设置 `EVALS_DATA_DIR` 为可写入的文件夹 - 服务器在其中管理 `drafts/`、`submitted/` 和 `exports/`。
```json
{
"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）：
```json
{
"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：
```json
{
"mcpServers": {
"evals-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"-e", "EVALS_DATA_DIR=/data",
"-v", "evals-data:/data",
"ghcr.io/cyanheads/evals-mcp-server:latest"
]
}
}
}
```
对于 Streamable HTTP，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 EVALS_DATA_DIR=./evals-data bun run start:http
# 服务器监听 http://localhost:3010/mcp
```
### 先决条件
- [Bun v1.3.2](https://bun.sh/) 或更高版本（或 Node.js v24+）。
- 用于 `EVALS_DATA_DIR` 的可写入目录。不需要外部 API 密钥。
### 安装
1. **克隆存储库：**
```sh
git clone https://github.com/cyanheads/evals-mcp-server.git
```
2. **导航到目录：**
```sh
cd evals-mcp-server
```
3. **安装依赖项：**
```sh
bun install
```
4. **配置环境：**
```sh
cp .env.example .env
# 编辑 .env 并设置 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` EvalsID 解析为完整的转储。 | - |
| `MCP_TRANSPORT_TYPE` | 传输：`stdio` 或 `http`。 | `stdio` |
| `MCP_HTTP_PORT` | HTTP 服务器的端口。 | `3010` |
| `MCP_AUTH_MODE` | 身份验证模式：`none`、`jwt` 或 `oauth`。 | `none` |
| `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` |
| `OTEL_ENABLED` | 启用 [OpenTelemetry 仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 | `false` |
参见 [`.env.example`](./.env.example) 以获取完整的可选覆盖列表。
## 运行服务器
### 本地开发
- **构建并运行：
```sh
# 一次性构建
bun run rebuild
# 运行构建的服务器
bun run start:stdio
# 或
bun run start:http
```
- **运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全检查
bun run test # Vitest 测试套件
bun run lint:mcp # 验证 MCP 定义对抗规范
```
### Docker
```sh
docker build -t evals-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio -e EVALS_DATA_DIR=/data -v evals-data:/data evals-mcp-server
```
Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志记录到 `/var/log/evals-mcp-server`。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`](./CLAUDE.md) 开发指南和架构规则。简版：
- 处理程序抛出，框架捕获 - 工具逻辑中没有 `try/catch`
- 使用 `ctx.log` 请求范围内的日志记录；记录通过 `record-store` 服务持久化，而不是 `ctx.state`
- 在 `src/index.ts` 中注册新工具和资源
- 服务器是真相的源头 - 验证输入，运行评分器作为硬门槛，并且永远不要仅凭断言承认记录
## 贡献
问题和拉取请求是欢迎的。运行检查和测试后再提交：
```sh
bun run devcheck
bun run test
```
