# Dingo MCP 服务端

## 概述

Dingo 内置了模型上下文协议 (MCP) 服务端，由 [FastMCP](https://github.com/modelcontextprotocol/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）进行交互。

## 安装

```bash
pip install dingo-python
```

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

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

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

## 运行服务端

### 使用 CLI（推荐）

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

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

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

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

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

```bash
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`，再配置）：

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

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

```json
{
  "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 应提出如下工具调用)*
```xml
<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 应提出如下工具调用)*
```xml
<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 应提出如下工具调用)*
```xml
<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 应提出如下工具调用)*
```xml
<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 应提出如下工具调用)*
```xml
<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`)*
```xml
<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 的位置。