QoH MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
QoH MCP · Evaluación de un agente de inventario con LLMs locales
Servidor MCP que expone una herramienta de stock por almacén (QoH, quantity on hand) a un LLM local vía Ollama, y la suite de evaluación con la que se llevó de 71 % a 100 % en el set de desarrollo y a 75 % en bruto / 88 % corregido en un held-out nunca usado para iterar, analizando errores y cambiando una sola cosa por experimento.
Los datos son sintéticos: un snapshot de 16 filas inspirado en un catálogo de gestión de cables. No contiene datos reales de ninguna empresa.
Resultados
Configuración final: qwen2.5:7b · prompt v3 · num_ctx 8192 · --ground-check.
Métricas puntuadas con los graders actuales (g5); entre paréntesis, el resultado bruto que dio
la ejecución con los graders de su momento.
Conjunto | Preguntas | Acierto | Tools correctas | Groundedness | Latencia media |
Desarrollo (usado para iterar), 2 ejecuciones | 17 | 100 % · 100 % | 94 % | 100 % | 34,6 s · 32,2 s |
Held-out (nunca usado para iterar) | 8 | 88 % (75 % bruto) | 100 % | 100 % | 45,8 s |
La cifra que vale es la del held-out: el set de desarrollo está inflado por definición, porque el sistema se ajustó mirando sus fallos. La diferencia entre el 75 % bruto y el 88 % es un falso negativo del evaluador en H06 que se corrigió de forma general (ver abajo); se publican las dos.
Cómo se llegó ahí
# | Cambio (uno por experimento) | Acierto dev bruto | Repuntuado g5 | Qué se aprendió |
1 | Baseline: prompt v1 | 71 % | 76 % | 5 fallos: 1 grader, 1 límite del modelo (aritmética), 1 prompt, 2 diseño/descripción de tools |
2 | Arreglos de tools + prompt v2 | 76 % | 76 % | El prompt v2 arregló un caso límite y rompió dos casos normales |
3 | Solo | 76 % | 76 % | Sin efecto: hipótesis de contexto truncado rechazada con datos |
4 | Solo prompt v3 | 82 % | 94 % | Las 2 "regresiones" (Q12, Q15) eran falsos negativos del grader |
5 | Solo | 100 % | 100 % | Elimina la cifra inventada de la pregunta de varios pasos; groundedness 94 % → 100 % por +32 % de latencia |
Comparación de modelos (mismo prompt v3 y mismo eval, g5): qwen2.5:7b 94 % / 26 s frente a
llama3.1:8b 71 % / 54 s. El modelo más pequeño gana.
Validación del LLM juez contra etiquetas humanas
53 trazas distintas etiquetadas a mano (38 PASS / 15 FAIL) con trace_viewer.py, repartidas de
forma fija en DEV (24) y TEST (29). Positivo = PASS; el TNR mide si el juez caza los fallos.
Juez (qwen2.5:7b) | TPR TEST | TNR TEST | Kappa TEST | ¿Fiable (≥ 90 %)? |
j1 zero-shot | 71 % | 75 % | 0,40 | No |
j1 + few-shot con críticas de DEV | 86 % | 50 % | 0,37 | No |
j2 (rúbrica corregida + argumentos de las tools) | pendiente | pendiente | pendiente | — |
Lo que mostró el análisis de los desacuerdos:
Con 4 FAIL, el few-shot parecía una gran mejora (kappa 0,07 → 0,43); con 15 FAIL no lo es. Con pocos negativos, el TNR solo puede valer 0 %, 50 % o 100 %: las muestras pequeñas engañan.
Los fallos del juez eran sobre todo de diseño, no de capacidad: la rúbrica se contradecía ("responde a lo que se pregunta" suspendía rechazos correctos, 5 casos), el juez no veía los argumentos de las tools (no podía detectar
warehouse="total") y no tenía regla para la pregunta ambigua.j2corrige las tres.Lo que el juez no sabe hacer (verificar cálculos o el sentido de una comparación) ya lo hacen los graders deterministas. El juez solo se usa donde el código no llega.
El juez también destapó un error de etiquetado humano (Q14 de llama: omite un SKU bajo mínimos y lo etiqueté como PASS), pendiente de revisar.
Por eso las cifras de este README salen de graders deterministas; el juez solo decide en las 2 preguntas abiertas, y con su validación documentada.
Held-out: fallos y cómo se trataron
Regla: el sistema (prompt, tools, modelo) no se tocó tras ver el held-out. Solo se corrigió el evaluador cuando el fallo era de medición, con un arreglo general y un test de regresión.
H04 — fallo real del modelo. Debía listar los SKUs con más stock virtual que físico; listó todas las discrepancias e invirtió el sentido. Trabajo futuro: que la tool devuelva la discrepancia con signo.
H06 — falso negativo del evaluador. Rechazo correcto ("se centran en el inventario, no en el plazo de entrega"), que el detector de rechazos por frases no reconocía (4.º caso). Ahora basta una negación explícita, y lo que protege es la comprobación de que no se filtran SKUs ni cifras inventadas.
H02 — falso positivo de groundedness. "$9.10" se interpretaba también como 910 (punto de miles) y se marcaba como cifra inventada, lo que disparó una reflexión innecesaria (latencia extra). Ahora un número está respaldado si alguna de sus interpretaciones aparece en los datos. Mismo bug en Q07 del set de desarrollo ("$6,599.68").
Trabajo futuro: normalizar el SKU en la tool (
cbl1042→CBL-1042); hoy lo resuelve el modelo.
Related MCP server: HomeStock
Lecciones
Analiza los errores antes de tocar el prompt. En el primer análisis, solo 1 de 5 fallos se arreglaba con el prompt; el resto eran del grader, de las tools o un límite del modelo.
El evaluador también se evalúa. 6 de los 14 fallos investigados (43 %) eran bugs de los graders, no del modelo. Cada salida real que destapa un bug se convierte en un test de regresión (73 tests).
No pidas cálculos al LLM. Los totales y valores se calculan en la tool.
Groundedness ≠ acierto. Una respuesta puede contener la cifra correcta y además otra inventada.
Un cambio por experimento y graders versionados; si cambia el grader, repuntúa lo antiguo.
Estructura
Archivo | Qué hace |
| Servidor MCP con 4 tools: |
| Snapshot congelado: la única fuente de verdad del eval |
| Set de desarrollo: 17 preguntas (consulta, agregación, comparación, casos límite, fuera de alcance, varios pasos, abierta) |
| Held-out: 8 preguntas nuevas, ejecutadas una sola vez con la configuración congelada |
| Puntuación determinista: exact match, tolerancia numérica, booleano, precision/recall, rechazo, aclaración, groundedness |
| Bucle de agente (Ollama + MCP), reintentos ante caídas, LLM juez para preguntas abiertas, informe JSON |
| Compara dos ejecuciones pregunta a pregunta (arreglos y regresiones) |
| Repuntúa una ejecución guardada con los graders actuales, sin volver a llamar al modelo |
| Visor de trazas en Streamlit con anotación humana (PASS/FAIL, crítica, modo de fallo) y conteo de modos de fallo |
| Valida el LLM juez contra las etiquetas humanas: TPR, TNR y kappa en DEV y TEST |
| 53 etiquetas humanas del experto (PASS/FAIL, crítica, modo de fallo) |
| Tests del evaluador (respuesta buena pasa, mala falla) y end-to-end sin LLM |
| Informes JSON brutos de las ejecuciones citadas; |
Uso
pip install -r requirements.txt
ollama pull qwen2.5:7b
python -m pytest tests -q # 1) el evaluador funciona
python run_evals.py --prompt v3 --num-ctx 8192 --ground-check # 2) eval de desarrollo
python run_evals.py --eval eval_holdout_qoh.yaml --prompt v3 --num-ctx 8192 --ground-check
python compare_runs.py # compara las dos últimas ejecuciones
streamlit run trace_viewer.py # revisar y etiquetar trazas
python validate_judge.py # ¿coincide el juez con el experto?
python validate_judge.py --fewshot # juez con las críticas de DEV como ejemplosOpciones: --model, --judge-model, --only Q01,Q11, --cpu, --prompt v2|v3,
--num-ctx, --ground-check.
Decisiones de diseño
Determinista primero: todas las preguntas salvo la abierta se puntúan con código; el juez se contrasta con un recall de SKUs de referencia porque un juez sin validar no decide solo.
Dos métricas separadas: acierto de la respuesta y acierto de las tools (nombre, orden y argumentos válidos), para distinguir "razonó mal" de "eligió mal la herramienta".
Tests de alucinación: SKU inexistente, búsqueda imposible, pregunta ambigua y fuera de alcance.
Errores de infraestructura aparte: una caída de Ollama se reintenta y, si persiste, no cuenta como fallo del modelo.
Prompts y graders versionados (
--prompt,GRADER_VERSION), registrados en cada informe.Groundedness: toda cifra de la respuesta debe aparecer en la salida de alguna tool. Con
--ground-check, si el modelo inventa una cifra se le pide que corrija una vez (reflexión).
Limitaciones
Eval pequeño (17 + 8 preguntas) y una ejecución por configuración: el modelo no es del todo determinista, así que las diferencias de una pregunta (≈6 puntos) no son significativas.
El groundedness es una heurística numérica: puede marcar datos derivados (porcentajes) como no respaldados.
El juez es el mismo modelo de 7B que se evalúa y no supera el umbral de fiabilidad (ver «Validación del LLM juez»). La partición TEST ya se ha mirado para diseñar j2: una validación limpia de j2 necesita etiquetas nuevas.
Licencia
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
LLM Observability & Orchestration Agent (LangChain Community)
Memory, reflection and safety for AI agents. Hosted or local, no vector database.
LLM Orchestration Agent (Langsmith)
Git-backed platform for skills, tools, and context for AI agents
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables document retrieval, OCR, web search, and calculator tools via a RAG pipeline and LangGraph agent, all running locally with Ollama.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to manage a local-first household inventory, recording receipt emails and maintaining a probabilistic estimate of stock levels. Provides tools to query stock, identify items to reorder, and correct ingestion errors, all without any cloud dependency.191Functional Source , Version 1.1, MIT Future
- AlicenseNot gradedqualityCmaintenanceEnables an AI agent to query a warehouse management system for orders, stock, stalled orders, and audit logs, and to make narrowly scoped writes by changing order status with a required reason or appending notes, with all writes recorded in a full audit trail.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to manage inventory conversationally: list and look up products, check current stock levels, record inbound and outbound movements idempotently, review movement history, and surface items below their minimum threshold. Every figure is grounded in tool calls rather than model estimation, and invalid operations return explicit error codes the agent can reason about.5MIT