judge-mcp

English: README.en.md

LLM-as-Judge テキスト品質評価を MCP サーバーとして提供。

原文・修正文のペアを多軸加重ルーブリックで採点し、人間ラベル付きゴールデンセットで採点モデルを試験し（「学習ではなく試験」）、2つの採点器の一致率を交差検証します。すべて MCP ツールとして公開されているため、Claude Desktop・Claude Code などあらゆる MCP クライアントで対話形式の評価を実行できます。

作った理由

校正・リライティング・要約には単一の正解がないため、LLM 採点器を採用するチームが増えています。しかし、検証されていない採点器は単なる一意見にすぎません。このサーバーは、実サービスログ分析プロジェクトで検証した方法論をツールとして一般化したものです。

1. 多軸加重ルーブリック — 意味保持・自然さ・改善度・過剰修正の抑制。不透明な単一スコアではなく、軸ごとに評価します。

2. ゴールデンセット試験 — 採点器の候補を人間ラベル（適切な修正/見逃し/過剰修正）で試験します。学習には決して使用しないため、ゴールデンセットは試験問題として維持され、ルーブリックが変更されるたびに回帰試験として再利用されます。

3. 二重採点の交差検証 — 同じ問題を2つの採点器で採点して一致率を測定し、結論が採点器の選択に対して頑健であるかを実証します。

4. 決定的プリフィルタ — 無変更ペアは LLM なしでコードが採点します。低コストで、常に同じ回答です。

Related MCP server: mcp-eval-harness

ツール

韓国語校正の合成ゴールデンセット24問（3バケット）が内蔵されており、golden_path で独自のゴールデンセット（JSONL: id、original、revised、label）を使用できます。

インストール・設定

OpenAI 互換バックエンドであればすべて動作します — OpenAI、ローカル vLLM、Ollama、LM Studio。

pip install -e .

export JUDGE_API_BASE="https://api.openai.com/v1"   # vLLM이면 http://localhost:8000/v1
export JUDGE_API_KEY="sk-..."                        # 로컬 서버는 아무 값
export JUDGE_MODEL="gpt-4o-mini"                     # 또는 Qwen/Qwen2.5-7B-Instruct-AWQ

Claude Desktop 設定例は examples/ にあります。設定後は次のように質問できます。

• 「この校正を採点して：原文『오늘 회의 몇시에 시작하나요』、修正『몇 시에 시작하나요?』」

• 「gpt-4o-mini でゴールデンセットを実行して成績表を見せて」

• 「gpt-4o-mini とローカル Qwen が採点器として互いに一致するか比較して」

実測結果

内蔵ゴールデンセット24問を Claude Sonnet（claude-cli バックエンド）で試験した結果：

直接再現：python scripts/run_golden.py --backend claude-cli（OpenAI 互換 API は --backend api）。

ケーススタディ：ゴールデンセットが設計欠陥を発見

最初の実行は 62.5% — 見逃しバケットが 0/8 でした。原因は採点器ではなく判定設計にありました。見逃した修正は意味を保持し過剰修正もないため、重みの大きい2軸（0.40+0.35）が満点になり、改善軸が1点でも総合が8〜9点になります。総合スコアで見逃しを検出することは数学的に不可能でした。

修正：見逃しバケットの判定を総合スコアではなく改善（improvement）軸 ≤ 4 に変更。再試験の結果 62.5% → 83.3%、見逃し 0/8 → 7/8。ゴールデンセット回帰ループが存在する理由はまさにこれです — 静かに潜んでいた評価設計の欠陥を実測で明らかにし、修正し、回帰テストで固定しました。（残るギャップ：過剰修正バケットでは LLM 採点の実行間変動が観察されました — Few-shot アンカー強化の候補であり、同じ回帰ループで改善を検証できます。）

設計ノート

• 採点器の検証が核心です。 採点器モデルはデフォルト状態では傾向が正反対であり、試験なしで選ぶのは推測にすぎません。精度は方向で判定します — 適切に修正されたものは高く（≥7）、見逃し・過剰修正は低く（≤5）。グレーゾーン（5〜7）は意図的に誤答として扱います。

• 再現性優先。 temperature 0、JSON 強制出力＋コードフェンス・雑談耐性パーシング、スコア範囲クランプ、そしてモデルが不要なケース（無変更）はコードパスで処理。

• 実行可能なエラー。 接続・スキーマ失敗はスタックトレースではなく「何を修正すればよいか」を含むメッセージで返します。

テスト

pip install -e ".[dev]"
pytest   # 21건, 네트워크 불필요 (모의 LLM)

ライセンス

MIT