Skip to main content
Glama

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

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 进程始终活着

安装与挂载

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

Claude Desktopclaude_desktop_config.json)/ Cursormcp.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 tools
compare_runsB

对比两次运行结果(竞品对比 / 版本回归)。输入是 run_eval 的 json_out 产物

ParametersJSON Schema
NameRequiredDescriptionDefault
run_aYes
run_bYes
labelsNo
html_outNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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(自动判定留空,避免锚定效应)

ParametersJSON Schema
NameRequiredDescriptionDefault
out_csvYes
result_jsonYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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 即众包(多数投票 + 一致率)

ParametersJSON Schema
NameRequiredDescriptionDefault
html_outNo
out_jsonNo
result_jsonYes
review_csvsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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 离线跑

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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 环境变量

ParametersJSON Schema
NameRequiredDescriptionDefault
mockNo
tagsNo
eval_setYes
html_outNo
json_outNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

  1. 5 tool updatesv0.1.0
    • First observedcompare_runs
    • First observedexport_review
    • First observedimport_review
    • First observedlist_eval_sets
    • First observedrun_eval

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation5/5

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).

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers