provespec-mcp

MCP server over the public ProveSpec catalog — pull a specification, build against it, then grade what you built.

No account, no database, no desktop app. Specs are fetched over HTTPS and grading is computed locally, so this process holds nothing and stores nothing.

Install

claude mcp add provespec -- npx -y provespec-mcp

Any MCP client works. The raw command is npx -y provespec-mcp over stdio; Node 18+.

Not on npm yet? Run it straight from source:

claude mcp add provespec -- npx -y github:AlanKharebov/provespec-mcp

Tools

Tool	What it does
catalog_list	Every published spec, optionally filtered by category
spec_search	Keyword search; deep: true also matches individual capability names
spec_get	One spec as a readable outline, optionally scoped to a top-level group
spec_checklist	The same spec as a flat, gradeable list of capability paths
spec_grade	Score an implementation: parity %, missing, partial, ungraded, beyond-spec
spec_diff	Compare two specs: what one asks that the other does not
spec_match	Novelty check — does the catalog already cover the spec you are about to write

How it's meant to be used

"Build me a URL shortener to the ProveSpec spec."

The agent calls spec_search → spec_get, builds against a real capability list instead of a vague prompt, then calls spec_checklist → spec_grade to check its own work. The gap list is the remaining work queue.

"Grade this repo against TodoMVC."

spec_checklist gives the agent the questions to answer; it reads the code and returns a verdict per capability with a file reference as evidence. The report says what is missing, what is half-built, and what exists beyond the spec.

Scopes

Software specs put engine capabilities under AI and interface capabilities under UI, so parity can be asked per layer:

spec_get(slug: "todomvc", scope: "AI")     → engine only
spec_grade(slug: "todomvc", scope: "UI", grades: [...])

Asking "does the interface expose what the engine can do?" is the same relation pointed at two layers of one product.

Grading rules

• Parity is fully-has / specified, matching the ProveSpec desktop app exactly.
• Statuses: yes · partial · no · na.
• Anything you leave ungraded counts as missing — silence is not credit.
• na on either side (spec or grade) drops the capability from the denominator.
• Grades that match no capability in the spec are reported as beyond the spec, not as defects — a build may legitimately do more than the spec asks.
• Paths accept ["A","B"], "A > B" or "A/B", and match case- and space-insensitively.

Configuration

Variable	Default	Purpose
PROVESPEC_SITE	https://provespec.com	Point at a mirror or a local site

Responses are cached in memory for 10 minutes.

Development

npm install
node test.mjs      # pure logic, no network
node smoke.mjs     # end-to-end against the live catalog

Licence

MIT for this server. The specifications it fetches are CC BY 4.0 — see https://provespec.com.