# Eval Manager MCP 接入

端点：/mcp
传输：Streamable HTTP（不是旧式 SSE）。相对端点须相对于本文档的 origin 解析。

机器可读目录：[manifest.json](/mcp/manifest.json)，包含真实工具说明、JSON Schema、读写标记和契约摘要。

## 安装步骤

1. 读取 manifest.json，解析 endpoint；检查客户端支持 Streamable HTTP。
2. 向管理员取得 MCP 访问令牌，在客户端安全配置 Authorization: Bearer <token>；令牌不得写入网页、分享链接或提交到仓库。
3. 合并名为 eval_manager 的服务配置，保留其他 MCP 服务；使用客户端的安装接口或配置文件。
4. 重新加载客户端，依次执行 initialize、tools/list、eval_get_capabilities、eval_list_runs({"limit":1})。仅目录可读不代表后端可用；eval_get_capabilities 必须成功。
5. 重跑或合并先 plan，提交使用同一参数和 fingerprint；写操作遵循既有用户授权并传入工具要求的确认字段。

## 客户端配置

Codex：

```sh
codex mcp add eval_manager --url '<ABSOLUTE_MCP_URL>' --bearer-token-env-var EVAL_MANAGER_MCP_TOKEN
```

将 <ABSOLUTE_MCP_URL> 替换为上述端点的绝对地址。令牌环境变量须在客户端启动环境中可用。

其他客户端按其配置格式添加远程 HTTP 服务和可选 Authorization 请求头。前端 [MCP 接入](/mcp-access) 提供 Codex、Claude Code、Cursor 和 VS Code 配置及下载。

## 能力边界

- 需要支持 Streamable HTTP 的 MCP 客户端；Bearer 模式要求客户端能够设置 Authorization 请求头。当前未实现 OAuth。
- 安装由 agent 所在客户端完成，可能需要重启或重新加载工具；网页不能替任意客户端取得安装权限。
- 支持模型端点增删与探测、可运行 bench、全新 STATIC/AGENTIC 评测、状态/结果、持久化最终报告。
- Agentic continuation、RAG 新建与报告删除暂未开放；不代理全部 Backend API。

## 自动化评测流程

先调用 eval_get_submission_guide。端点查询/探测 → 选择执行环境和可运行 bench → eval_plan_run → eval_submit_run → 轮询 eval_get_run → eval_get_result_summary → eval_generate_report。

## 工具（35）

- **eval_list_runs**（只读）：紧凑列出评测任务组，适合先定位 groupId，避免读取完整 GUI 页面。
- **eval_get_capabilities**（只读）：显示 MCP 构建时绑定的 Backend OpenAPI 版本、覆盖率、状态和 Effort 档位。
- **eval_list_model_endpoints**（只读）：列出已保存的模型端点及公开配置；Backend 永不返回 API Key。
- **eval_test_model_endpoint**（写入/执行）：在所选 Control 的评测 namespace 临时 Pod 中探测已保存端点的模型列表和流式生成；返回探测位置与失败阶段，不回显凭据。
- **eval_probe_model_endpoint**（写入/执行）：在所选 Control 的评测 namespace 临时 Pod 中探测已保存端点的模型列表和流式生成；返回探测位置与失败阶段，不回显凭据。
- **eval_get_run**（只读）：读取任务组及每个 task 的冻结执行参数，用于检查 thinking、截断、温度、并发和进度。
- **eval_get_result_summary**（只读）：只读取任务组内各 benchmark 的聚合结果，不加载 case 明细。
- **eval_plan_single_rerun**（只读）：只规划、不提交：从已有任务组精确复制一个 task/benchmark，并应用参数覆盖。绝不会复制整个 benchmark 集合。
- **eval_submit_single_rerun**（写入/执行）：提交单个 STATIC task/benchmark 重跑；需要先规划得到 fingerprint。提交后自动回读冻结参数并核验显式覆盖。
- **eval_list_cases**（只读）：分页读取单个 task 的 case 索引；只返回 ID、状态、分数和定位字段，不返回输入输出或 raw。
- **eval_get_case**（只读）：读取一个 case 的小型索引信息，不返回可能很大的 input/output/raw；随后用 eval_get_case_detail 按区块取明细。
- **eval_get_case_detail**（只读）：按 section 和可选 JSON Pointer 读取单个 case 明细，并按字符分页；适合模型输出、judge 结果、轨迹和 raw artifact。
- **eval_get_task_debug**（只读）：读取 task 调试索引：状态、错误消息、job、结果 URI、checkpoint 和 metadata 键；不返回完整日志。
- **eval_get_task_log**（只读）：按字符范围分页读取 task 执行日志；返回 nextOffset，不会一次传回整份日志。
- **eval_get_task_metadata**（只读）：按 JSON Pointer 获取 resultMetadata 的一个子树，并按字符分页；可用于轨迹引用、artifact 与运行指标。
- **eval_compare_runs**（只读）：对比两个任务组的模型、冻结参数、状态与得分，快速判断是否为参数或环境漂移。
- **eval_plan_result_merge**（只读）：只规划、不提交：校验 2–20 个终态任务集能否物化为一个自带 OSS 结果的只读汇总。
- **eval_plan_platform_error_retry**（只读）：只规划、不提交：由 Backend 识别已结束 STATIC 任务中的平台错误 Case，并强制首次补偿运行 retries=0。
- **eval_submit_result_merge**（写入/执行）：提交只读结果归并；必须带规划指纹和幂等 UUID。任务异步执行，不修改来源任务或来源 OSS。
- **eval_get_result_merge**（只读）：查询后台结果归并状态；完成时返回只读汇总任务集 ID。
- **eval_submit_platform_error_retry**（写入/执行）：提交 Backend 识别的平台错误 Case 补偿任务；重新获取草稿并核对 fingerprint，避免 Case 集合变化。
- **eval_pause_run**（写入/执行）：暂停支持 checkpoint 的运行中任务组；必须同时提供当前任务名并显式确认。
- **eval_resume_run**（写入/执行）：从已提交 checkpoint 恢复暂停任务组；必须同时提供当前任务名并显式确认。
- **eval_cancel_run**（写入/执行）：取消任务组。为避免误操作，必须同时提供 groupId、当前任务名和 confirm=true。
- **eval_get_submission_guide**（只读）：新评测完整调用顺序、STATIC/AGENTIC 详细运行参数和报告前置条件。
- **eval_list_execution_environments**（只读）：列出执行环境、支持类型、容量与部分故障；先选 controlId。
- **eval_list_runnable_benches**（只读）：列出可运行 image / bench / dataset；同时返回 unavailableImages 的阻塞原因、缺失预热节点和修复建议。空列表不代表没有资产；诊断只读，不自动修复。返回 assetReleaseId 用于冻结提交。
- **eval_list_runnable_model_endpoints**（写入/执行）：在指定执行环境的临时 Pod 对选定端点检查模型列表和小型流式生成，返回通过探测的端点与失败/降级项。探针通过不保证评测调用成功。
- **eval_save_model_endpoint**（写入/执行）：按 endpoint + model_name 新增或更新模型端点。api_key 仅传给 Backend，输出不回显。确认后执行，可设置推理默认值、token与并发限制。
- **eval_delete_model_endpoint**（写入/执行）：按 ID 删除模型端点；必须提供当前端点名称和 confirm=true。
- **eval_plan_run**（只读）：规划全新 STATIC/AGENTIC 评测，解析模型和 bench 名称并冻结计划指纹；不创建任务。
- **eval_submit_run**（写入/执行）：提交全新评测的详细参数；先 plan，使用相同参数、expectedFingerprint、confirm=true。成功返回 groupId 并回读冻结结果。
- **eval_generate_report**（写入/执行）：生成并保存最终模型×bench评测报告，包含分数、样本数、输出token与执行参数快照。仅接受已完成且结果导入完成的 bench；不将进行中结果当最终报告。
- **eval_list_reports**（只读）：列出已保存的最终评测报告摘要。
- **eval_get_report**（只读）：读取报告的模型×bench指标、样本数与冻结参数。