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 ツールとして公開することで、エージェント（Claude Desktop、Claude Code、または任意の MCP クライアント）が会話形式でゴールデンデータセットを管理できるようにします。

LLM API キーは不要です。 評価には LLM の呼び出しではなく、TF-IDF コサイン類似度（scikit-learn）を使用します。

golden-dataset-studio とは別のパッケージにする理由

golden-dataset-studio は CLI ツールです。ターミナルで golden add、golden commit などを入力する人間向けに設計されています。golden-dataset-mcp は、同じ基盤操作を MCP ツールとして公開し、LLM エージェントがプログラムから実行できるようにします。たとえば、自動化された RAG 評価パイプラインの一部として利用できます。別々の PyPI パッケージにすることで、CLI の利用者が依存関係として fastmcp を追加する必要がなくなり、MCP の利用者にはプロトコルに特化したシンプルなパッケージを提供できます。

ツール

ツール	機能
init_dataset	指定したパスに新しいデータセットを初期化します
add_entry	作業ツリーに質問と回答のペアを追加します
update_entry	作業ツリー内の既存エントリーのフィールドを編集します
delete_entry	作業ツリーからエントリーを削除します
list_entries	作業ツリーまたはコミット済みバージョンのエントリーを一覧表示します
commit_version	作業ツリーを新しい不変バージョンとしてスナップショットします
diff_versions	2 つのバージョン間で追加・削除・変更されたエントリーを表示します
evaluate_answers	TF-IDF コサイン類似度を用いて、実際の回答をあるバージョンと照合してスコアを付けます
dataset_status	現在のバージョン、作業ツリーのサイズ、バージョン履歴を表示します

設計：すべてのツールで dataset_path を明示的に指定

現在の作業ディレクトリで動作する CLI とは異なり、ここではすべてのツールで dataset_path パラメーターを明示的に指定する必要があります。これにより、サーバーは呼び出し間で完全にステートレスになります。追跡が必要な隠れた「現在のデータセット」セッション状態がなく、1 つのサーバーインスタンスで複数のデータセットを管理したり、複数のクライアントからの同時接続に対応したりする場合も安全です。

インストール

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 エージェント／MCP クライアント
パスの扱い	現在の作業ディレクトリ	呼び出しごとに明示する dataset_path
依存関係の方向	—	golden-dataset-studio に依存

人間が操作する CLI を使いたい場合は、golden-dataset-studio を直接使用してください。エージェントに操作させたい場合は、このパッケージを使用してください。

開発

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 が失敗することを想定してください。
• すべての状態は <dataset_path>/.golden_dataset/ 以下の JSON／JSONL ファイルとしてファイルシステムに保存されます。このサーバーではリモートストレージや同期は行いません。

ライセンス

MIT