使用说明

项目简介

Dataset Viewer MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 LLM 客户端提供访问和操作 Hugging Face Hub 数据集的能力。通过该服务器，LLM 可以方便地获取数据集的元信息、浏览数据内容、执行数据分析和搜索等操作，从而更好地利用 Hugging Face Hub 上丰富的 NLP 数据资源。

主要功能点

数据集资源访问: 使用 'dataset://' URI 方案访问 Hugging Face 数据集，支持数据集配置和切分 (split)。
数据集信息查询: 获取数据集的详细信息，包括描述、特征、配置、切分等。
数据内容浏览: 分页浏览数据集内容，支持指定配置和切分。
数据集统计分析: 获取数据集切分的统计信息。
数据集搜索: 在数据集内容中执行文本搜索。
数据过滤: 使用 SQL-like 的 WHERE 条件过滤数据集行。
Parquet 导出: 将整个数据集导出为 Parquet 格式文件。
访问控制: 支持通过 Hugging Face API token 访问私有数据集。

安装步骤

克隆仓库:

git clone https://github.com/privetin/dataset-viewer.git
cd dataset-viewer

创建并激活虚拟环境:

# 创建虚拟环境
uv venv

# 激活虚拟环境
# On Unix:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

安装项目依赖:
```
uv add -e .
```

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能连接 Dataset Viewer MCP Server。以下是 Claude Desktop 客户端的配置示例，其他 MCP 客户端的配置方式类似。

在 Claude Desktop 的配置文件 ('claude_desktop_config.json') 中添加 'mcpServers' 配置：

{
  "mcpServers": {
    "dataset-viewer": {
      "command": "uv",
      "args": [
        "run",
        "dataset-viewer"
      ]
    }
  }
}

'server name': 'dataset-viewer' (服务器名称，客户端用于识别和调用)
'command': 'uv' (启动服务器的命令，这里使用 'uv run' 来运行 Python 脚本)
'args':
- '"run"': 'uv run' 的子命令，用于运行指定的 Python 模块或脚本。
- '"dataset-viewer"': 要运行的 Python 模块名，对应项目中的 'src/dataset_viewer/init.py' 文件，该文件定义了服务器的入口 'main()' 函数。

环境变量配置

Dataset Viewer MCP Server 允许通过环境变量 'HUGGINGFACE_TOKEN' 配置 Hugging Face API Token，用于访问私有数据集。您可以在启动服务器前设置该环境变量，或者在调用工具时通过参数 'auth_token' 显式指定。

基本使用方法

Dataset Viewer MCP Server 通过 JSON-RPC 协议与客户端通信。客户端发送 JSON-RPC 请求调用服务器提供的工具 (Tools) 和资源 (Resources)。

资源 (Resources)

使用 'dataset://{dataset_id}' 格式的 URI 访问数据集资源，例如 'dataset://stanfordnlp/imdb'。
可以通过 MCP 客户端的资源列表功能查看可用的数据集资源。
可以通过 MCP 客户端的读取资源功能获取数据集的元信息。

工具 (Tools)

Dataset Viewer MCP Server 提供了以下工具，客户端可以调用这些工具来操作数据集：

validate: 验证数据集是否存在和可访问。

{
  "tool_name": "validate",
  "arguments": {
    "dataset": "stanfordnlp/imdb"
  }
}

get_info: 获取数据集详细信息。

{
  "tool_name": "get_info",
  "arguments": {
    "dataset": "stanfordnlp/imdb"
  }
}

get_rows: 获取数据集数据行 (分页)。

{
  "tool_name": "get_rows",
  "arguments": {
    "dataset": "stanfordnlp/imdb",
    "config": "plain_text",
    "split": "train",
    "page": 0
  }
}

get_first_rows: 获取数据集前几行数据。

{
  "tool_name": "get_first_rows",
  "arguments": {
    "dataset": "stanfordnlp/imdb",
    "config": "plain_text",
    "split": "train"
  }
}

get_statistics: 获取数据集统计信息。

{
  "tool_name": "get_statistics",
  "arguments": {
    "dataset": "stanfordnlp/imdb",
    "config": "plain_text",
    "split": "train"
  }
}

search_dataset: 搜索数据集内容。

{
  "tool_name": "search_dataset",
  "arguments": {
    "dataset": "stanfordnlp/imdb",
    "config": "plain_text",
    "split": "train",
    "query": "great movie"
  }
}

filter: 过滤数据集数据行。

{
  "tool_name": "filter",
  "arguments": {
    "dataset": "stanfordnlp/imdb",
    "config": "plain_text",
    "split": "train",
    "where": "label = 'positive'",
    "orderby": "text DESC",
    "page": 0
  }
}

get_parquet: 导出数据集为 Parquet 文件。

{
  "tool_name": "get_parquet",
  "arguments": {
    "dataset": "stanfordnlp/imdb"
  }
}

客户端需要根据 MCP 协议规范构造 JSON-RPC 请求，并发送到 Dataset Viewer MCP Server。服务器会处理请求并返回 JSON-RPC 响应。

关键词