spec-score-mcp
Spec Score MCP
Evalúa tus especificaciones antes de que Claude las convierta en código.
Una especificación equilibrada produce código equilibrado. Una especificación desequilibrada produce ficción creativa.
El problema
Cuando tu especificación es detallada en algunos ejes pero vaga en otros, Claude no pide aclaraciones; simplemente rellena los espacios en blanco. El resultado compila y las pruebas pasan, pero no es lo que tenías en mente.
Esta herramienta detecta esto antes de que empieces a construir. Califica tu especificación en 4 ejes, te indica cuál es el más débil y te da un consejo concreto para solucionarlo.
Related MCP server: slop-guard
4 ejes
Eje | Pregunta que responde |
integridad | ¿Puede Claude entender el alcance completo de lo que hay que construir? |
claridad | ¿Hay una sola forma de interpretar esta especificación? |
restricciones | ¿Sabe Claude qué NO construir? |
especificidad | ¿Hay detalles concretos y comprobables? |
Cada eje se califica de 0.0 a 1.0. La puntuación de equilibrio mide qué tan uniformemente cubiertos están los 4 ejes.
El equilibrio importa más que las puntuaciones individuales. Una especificación con 0.50 en los 4 ejes (equilibrio: 0.97) producirá mejores resultados que una con 0.95 / 0.95 / 0.20 / 0.90 (equilibrio: 0.58). ¿Por qué? Ese eje débil —restricciones en 0.20— es exactamente donde Claude improvisará. Describiste qué construir en detalle, pero olvidaste decir qué queda fuera del alcance. Así que Claude construye todo lo que pediste, además de funciones que no querías.
En el gráfico de radar: un diamante uniforme es mejor que una punta afilada.
Veredictos
Veredicto | Qué significa |
SHIP IT | La especificación está lista: Claude sabe qué construir y qué no |
ALMOST | Un eje necesita un pequeño ajuste antes de empezar |
DRAFT | Varios ejes necesitan trabajo, pero la estructura está ahí |
VAGUE | Bien organizada pero demasiado abstracta para actuar sobre ella |
UNBOUNDED | Objetivo claro pero sin límites: Claude construirá de más |
OVER-CONSTRAINED | Muchas reglas pero no está claro cuál es el objetivo real |
SKETCH | Punto de partida: necesita detalles en la mayoría de los ejes |
¿Aún no es SHIP IT? La herramienta te dice qué eje es el más débil y qué añadir. Corrige ese eje, vuelve a calificar y repite. La mayoría de las especificaciones llegan a SHIP IT en 2-3 rondas.
Instalación
git clone https://github.com/openpoem/spec-score-mcp.git
cd spec-score-mcp && npm install && npm run build
claude mcp add spec-score -- node $(pwd)/dist/mcp.jsLas 3 herramientas ahora están disponibles en cada sesión de Claude Code.
Uso
Comandos de barra (Slash commands)
Clona este repositorio para obtener los comandos de barra integrados:
/project:scan my-feature-spec.mdLee el archivo, lo califica y escribe un my-feature-spec.md.scored.md con las puntuaciones, el veredicto, el consejo y un gráfico de radar.
/project:compare blueprint.md implementation.mdCalifica ambos archivos y escribe un compared.scored.md con gráficos de radar comparativos.
Uso directo de herramientas
Las 3 herramientas MCP funcionan en cualquier conversación de Claude Code:
Herramienta | Qué hace |
| Califica una especificación en 4 ejes, devuelve la puntuación de equilibrio y el veredicto |
| Genera un gráfico de radar SVG a partir de las puntuaciones |
| Comparación lado a lado de dos especificaciones calificadas |
Pregúntale a Claude: "Score this spec", "Show me the radar chart" o "Compare these two specs".
Ejemplo: de UNBOUNDED a SHIP IT
Esta herramienta calificando su propia especificación: cuatro rondas, cada una corrigiendo el eje más débil:
Ronda 1: la idea
Construir una herramienta de calificación de especificaciones
UNBOUNDED 0.12 Tip: What does 'scoring' mean? What axes? What output?Un eje es alto (claridad: el objetivo es claro), todo lo demás está cerca de cero. Claude construiría... cualquier cosa. ¿Una aplicación web? ¿Una CLI? ¿Una extensión de VS Code? No hay forma de saberlo.
Ronda 2: añadir contexto
Construir un servidor MCP que califique especificaciones en 4 ejes: integridad, claridad, restricciones, especificidad. Cada eje es 0.0-1.0. Devuelve una puntuación de equilibrio y un veredicto.
ALMOST 0.67 Tip: What are the verdicts? What does the tool NOT do?Ahora Claude sabe qué construir. Pero las restricciones siguen siendo débiles: podría añadir corrección automática, integración con CI, una base de datos.
Ronda 3: añadir límites
Tres herramientas: spec_score, spec_visualize, spec_compare. Objetivos no incluidos: sin corrección automática, sin integración con CI, sin almacenamiento.
SHIP IT 0.84 Tip: Add testable criteria — what balance maps to which verdict?Cruzó el umbral. Claude ahora sabe qué construir Y qué no construir. La especificidad sigue siendo el eje más débil.
Ronda 4: añadir detalles comprobables
Equilibrio = 1 - sqrt(varianza)/media. SHIP IT > 0.75, ALMOST > 0.60, más veredictos basados en patrones. Node.js, MCP SDK, transporte stdio.
SHIP IT 0.95 Spec is ready for implementation.Cuatro rondas: 0.12 → 0.67 → 0.84 → 0.95. Cada ronda corrigió exactamente una cosa.
Las matemáticas
Claude califica cada eje (0.0 - 1.0)
Normalizar el vector:
v / ||v||Equilibrio:
1 - sqrt(varianza) / mediaVeredicto: umbral de equilibrio + coincidencia de patrones de ejes
La inteligencia de calificación proviene de Claude, no del algoritmo. El algoritmo solo mide el equilibrio.
Estructura del proyecto
src/
mcp.ts # MCP server (3 tools)
score.ts # Scoring engine
visualize.ts # SVG radar charts
.claude/
commands/
scan.md # /project:scan command
compare.md # /project:compare commandOpenPoem — spec-score-mcp
Licencia MIT.
© 2026 OpenPoem. info@openpoem.org
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The tools have overlapping purposes that could cause confusion. spec_score and spec_visualize both score a spec on the same four axes and provide the same analysis, making them nearly redundant. Only spec_compare has a clearly distinct function by comparing two specs, but the other two tools are ambiguous in their differentiation.
The naming follows a consistent pattern with all tools using the prefix 'spec_' followed by a verb (compare, score, visualize). This makes the purpose of each tool predictable and readable, though the similarity in naming between spec_score and spec_visualize contributes to the disambiguation issue.
With 3 tools, the count is reasonable for a server focused on spec evaluation. It covers core functions like scoring, comparing, and visualizing specs, which aligns well with the server's purpose, though the overlap between spec_score and spec_visualize suggests the set could be streamlined without losing functionality.
The tool surface is mostly complete for spec evaluation, covering scoring, comparison, and visualization. However, there is a notable gap in tools for editing or updating specs based on the analysis, which could limit workflow coverage. The redundancy between spec_score and spec_visualize also indicates inefficiency rather than a functional gap.
Maintenance
Related MCP Connectors
Scores your code across 12 areas, with findings, fix prompts, and re-assessment in your AI agent
Scores how well AI agents will use your API, 0-100, from its OpenAPI spec. Free and read-only.
PQS scores any prompt before the model runs. 8 dimensions. 5 frameworks. Pre-flight, not post-hoc.
Grade MCP tool definitions for agent-readiness: score, A-F grade, fixes, est. token cost.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceScores MCP tool definitions and tool lists from 0-100, flagging vague descriptions, missing parameter docs, non-verb-first naming, oversized enums, and nested schemas with severity, rationale, and concrete fixes. It also validates marketplace listings against platform character caps such as MCPize's 500-character short-description limit before deploy.MIT
- FlicenseNot gradedqualityAmaintenanceScores text from 0 to 100 for formulaic AI writing patterns using configurable rule-based heuristics with no LLM judge or API calls. Enables agents to lint inline strings or files and receive a score, band, specific violations with context, and concrete advice.-
- FlicenseNot gradedqualityAmaintenanceEnables agents to score prose from 0-100 for formulaic AI writing tells using purely programmatic rule-based heuristics, with no LLM judge or API calls. Returns a numeric score, band label, specific violations with surrounding context, per-category counts, and concrete advice, and can also analyze a file path directly.-
- AlicenseNot gradedqualityCmaintenanceEnables users to grade MCP tool definitions for agent-readiness, returning a score, A–F grade, concrete fixes, and estimated token cost.MIT