dify-eval-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dify-eval-mcp帮我跑一下 erp-copilot 的回归集,和上次的基线比一下"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dify-eval-mcp
把 dify-eval 的评测能力暴露成 MCP Server—— Claude Desktop / Cursor / CodeBuddy 里直接对 AI 说「跑一遍回归评测」,它就会调。
为什么做这个项目
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/...Related MCP server: Eval_MCP
五个工具
工具 | 干什么 | 对应 dify-eval |
| 扫目录发现评测集(名字 / 用例数 / 可否 mock) | — |
| 跑评测集,返回通过率 / 维度统计 / 失败清单 |
|
| 两次运行对比(竞品对比 / 版本回归) |
|
| 导出人工盲评 CSV |
|
| 合并人工评审(多份 = 众包,多数投票 + 一致率) |
|
设计要点:
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 进程始终活着
安装与挂载
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):
{
"mcpServers": {
"dify-eval": {
"command": "dify-eval-mcp",
"env": {
"DIFY_BASE_URL": "https://your-dify.example.com",
"DIFY_API_KEY": "app-xxx"
}
}
}
}不配环境变量也能用——那就是纯 mock 离线模式。
测试
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
Available Tools
5 toolscompare_runsB
对比两次运行结果(竞品对比 / 版本回归)。输入是 run_eval 的 json_out 产物
| Name | Required | Description | Default |
|---|---|---|---|
| run_a | Yes | ||
| run_b | Yes | ||
| labels | No | ||
| html_out | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It notes the input source and general comparison purpose, but it does not explain whether the tool is read-only, whether it writes the html_out file, what side effects exist, or what kind of result is returned. This is a significant transparency gap for a tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core purpose and immediately adds the key input constraint. Every part earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimally viable: an agent can infer that run_a and run_b should come from run_eval json_out outputs and that comparison is the goal. However, optional parameters like labels and html_out remain unexplained, and there is no behavioral detail about the comparison output or side effects, leaving clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only implies that run_a and run_b correspond to run_eval json_out outputs. It adds no meaning for labels or html_out, and does not clarify whether the parameters are file paths, JSON strings, or something else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('compare two run results') and the resource being compared, with two concrete use cases: competitor comparison and version regression. It also ties the tool to run_eval by specifying the input is run_eval's json_out output, which helps distinguish it from sibling tools, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context for when to use the tool: after run_eval produces json_out, and for competitor comparison or version-regression analysis. It does not explicitly state when not to use it or name alternative tools, but the context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_reviewA
从运行结果导出人工盲评 CSV(自动判定留空,避免锚定效应)
| Name | Required | Description | Default |
|---|---|---|---|
| out_csv | Yes | ||
| result_json | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses a meaningful behavioral trait: automatic judgments are intentionally left blank ('自动判定留空') to avoid anchoring effects ('避免锚定效应'). This adds value beyond the schema, though it does not mention file-handling side effects like overwriting or directory creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with the key behavioral notice in parentheses. Every element earns its place, and the core action is stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter export tool with an output schema and no nested objects, the description covers the source, output format, and intentional blank-judgment behavior. It is nearly complete, though explicit parameter semantics and clearer alternative routing would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not explain what result_json and out_csv should contain or whether they are paths, content strings, or file URLs. The description loosely connects '运行结果' to result_json and 'CSV' to out_csv, but this is insufficient given the complete lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('导出', export), a specific resource (人工盲评 CSV, human blind review CSV), and a source (运行结果, run results). It also distinguishes itself from siblings like import_review by making clear it is an export step rather than an import or evaluation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: after run results exist, export a CSV for human blind review. However, it does not explicitly state when to use this tool versus siblings such as import_review, run_eval, or compare_runs, leaving the agent to infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_reviewA
把人工评审 CSV 合并回运行结果;传多份 CSV 即众包(多数投票 + 一致率)
| Name | Required | Description | Default |
|---|---|---|---|
| html_out | No | ||
| out_json | No | ||
| result_json | Yes | ||
| review_csvs | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a meaningful behavioral trait (majority voting and agreement rate when multiple CSVs are passed), which goes beyond a simple merge. Yet it does not mention whether the operation mutates the result file, how conflicts are resolved, or what side effects occur, leaving gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core operation and then adds the critical crowdsourcing nuance. There is zero redundancy, and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so return-value explanation is not needed. However, the description omits param-level details, the required CSV format, merge conflict behavior, and whether the operation is in-place or returns new output. It gives the key idea but leaves an agent uncertain about invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does map review_csvs to the human review CSVs and result_json to the run results, and it explains the multi-CSV aggregation semantics. However, html_out and out_json are entirely unexplained, and the description does not fully compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (merge/合并) and resource (human review CSV into run results), and adds the distinctive crowdsourcing behavior (majority voting + agreement rate). This clearly distinguishes it from siblings like export_review or compare_runs without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when human review CSVs exist and need to be merged back into run results, and that passing multiple CSVs activates crowdsourcing. However, it provides no explicit guidance on when to choose this over siblings, no exclusions, and no mention of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_eval_setsA
扫描目录里的评测集(.yaml/.yml),返回名称、用例数、是否可 mock 离线跑
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does it reasonably well: it indicates a read-only scan, the YAML file filter, and the derived attribute '是否可 mock 离线跑' (whether it can be mock-run offline). It does not cover error behavior or whether subdirectories are scanned recursively, but for a simple listing tool this is a solid disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact Chinese sentence that front-loads the action and then immediately enumerates the returned information: name, case count, and mock-offline capability. There is no filler, no repeated schema trivia, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only listing tool with one parameter and an output schema, so the description does not need to explain return-value structure in depth. It covers what files are scanned and what fields are returned, while the output schema handles detailed return semantics. The lack of explicit guidance about recursive scanning and directory-missing errors prevents a top score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a 'directory' field with no description, and schema_description_coverage is 0%, so the description must compensate. It does so by clarifying that the directory is the folder to scan for YAML eval-set files, which gives the single parameter meaningful role context. It omits path-format details, but the parameter is simple enough that this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the verb '扫描' (scan), names the resource '评测集' (eval sets), and specifies the relevant file pattern '*.yaml/*.yml', followed by the return fields. This clearly differentiates it from siblings like run_eval, compare_runs, export_review, and import_review, which operate on eval sets rather than listing them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a discovery/pre-flight tool by describing scanning and reporting mock-offline capability, but it never explicitly states when to use it instead of siblings such as run_eval or compare_runs. There are no when-not conditions or alternative-referencing cues, so usage guidance is only implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_evalB
跑一批评测用例。mock=True(默认)离线运行,不需要 Dify 实例;live 模式用 DIFY_BASE_URL/DIFY_API_KEY 环境变量
| Name | Required | Description | Default |
|---|---|---|---|
| mock | No | ||
| tags | No | ||
| eval_set | Yes | ||
| html_out | No | ||
| json_out | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It usefully discloses offline/live behavior and environment variable requirements, but it does not mention side effects such as writing HTML/JSON output files or whether the tool persists results elsewhere. This is partial transparency rather than a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence that front-loads the core purpose and then adds essential mode details. There is no filler, repetition of the tool name, or unnecessary background.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, zero schema descriptions, and no annotations, the description is under-specified. It explains the mock/live distinction but does not explain what eval_set should contain, valid tag formats, or where html_out/json_out outputs are written. An output schema may describe return values, but invocation-relevant context is still missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only explains 'mock'; the required 'eval_set' parameter is never defined, and 'tags', 'html_out', and 'json_out' are left entirely to inference from their names. This is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: '跑一批评测用例' (run a batch of evaluation test cases). This is clear enough to distinguish run_eval from sibling tools like list_eval_sets or compare_runs, though it does not explicitly name or contrast those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance on when to use mock mode (offline, no Dify instance) versus live mode (requires DIFY_BASE_URL/DIFY_API_KEY). It does not mention sibling alternatives or exclusions, but the mode-based usage guidance is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
compare_runs - First observed
export_review - First observed
import_review - First observed
list_eval_sets - First observed
run_eval
TDQS
Scored across 5 tools
Each tool has a distinct, non-overlapping purpose: running evaluations, comparing runs, exporting/importing human reviews, and listing evaluation sets. The paired export/import tools are clearly separated by their direction of data flow, and run_eval vs list_eval_sets are unambiguously different (execution vs discovery).
All tool names follow a consistent verb_noun pattern in snake_case: run_eval, compare_runs, export_review, import_review, list_eval_sets. The verbs are all lowercase and descriptive, and the nouns are appropriate. The slight singular/plural variation (eval vs eval_sets, runs) is semantically justified and does not break the pattern.
Five tools is well-scoped for the domain of Dify evaluation workflows. Each tool covers a distinct step in the lifecycle (discover, run, compare, review), without unnecessary overlap or bloat. This is within the ideal 3-15 range and feels purpose-built rather than padded.
The tool surface covers the core evaluation workflow: listing eval sets, running them, comparing results, and handling human reviews. The only noticeable gap is the lack of a way to list or inspect existing run outputs, which an agent would need to know prior runs for comparison. This is a minor dead end that can be worked around if run artifacts are known or passed explicitly.
Maintenance
Related MCP Connectors
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Remote MCP for Gemini upgrade evals, prompt regressions, output diffs, and eval receipts.
Related MCP Servers
AlicenseAqualityAmaintenanceMCP server that gives AI coding agents direct access to evaluation tools.23Apache 2.0- FlicenseNot gradedqualityBmaintenanceAn MCP server for prompt and RAG evaluation workflows, enabling users to register, create API keys, and run evaluations via Claude Desktop, Cursor, or other MCP clients, with a hosted backend for heavy evaluation work.1-

Patronus MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables running LLM evaluations, experiments, and custom evaluators through a standardized MCP interface.16Apache 2.0
AgentMark MCP Serverofficial
AlicenseNot gradedqualityAmaintenanceMCP server for AgentMark. Exposes the full AgentMark API to AI editors: list traces and spans, manage datasets, write scores, run experiments, manage apps, deployments, environments, and annotation queues.352AGPL 3.0