spec-score-mcp
Spec Score MCP
Оценивайте свои спецификации перед тем, как Claude начнет их реализацию.
Сбалансированная спецификация порождает сбалансированный код. Несбалансированная спецификация порождает художественный вымысел.
Проблема
Когда ваша спецификация детально проработана по одним осям, но расплывчата по другим, Claude не просит уточнений — он заполняет пробелы сам. Результат компилируется, тесты проходят, но это совсем не то, что вы имели в виду.
Этот инструмент выявляет такие проблемы до начала разработки. Он оценивает вашу спецификацию по 4 осям, указывает на самую слабую из них и дает конкретный совет по исправлению.
Related MCP server: slop-guard
4 оси
Ось | На какой вопрос отвечает |
полнота | Понимает ли Claude весь объем того, что нужно построить? |
ясность | Существует ли только один способ интерпретации этой спецификации? |
ограничения | Знает ли Claude, чего НЕ нужно строить? |
конкретика | Есть ли конкретные, проверяемые детали? |
Каждая ось оценивается от 0.0 до 1.0. Показатель сбалансированности измеряет, насколько равномерно охвачены все 4 оси.
Сбалансированность важнее, чем отдельные оценки. Спецификация с оценкой 0.50 по всем 4 осям (сбалансированность: 0.97) даст лучший результат, чем спецификация с оценками 0.95 / 0.95 / 0.20 / 0.90 (сбалансированность: 0.58). Почему? Та самая слабая ось — ограничения на 0.20 — это именно то место, где Claude начнет импровизировать. Вы детально описали, что нужно построить, но забыли указать, что выходит за рамки проекта. В итоге Claude построит все, что вы просили, плюс функции, которые вам не нужны.
На лепестковой диаграмме: ровный ромб лучше, чем острый шип.
Вердикты
Вердикт | Что это значит |
SHIP IT | Спецификация готова — Claude знает, что строить, а что нет |
ALMOST | Одна ось требует небольшой доработки перед началом |
DRAFT | Несколько осей требуют доработки, но структура уже есть |
VAGUE | Хорошо организована, но слишком абстрактна для реализации |
UNBOUNDED | Ясная цель, но нет границ — Claude построит лишнее |
OVER-CONSTRAINED | Много правил, но неясно, в чем заключается реальная цель |
SKETCH | Отправная точка — требуется детализация по большинству осей |
Еще не SHIP IT? Инструмент подскажет, какая ось самая слабая и что нужно добавить. Исправьте эту ось, переоцените, повторите. Большинство спецификаций достигают статуса SHIP IT за 2-3 итерации.
Установка
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.jsТеперь эти 3 инструмента доступны в каждом сеансе Claude Code.
Использование
Слэш-команды
Клонируйте этот репозиторий, чтобы получить встроенные слэш-команды:
/project:scan my-feature-spec.mdСчитывает файл, оценивает его и записывает my-feature-spec.md.scored.md с оценками, вердиктом, советом и лепестковой диаграммой.
/project:compare blueprint.md implementation.mdОценивает оба файла и записывает compared.scored.md с лепестковыми диаграммами для сравнения.
Прямое использование инструментов
Эти 3 MCP-инструмента работают в любом диалоге Claude Code:
Инструмент | Что он делает |
| Оценивает спецификацию по 4 осям, возвращает показатель сбалансированности и вердикт |
| Генерирует SVG-лепестковую диаграмму на основе оценок |
| Сравнивает две оцененные спецификации бок о бок |
Спросите Claude: "Оцени эту спецификацию", "Покажи мне лепестковую диаграмму" или "Сравни эти две спецификации".
Пример: от UNBOUNDED до SHIP IT
Этот инструмент оценивает свою собственную спецификацию — четыре раунда, каждый из которых исправляет самую слабую ось:
Раунд 1: идея
Создать инструмент для оценки спецификаций
UNBOUNDED 0.12 Tip: What does 'scoring' mean? What axes? What output?Одна ось высокая (ясность — цель ясна), все остальное близко к нулю. Claude построит... что угодно. Веб-приложение? CLI? Расширение для VS Code? Невозможно узнать.
Раунд 2: добавление контекста
Создать MCP-сервер, который оценивает спецификации по 4 осям: полнота, ясность, ограничения, конкретика. Каждая ось от 0.0 до 1.0. Возвращает показатель сбалансированности и вердикт.
ALMOST 0.67 Tip: What are the verdicts? What does the tool NOT do?Теперь Claude знает, что строить. Но ограничения все еще слабые — он может добавить автоисправление, CI-интеграцию, базу данных.
Раунд 3: добавление границ
Три инструмента: spec_score, spec_visualize, spec_compare. Нецели: никакого автоисправления, никакой CI-интеграции, никакого хранилища.
SHIP IT 0.84 Tip: Add testable criteria — what balance maps to which verdict?Порог пройден. Claude теперь знает, что строить И чего не строить. Конкретика все еще самая слабая ось.
Раунд 4: добавление проверяемых деталей
Баланс = 1 - sqrt(дисперсия)/среднее. SHIP IT > 0.75, ALMOST > 0.60, плюс вердикты на основе паттернов. Node.js, MCP SDK, stdio transport.
SHIP IT 0.95 Spec is ready for implementation.Четыре раунда: 0.12 → 0.67 → 0.84 → 0.95. Каждый раунд исправлял ровно одну вещь.
Математика
Claude оценивает каждую ось (0.0 - 1.0)
Нормализация вектора:
v / ||v||Баланс:
1 - sqrt(дисперсия) / среднееВердикт: порог баланса + сопоставление с паттернами осей
Интеллект оценки исходит от Claude, а не от алгоритма. Алгоритм измеряет только сбалансированность.
Структура проекта
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
Лицензия 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