Spec Score Mcp
io.github.openpoemPublished by GitHub account openpoemv2.0.2Updated Oct 24, 2026
Score your specs before feeding them to an LLM. MCP server with radar chart visualization.
Overview
Scores a written specification on four axes, returns a balance score and verdict, and renders an SVG radar chart.
- What you can do
- The server exposes three tools: spec_score scores a spec on completeness, clarity, constraints and specificity (each 0.0-1.0) and returns a balance score plus a verdict such as SHIP IT, ALMOST, DRAFT, VAGUE, UNBOUNDED, OVER-CONSTRAINED or SKETCH; spec_visualize generates an SVG radar chart from scores; spec_compare puts two scored specs side by side. It also reports the weakest axis and a tip for fixing it. The scoring itself is done by the assistant, while the algorithm measures how evenly the axes are covered.
- When to use it
- Useful before handing a feature spec or design document to an assistant for implementation, to catch vague or unbounded requirements early. Also handy for comparing a blueprint against a finished implementation, or for iterating on a spec until it reaches a ready verdict.
- Requirements
- Runs locally as a stdio process on the user's machine, installed from the npm package spec-score-mcp; the README's install path clones the repository, runs npm install and npm run build, then registers the built entry point with the assistant. Node.js is required. No authentication, environment variables or headers are declared. Desktop only; not available as a web executable.
Installation
In SourceWeft
- Open Spec Score Mcp in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Spec Score MCP
Score your specs before Claude builds from them.
A balanced spec produces balanced code. An unbalanced spec produces creative fiction.
The problem
When your spec is detailed on some axes but vague on others, Claude doesn't ask for clarification — it fills in the blanks. The result compiles, the tests pass, but it's not what you meant.
This tool catches that before you start building. It scores your spec on 4 axes, tells you which one is weakest, and gives you a concrete tip to fix it.
4 axes
Each axis scores 0.0 to 1.0. The balance score measures how evenly the 4 axes are covered.
Balance matters more than individual scores. A spec scoring 0.50 on all 4 axes (balance: 0.97) will produce better output than one scoring 0.95 / 0.95 / 0.20 / 0.90 (balance: 0.58). Why? That one weak axis — constraints at 0.20 — is exactly where Claude will improvise. You described what to build in detail, but forgot to say what's out of scope. So Claude builds everything you asked for, plus features you didn't.
On the radar chart: an even diamond beats a sharp spike.
Verdicts
Not SHIP IT yet? The tool tells you which axis is weakest and what to add. Fix that axis, re-score, repeat. Most specs reach SHIP IT in 2-3 rounds.
Install
The 3 tools are now available in every Claude Code session.
Usage
Slash commands
Clone this repo to get the built-in slash commands:
Reads the file, scores it, and writes a my-feature-spec.md.scored.md with scores, verdict, tip, and a radar chart.
Scores both files and writes a compared.scored.md with side-by-side radar charts.
Direct tool use
The 3 MCP tools work in any Claude Code conversation:
Ask Claude: "Score this spec", "Show me the radar chart", or "Compare these two specs".
Example: from UNBOUNDED to SHIP IT
This tool scoring its own spec — four rounds, each fixing the weakest axis:
Round 1: the idea
[Round 1: UNBOUNDED (0.12)]Build a spec scoring tool
One axis is high (clarity — the goal is clear), everything else is near zero. Claude would build... anything. A web app? A CLI? A VS Code extension? No way to know.
Round 2: add context
[Round 2: ALMOST (0.67)]Build an MCP server that scores specs on 4 axes: completeness, clarity, constraints, specificity. Each axis is 0.0-1.0. Returns a balance score and verdict.
Now Claude knows what to build. But constraints are still weak — it might add auto-fixing, CI integration, a database.
Round 3: add boundaries
[Round 3: SHIP IT (0.84)]Three tools: spec_score, spec_visualize, spec_compare. Non-goals: no auto-fixing, no CI integration, no storage.
Crossed the threshold. Claude now knows what to build AND what not to build. Specificity is still the weakest axis.
Round 4: add testable details
[Round 4: SHIP IT (0.95)]Balance = 1 - sqrt(variance)/mean. SHIP IT > 0.75, ALMOST > 0.60, plus pattern-based verdicts. Node.js, MCP SDK, stdio transport.
Four rounds: 0.12 → 0.67 → 0.84 → 0.95. Each round fixed exactly one thing.
The math
- Claude scores each axis (0.0 - 1.0)
- Normalize the vector:
v / ||v|| - Balance:
1 - sqrt(variance) / mean - Verdict: balance threshold + axis pattern matching
The scoring intelligence comes from Claude, not from the algorithm. The algorithm only measures balance.
Project structure
OpenPoem — spec-score-mcp
MIT License.
© 2026 OpenPoem. [email protected]
Source: README.md at commit b92ddae
Tools
0Version history
1- v2.0.2LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts