golden-dataset-mcp

mcp-name: io.github.nipunkhanderia/golden-dataset-mcp

golden-dataset-mcp

一个封装了 golden-dataset-studio 的 MCP 服务，用于对 RAG/LLM 流水线进行版本控制的黄金数据集管理和语义评估。

这是现有 golden_dataset 库（DatasetStore、Evaluator）之上的轻量协议层。它不会重新实现任何逻辑，而是将该库现有的 Python API 作为 MCP 工具提供，以便 Agent（Claude Desktop、Claude Code 或任何 MCP 客户端）通过对话管理黄金数据集。

无需 LLM API 密钥。 评估使用 TF-IDF 余弦相似度（scikit-learn），而非调用 LLM。

为什么要将它作为独立软件包，而不是合并到 golden-dataset-studio？

golden-dataset-studio 是一个 CLI 工具，专为在终端中输入 golden add、golden commit 等命令的人设计。golden-dataset-mcp 将相同的底层操作作为 MCP 工具提供，让 LLM Agent 能够以编程方式调用这些操作，例如将其用于自动化 RAG 评估流水线。将它们作为独立的 PyPI 软件包，可以避免 CLI 用户被迫将 fastmcp 作为依赖项安装，同时也让 MCP 用户获得简洁、专注于协议的软件包。

工具

工具	功能
init_dataset	在指定路径初始化新数据集
add_entry	向工作树添加问答对
update_entry	编辑工作树中现有条目的字段
delete_entry	从工作树中移除条目
list_entries	列出工作树或已提交版本中的条目
commit_version	将工作树快照保存为新的不可变版本
diff_versions	显示两个版本之间新增、移除或更改的条目
evaluate_answers	使用 TF-IDF 余弦相似度，根据某个版本对实际答案进行评分
dataset_status	显示当前版本、工作树大小和版本历史

设计：每个工具都需要显式的 dataset_path

与操作当前工作目录的 CLI 不同，这里的每个工具都需要显式的 dataset_path 参数。这样可以确保服务在调用之间完全无状态，不会因隐藏的“当前数据集”会话状态而导致跟踪困难，也能安全地让一个服务实例管理多个数据集或同时为多个客户端提供服务。

安装

pip install golden-dataset-mcp

这会自动将 golden-dataset-studio 和 scikit-learn 作为依赖项安装。

在 Claude Desktop / Claude Code 中使用

{
  "mcpServers": {
    "golden-dataset": {
      "command": "golden-dataset-mcp"
    }
  }
}

无需设置环境变量，也无需 API 密钥或配置。

示例流程

1. init_dataset(dataset_path="./my-rag-eval", name="support-bot-eval")
2. add_entry(dataset_path="./my-rag-eval", question="...", answer="...")
   [repeat for each golden Q&A pair]
3. commit_version(dataset_path="./my-rag-eval", description="initial 50 questions")
4. [run your RAG pipeline, collect actual answers]
5. evaluate_answers(dataset_path="./my-rag-eval", actual_answers=[...])
   -> avg_semantic_similarity, per-entry scores, pass/fail

随着 RAG 流水线不断变化，在编辑后再次运行 commit_version，并使用 diff_versions 准确查看不同版本之间黄金数据集的变化。

与底层库的关系

	golden-dataset-studio	golden-dataset-mcp
接口	CLI（golden ...）	MCP 工具
调用方	输入命令的人	LLM Agent / MCP 客户端
路径处理	当前工作目录	每次调用显式指定 dataset_path
依赖方向	—	依赖 golden-dataset-studio

如果你需要由人操作的 CLI，请直接使用 golden-dataset-studio。如果你希望由 Agent 来调用它，请使用此软件包。

开发

git clone https://github.com/nipunkhanderia/golden-dataset-mcp
cd golden-dataset-mcp
pip install -e ".[dev]"
pytest -v

验证 MCP 接口契约：

npx @modelcontextprotocol/inspector golden-dataset-mcp

局限

• evaluate_answers 使用 TF-IDF 余弦相似度，与深层语义相比，它更擅长捕捉词汇重合。若要使用基于嵌入或 RAGAS 风格的指标，请直接调用底层库的 Evaluator.ragas_evaluate()（需要运行 pip install "golden-dataset-studio[ragas]" 安装；此版本未将其公开为 MCP 工具）。
• 答案过短或仅由停用词组成时会报错。 scikit-learn 的 TF-IDF 向量化器会对 "4" 或 "the a an" 这类输入抛出 ValueError: empty vocabulary。避免使用只有一个词元的黄金答案，否则 evaluate_answers 可能会失败。
• 所有状态均以 JSON/JSONL 文件形式存储在 <dataset_path>/.golden_dataset/ 下；此服务不会进行远程存储或同步。

许可证

MIT