spec-score

Spec-score MCP is a server that evaluates a software specification and scores it across four axes: completeness, clarity, constraints, and specificity. Each axis returns a score from 0.0 to 1.0 and the server also provides a balance score and a verdict indicating how ready the spec is for implementation. The MCP exposes three tools: spec_score (score a spec and return detailed axis scores and balance verdict), spec_visualize (generate an SVG radar chart from scores), and spec_compare (compare two scored specs side-by-side). In Claude Code sessions you can invoke these tools directly in conversations or via slash commands, allowing you to iteratively improve your spec before you start building. Use the slash commands to score a spec document, then visualize the results to better understand weak axes and guide refinements. You can also run the HTTP API endpoints (POST /api/score, /api/visualize, /api/compare) if you want programmatic access outside of Claude.

Prerequisites:

• Node.js and npm installed on your machine (Node 14+ recommended).
• Access to a shell/terminal.

Install the MCP server globally via npm:

npm i -g spec-score-mcp

Alternatively, you can run it via npx without a global install:

npx spec-score-mcp

Once installed, start the MCP server (the tool will be ready to use in Claude Code sessions or via CLI depending on your setup). In Claude, add the MCP with the command npx spec-score-mcp or the equivalent npx invocation if you used the CLI route. For development or local testing, you can clone the repository and run the TypeScript source directly with ts-node or build steps as described in the repository’s contributing guide (not required for end users).

Usage in Claude:

• In Claude Code, add the MCP with the command shown above so that the three tools (spec_score, spec_visualize, spec_compare) are available in all conversations.

Notes and tips:

• The MCP focuses on four axes to guide spec refinement. Use the weakest axis as a priority target for improvement.
• Balance score is a key signal: aim for a well-distributed score across all axes rather than a spike on a single axis.
• The tools are designed to be used together: first score with spec_score, then generate a radar chart with spec_visualize, and finally compare two candidate specs with spec_compare for side-by-side evaluation.
• If you’re integrating programmatically, you can use the HTTP API endpoints to score and visualize specs from your own tooling.
• Ensure your spec documents are well-formed and clearly labeled so the scoring engine can interpret them accurately.