Skip to content

README_mcp_zh-CN.md

Latest commit

 

History

History
300 lines (233 loc) · 10.3 KB

README_mcp_zh-CN.md

File metadata and controls

300 lines (233 loc) · 10.3 KB

Dingo MCP 服务端

概述

Dingo 内置了模型上下文协议 (MCP) 服务端，由 FastMCP 驱动。这允许 MCP 客户端（例如 Cursor）以编程方式与 Dingo 的数据评估功能进行交互。

特性

  • 通过 MCP 调用 Dingo 的评估逻辑。
  • 提供以下工具：
    • run_dingo_evaluation: 对指定数据执行基于规则或基于 LLM 的评估。
    • list_dingo_components: 列出 Dingo 中可用的规则组和已注册的 LLM 模型。
    • get_rule_details: 获取特定规则的详细信息。
    • get_llm_details: 获取特定 LLM 的详细信息。
    • get_prompt_details: 获取特定提示的详细信息。
    • run_quick_evaluation: 基于高级目标运行简化评估。
  • 支持通过 MCP 客户端（如 Cursor）进行交互。

安装

pip install dingo-python

安装后即可使用 dingo CLI 命令，内含 MCP 服务端。无需克隆仓库。

如需开发或直接修改 mcp_server.py：

git clone https://github.com/MigoXLab/dingo.git
cd dingo
pip install -e .

运行服务端

使用 CLI（推荐）

# SSE 传输（默认），监听 8000 端口
dingo serve

# 自定义主机和端口
dingo serve --host 127.0.0.1 --port 9000

# stdio 传输（适用于 Claude Desktop 或本地 agent 启动）
dingo serve --transport stdio

直接运行 mcp_server.py（兼容旧方式）

如果已克隆仓库，也可以直接运行：

python mcp_server.py

传输模式

模式 使用场景 启动方式
SSE（默认） 网络服务、Cursor 集成 dingo serve 或 dingo serve --port 9000
stdio Claude Desktop、本地 agent 启动 dingo serve --transport stdio

与 Cursor 集成

配置

要将 Cursor 连接到你正在运行的 Dingo MCP 服务端，你需要编辑 Cursor 的 MCP 配置文件 (mcp.json)。该文件通常位于 Cursor 的用户配置目录中（例如 ~/.cursor/ 或 %USERPROFILE%\.cursor\）。

在 mcpServers 对象中添加或修改你的 Dingo 服务端条目。

示例1：SSE 模式（先运行 dingo serve，再配置）：

{
  "mcpServers": {
    "dingo": {
      "url": "http://localhost:8000/sse"
    }
  }
}

示例2：stdio 模式（Cursor 自动启动进程）：

{
  "mcpServers": {
    "dingo": {
      "command": "dingo",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "OPENAI_MODEL": "gpt-4"
      }
    }
  }
}
  • SSE 模式：需先启动 dingo serve，url 必须与主机和端口匹配。默认为 http://localhost:8000/sse。
  • stdio 模式：Cursor 会自动启动 dingo serve --transport stdio 进程，无需手动启动服务端。
  • 保存对 mcp.json 的更改后，重启 Cursor。

在 Cursor 中使用

配置完成后，你可以在 Cursor 中调用 Dingo 工具：

  • 列出组件: "使用 dingo_evaluator 工具列出可用的 Dingo 组件。"
  • 运行评估: "使用 dingo_evaluator 工具运行规则评估..." 或 "使用 dingo_evaluator 工具运行 LLM 评估..."
  • 获取详情: "使用 dingo_evaluator 工具获取特定规则/LLM/提示的详细信息..."
  • 快速评估: "使用 dingo_evaluator 工具快速评估文件的..."

Cursor 将提示你输入必要的参数。

工具参考

list_dingo_components()

列出可用的 Dingo 规则组、已注册的 LLM 模型标识符和提示定义。

  • 参数:
    • component_type (Literal["rule_groups", "llm_models", "prompts", "all"]): 要列出的组件类型。默认值: "all"。
    • include_details (bool): 是否包括每个组件的详细描述和元数据。默认值: false。
  • 返回: Dict[str, List[str]] - 包含 rule_groups、llm_models、prompts 和/或 llm_prompt_mappings 的字典（取决于 component_type）。

Cursor 使用示例:

使用 dingo_evaluator 工具列出 dingo 组件。

get_rule_details()

获取特定 Dingo 规则的详细信息。

  • 参数:
    • rule_name (str): 要获取详细信息的规则名称。
  • 返回: 包含规则详细信息的字典，包括其描述、参数和评估特征。

Cursor 使用示例:

使用 Dingo Evaluator 工具获取"default"规则组的详细信息。

(Cursor 应提出如下工具调用)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>get_rule_details</tool_name>
<arguments>
{
  "rule_name": "default"
}
</arguments>
</use_mcp_tool>

get_llm_details()

获取特定 Dingo LLM 的详细信息。

  • 参数:
    • llm_name (str): 要获取详细信息的 LLM 名称。
  • 返回: 包含 LLM 详细信息的字典，包括其描述、功能和配置参数。

Cursor 使用示例:

使用 Dingo Evaluator 工具获取"LLMTextQualityModelBase" LLM 的详细信息。

