judge-mcp

English: README.en.md

Evaluación de calidad de texto LLM-as-Judge como servidor MCP.

Puntúa pares de texto original y texto corregido con una rúbrica ponderada multieje, pone a prueba (no entrena) los modelos evaluadores con un conjunto dorado de etiquetas humanas, y valida de forma cruzada el grado de concordancia entre dos evaluadores. Todo se expone como herramientas MCP, de modo que puedes ejecutar evaluaciones conversacionalmente desde cualquier cliente MCP, como Claude Desktop o Claude Code.

Por qué lo creé

En la corrección, la reescritura y el resumen no existe una única respuesta correcta, por lo que cada vez más equipos recurren a evaluadores LLM. Pero un evaluador sin validar no es más que otra opinión. Este servidor generaliza como herramienta la metodología validada en un proyecto de análisis de registros de un servicio real.

1. Rúbrica ponderada multieje — preservación del significado, naturalidad, grado de mejora y moderación de la sobrecorrección. En lugar de una puntuación única y opaca, evalúa por ejes.

2. Prueba con conjunto dorado — prueba a los candidatos a evaluador con etiquetas humanas (bien corregido / sin corregir / sobrecorregido). Nunca se usan para entrenar, de modo que el conjunto dorado se mantiene como examen, y se reutiliza como prueba de regresión cada vez que cambia la rúbrica.

3. Validación cruzada de doble evaluación — puntúa la misma pregunta con dos evaluadores, mide el grado de concordancia y demuestra empíricamente si la conclusión es robusta frente a la elección del evaluador.

4. Prefiltro determinista — los pares sin cambios los puntúa el código sin LLM. Es barato y siempre da la misma respuesta.

Related MCP server: mcp-eval-harness

Herramientas

Incluye un conjunto dorado sintético de 24 preguntas de corrección en coreano (3 grupos), y con golden_path puedes usar tu propio conjunto dorado (JSONL: id, original, revised, label).

Instalación y configuración

Funciona con cualquier backend compatible con OpenAI: OpenAI, vLLM local, 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

En examples/ tienes un ejemplo de configuración para Claude Desktop. Tras configurarlo, puedes preguntar cosas como:

• "Puntúa esta corrección: original '오늘 회의 몇시에 시작하나요', corregido '몇 시에 시작하나요?'"

• "Ejecuta el conjunto dorado con gpt-4o-mini y muéstrame el boletín"

• "Compara si gpt-4o-mini y el Qwen local coinciden como evaluadores"

Resultados medidos

Resultados de probar las 24 preguntas del conjunto dorado integrado con Claude Sonnet (backend claude-cli):

Reprodúcelo tú mismo: python scripts/run_golden.py --backend claude-cli (para API compatible con OpenAI, --backend api).

Caso práctico: el conjunto dorado detectó un defecto de diseño

La primera ejecución dio 62,5 % — el grupo de sin corregir obtuvo 0/8. La causa no era el evaluador, sino el diseño del veredicto. Una corrección sin cambios preserva el significado y no sobrecorrige, así que los dos ejes con mayor peso (0,40 + 0,35) alcanzan la puntuación máxima, y aunque el eje de mejora dé 1 punto, el total queda entre 8 y 9. Detectar los casos sin corregir mediante la puntuación total era matemáticamente imposible.

Corrección: el veredicto del grupo de sin corregir pasó de la puntuación total al eje de mejora (improvement) ≤ 4. Al volver a probar, el resultado pasó de 62,5 % a 83,3 %, y el grupo de sin corregir de 0/8 a 7/8. Para eso existe el bucle de regresión del conjunto dorado: sacó a la luz un defecto de diseño de la evaluación que estaba oculto, lo corrigió y lo dejó fijado con una prueba de regresión. (Brecha restante: en el grupo de sobrecorregido se observa variabilidad entre ejecuciones de la evaluación LLM — es candidato a reforzarse con anclas few-shot, y la mejora puede validarse con el mismo bucle de regresión).

Notas de diseño

• La validación del evaluador es lo esencial. Los modelos evaluadores tienen tendencias opuestas en su estado por defecto, así que elegir sin probar es adivinar. La precisión se mide por dirección: una corrección bien hecha puntúa alto (≥7), y una sin corregir o sobrecorregida, bajo (≤5). La zona gris (5~7) se trata deliberadamente como respuesta incorrecta.

• La reproducibilidad es prioritaria. temperature 0, salida JSON forzada con análisis tolerante a vallas de código y divagaciones, límites de rango en las puntuaciones y, para los casos que no necesitan modelo (sin cambios), ruta por código.

• Errores accionables. Los fallos de conexión o de esquema no devuelven un stacktrace, sino un mensaje que indica "qué hay que arreglar".

Pruebas

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

Licencia

MIT