# dify-eval-mcp

把 [dify-eval](https://github.com/ulinchoo-dotcom/dify-eval) 的评测能力暴露成 **MCP Server**——
Claude Desktop / Cursor / CodeBuddy 里直接对 AI 说「跑一遍回归评测」，它就会调。

## 为什么做这个项目

[dify-eval](https://github.com/ulinchoo-dotcom/dify-eval) 解决「AI 应用发布前的质量门禁」，
但它是 CLI：人要在终端里敲命令。而 AI 应用的开发者越来越多时间泡在 MCP 客户端里（Cursor / Claude），
**评测能力应该长在他们的工作流里，而不是另一个终端窗口里**。

一条命令行工具 → MCP Server 的封装，让「跑评测」变成 Agent 的一个工具调用：

```
你：帮我跑一下 erp-copilot 的回归集，和上次的基线比一下
Agent：（调 list_eval_sets 发现评测集 → run_eval 跑 mock → compare_runs 对比）
Agent：12 条用例过了 10 条，mini-003 挂了 groundedness 维度；和基线比没有回归。报告在 reports/...
```

## 五个工具

| 工具 | 干什么 | 对应 dify-eval |
|---|---|---|
| `list_eval_sets` | 扫目录发现评测集（名字 / 用例数 / 可否 mock） | — |
| `run_eval` | 跑评测集，返回通过率 / 维度统计 / 失败清单 | `run` |
| `compare_runs` | 两次运行对比（竞品对比 / 版本回归） | `compare` |
| `export_review` | 导出人工盲评 CSV | `export-review` |
| `import_review` | 合并人工评审（多份 = 众包，多数投票 + 一致率） | `import-review` |

设计要点：

- **mock 优先**：`run_eval` 默认 mock 离线跑，Agent 随便调也不会烧钱；
  live 模式走 `DIFY_BASE_URL` / `DIFY_API_KEY` 环境变量，密钥不进工具参数
- **协议与逻辑分离**：工具实现全在 `tools.py`（不 import 任何 `mcp.*`），
  单测不碰协议；协议层另有一套**真实 stdio JSON-RPC 端到端测试**（起子进程握手、tools/list、tools/call）
- **错误不崩 server**：业务错误以 `{"error": ...}` 返回给调用方，server 进程始终活着

## 安装与挂载

```bash
pip install "dify-eval-mcp @ git+https://github.com/ulinchoo-dotcom/dify-eval-mcp.git@main"
```

**Claude Desktop**（`claude_desktop_config.json`）/ **Cursor**（`mcp.json`）：

```json
{
  "mcpServers": {
    "dify-eval": {
      "command": "dify-eval-mcp",
      "env": {
        "DIFY_BASE_URL": "https://your-dify.example.com",
        "DIFY_API_KEY": "app-xxx"
      }
    }
  }
}
```

不配环境变量也能用——那就是纯 mock 离线模式。

## 测试

```bash
pip install -e ".[dev]"
pytest -q    # 12 个测试：工具层 8 个 + 真实 stdio 协议层 4 个
```

协议层测试会起一个真实的 server 子进程，走完
`initialize → notifications/initialized → tools/list → tools/call` 全流程——
这是「Cursor 能不能真的挂上」的最低保证。

## 三仓库的关系

```
dify-eval        评测引擎（CLI / 判定器 / 报告）        ← 核心
dify-eval-mcp    MCP 封装（本仓库）                    ← 让 Agent 能调
dify-bundle      交付包工具（export/check/diff/import） ← 让配置能带走
```

## License

MIT