(Cursor 应提出如下工具调用)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>get_llm_details</tool_name>
<arguments>
{
  "llm_name": "LLMTextQualityModelBase"
}
</arguments>
</use_mcp_tool>

get_prompt_details()

获取特定 Dingo 提示的详细信息。

  • 参数:
    • prompt_name (str): 要获取详细信息的提示名称。
  • 返回: 包含提示详细信息的字典，包括其描述、关联的指标类型以及所属的组。

Cursor 使用示例:

使用 Dingo Evaluator 工具获取"PromptTextQuality"提示的详细信息。

(Cursor 应提出如下工具调用)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>get_prompt_details</tool_name>
<arguments>
{
  "prompt_name": "PromptTextQuality"
}
</arguments>
</use_mcp_tool>

run_quick_evaluation()

基于高级目标运行简化的 Dingo 评估。

  • 参数:
    • input_path (str): 要评估的文件路径。
    • evaluation_goal (str): 描述要评估的内容（例如，"检查不当内容"、"评估文本质量"、"评估帮助性"）。
  • 返回: 评估结果的摘要或详细结果的路径。

Cursor 使用示例:

使用 Dingo Evaluator 工具快速评估文件"test/data/test_local_jsonl.jsonl"中的文本质量。

(Cursor 应提出如下工具调用)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>run_quick_evaluation</tool_name>
<arguments>
{
  "input_path": "test/data/test_local_jsonl.jsonl",
  "evaluation_goal": "评估文本质量并检查任何问题"
}
</arguments>
</use_mcp_tool>

run_dingo_evaluation(...)

运行 Dingo 评估（基于规则或基于 LLM）。

  • 参数:
    • input_path (str): 输入文件或目录的路径。支持：
      • 相对路径（推荐）：相对于当前工作目录（CWD）解析，例如：test_data.jsonl
      • 绝对路径：如果文件存在，直接使用
      • 项目相对路径（兼容旧版）：如果在 CWD 中未找到，则回退到项目根目录
    • evaluation_type (Literal["rule", "llm"]): 评估类型。
    • eval_group_name (str): 用于 rule 类型的规则组名称（默认：""，表示使用 'default'）。有效的规则组从 Dingo 的 Model 注册表动态加载。使用 list_dingo_components(component_type="rule_groups") 查看可用的规则组。对于 llm 类型则忽略此参数。
    • output_dir (Optional[str]): 保存输出的目录。默认为 input_path 父目录下的 dingo_output_* 子目录。
    • task_name (Optional[str]): 任务名称（用于生成输出路径）。默认为 mcp_eval_<uuid>。
    • save_data (bool): 是否保存详细的 JSONL 输出（默认：True）。
    • save_correct (bool): 是否保存正确的数据（默认：True）。
    • kwargs (dict): 用于附加 dingo.io.InputArgs 的字典。常见用途：
      • dataset (str): 数据集类型（例如 'local', 'hugging_face'）。如果提供了 input_path，则默认为 'local'。
      • data_format (str): 输入数据格式（例如 'json', 'jsonl', 'plaintext'）。如果可能，会从 input_path 扩展名推断。
      • column_content (str): 对于 JSON/JSONL 等格式必需 - 指定包含要评估文本的键。
      • column_id, column_prompt, column_image: 其他列映射。
      • custom_config (str | dict): JSON 配置文件路径、JSON 字符串或用于 LLM 评估或自定义规则设置的字典。LLM 的 API 密钥必须在此处提供。
      • max_workers, batch_size: Dingo 执行参数（在 MCP 中默认为 1 以确保稳定性）。
  • 返回: str - 主输出文件的绝对路径（例如 summary.json）。

Cursor 使用示例 (基于规则):

使用 Dingo Evaluator 工具对 test/data/test_local_jsonl.jsonl 运行默认规则评估。确保使用 'content' 列。

(Cursor 应提出如下工具调用)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>run_dingo_evaluation</tool_name>
<arguments>
{
  "input_path": "test/data/test_local_jsonl.jsonl",
  "evaluation_type": "rule",
  "eval_group_name": "default",
  "kwargs": {
    "column_content": "content"
    // data_format="jsonl" 和 dataset="local" 将被推断
  }
}
</arguments>
</use_mcp_tool>

Cursor 使用示例 (基于 LLM):

使用 Dingo Evaluator 工具对 test/data/test_local_jsonl.jsonl 执行 LLM 评估。使用 'content' 列。使用文件 examples/mcp/config_self_deployed_llm.json 进行配置。

(Cursor 应提出如下工具调用。注意，当为 LLM 评估使用 custom_config 时，可以省略或设置 eval_group_name)

<use_mcp_tool>
<server_name>dingo_evaluator</server_name>
<tool_name>run_dingo_evaluation</tool_name>
<arguments>
{
  "input_path": "test/data/test_local_jsonl.jsonl",
  "evaluation_type": "llm",
  "kwargs": {
    "column_content": "content",
    "custom_config": "examples/mcp/config_self_deployed_llm.json"
    // data_format="jsonl" 和 dataset="local" 将被推断
  }
}
</arguments>
</use_mcp_tool>

请参阅 examples/mcp/config_api_llm.json（用于基于 API 的 LLM）和 examples/mcp/config_self_deployed_llm.json（用于自托管 LLM）了解 custom_config 文件的结构，包括放置 API 密钥或 URL 的位置。