judge-mcp

English: README.en.md

将 LLM-as-Judge 文本质量评估做成 MCP 服务器。

对原文·修改文配对进行多轴加权评分，用人标签黄金集来"考试"（而非"训练"）评分模型，并交叉验证两个评分器的一致率。全部通过 MCP 工具暴露，因此可以在 Claude Desktop、Claude Code 等任何 MCP 客户端中通过对话运行评估。

为什么做这个

校对、改写、摘要没有唯一正确答案，因此越来越多团队使用 LLM 评分器。但未经验证的评分器只是又多了一种意见而已。这个服务器是把实际服务日志分析项目中验证过的方法论泛化为工具。

1. 多轴加权评分 — 语义保留、自然度、改进程度、过度校正克制。不用不透明的单一分数，而是按轴分别打分。

2. 黄金集考试 — 用人工标签（改得好/漏改/过度校正）来考试候选评分器。绝不用于训练，因此黄金集始终保持为试卷，每当评分标准改变时，可重复用作回归测试。

3. 双评分交叉验证 — 用两个评分器对同一道题评分，计算一致率，实证结论是否对评分器选择具有稳健性。

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。原因不在评分器，而在判定设计。漏改的修改保留了语义且没有过度校正，因此权重最大的两个轴（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