jdevalk/specification.website: a sourced, platform-agnostic web spec you can query over MCP

The problem is fragmentation across WHATWG, W3C, IETF and search engine docs

The README describes the web as a layer cake of standards. WHATWG defines HTML, W3C ratifies WCAG, the IETF publishes the RFCs behind security headers and /.well-known/ URIs, IANA registers namespaces, search engines publish their own rules, and browsers add quirks. The stated observation is that almost nobody carries the whole picture. This repository is an attempt to collect those slices into one place.

The audience follows from that framing. It is written for people who need to check a requirement against its source rather than against a blog post: engineers auditing a site, accessibility specialists who want WCAG 2.2 references next to the rule, and teams preparing a site to be read by AI agents. The README is explicit that this is not a framework and not a tutorial, and compares its intent to the HTML Living Standard: outcomes, requirements, references. If you want a plugin recommendation, this is the wrong document.

Ten categories, four status levels, and a citation on every page

Content is organised into ten categories listed in the README: Foundations, SEO, Accessibility, Security, Well-Known URIs, Agent Readiness, Performance, Privacy, Resilience and Internationalisation. Each page carries a status level. Required means the web platform contract breaks without it. Recommended means modern sites should do it. Optional depends on context. Avoid marks something outdated, harmful or actively superseded.

That four-level scale is the most useful design decision in the repository. A spec that only lists good practice leaves you guessing about priority. Avoid is the level that does the real work, because it gives maintainers a citable reason to remove something rather than a preference to argue about. The README also states that where there is no settled standard, the spec says so, which is a commitment worth checking on the pages you actually depend on.

Every page cites at least one source. The list in the README runs from the WHATWG HTML Living Standard and MDN Web Docs through WCAG 2.2 and its Understanding documents, IETF RFCs, sitemaps.org, schema.org, llmstxt.org, Google Search Central, web.dev, the Yoast Developer Portal, Equalize Digital's Accessibility Checker docs, the WP Accessibility Knowledge Base, Is It Agent Ready?, and the Overlay Fact Sheet. The inclusion of the Overlay Fact Sheet is a position: accessibility overlays are treated as a known problem rather than a solution.

Astro content collections generate the site, the feeds and the MCP data

Spec pages live as markdown under src/content/spec/<category>/. The README points to src/content/spec/foundations/title.md as an example to copy, and to src/content.config.ts for the front matter schema. Minimum fields are title, summary, category, status, order and sources. The body follows a fixed section order: What it is, Why it matters, How to implement, Common mistakes, Verification.

That fixed shape is what makes the rest of the pipeline possible. The README states that everything derived from the spec content updates automatically: /spec/, /checklist/, /llms.txt, /llms-full.txt, /sitemap-index.xml, /rss.xml, per-page .md endpoints, the Pagefind search index, and the MCP server's bundled data. The instruction attached to that list is blunt: never hand-edit those, edit the source markdown.

The build fails if the schema is invalid, and the README says that is intentional. For a contributed spec this is the right trade. A missing source or a malformed status stops the build rather than quietly shipping an uncited page. The cost is that contributors cannot add a page with a field the schema does not yet know about without changing src/content.config.ts first.

Running it locally: Node 22.12+, port 31337, static output in ./dist

The README lists Node.js 22.12+ and npm as the only requirements. Four commands cover the workflow:

npm install npm run dev (serves http://localhost:31337) npm run build (static output in ./dist) npm run preview (serves ./dist on port 31337)

The dev server port is described as a convention in the README, with the aside that it is 31337 because of course it does. Build output is static, which matches the deployment badge pointing at Cloudflare Pages.

The MCP piece is separate. A Cloudflare Worker in mcp/ exposes the spec to MCP-aware agents, and the README directs you to mcp/README.md for the tool list, the connection configuration and deployment steps. The live endpoint is given as https://mcp.specification.website/mcp. Because the worker bundles data derived from the content collection, an agent querying that endpoint sees the same rules as the website. How the worker is deployed, and what its tool surface looks like, is not in this README; you have to open mcp/README.md.

A platform-agnostic spec deliberately stops before your codebase

The clearest limitation is stated as a feature. The README says the spec is not platform-specific and gives the example that there is no advice to use a particular Next.js plugin: the spec describes the outcome, you choose the implementation. That is a defensible editorial line, but it means the gap between reading a requirement and satisfying it is entirely yours to close. A team on WordPress, Next.js or a hand-rolled stack gets the same page and no migration path.

The second constraint is freshness. The repository has no releases retrieved, so there is no versioned snapshot to pin against. The spec tracks living documents: the HTML Living Standard, WCAG 2.2, evolving search engine guidance and the newer agent-readiness material around llms.txt. Content can change between your audit and your next one, and nothing in the material describes a changelog for spec pages.

The third is scope. Ten categories are covered, but the README does not claim completeness, and the contributing rules ask contributors to be honest about status. Treat it as a checklist with citations, not as a conformance suite. Nothing in the repository runs your site and tells you which requirements you fail.

How it differs from web.dev, MDN and an accessibility checker

The nearest comparison is MDN Web Docs, which the project itself cites as a source. MDN explains a feature: what it does, its syntax, its browser support, its history. This repository states an outcome and the status attached to it. For a decision like whether to keep a deprecated attribute, the spec's Avoid level and its cited source are a faster read than assembling the same conclusion from reference pages. For learning what an attribute does in the first place, MDN is the better tool and the spec assumes you already know.

The other comparison is an automated accessibility checker, such as the Equalize Digital tool the README cites. A checker scans your rendered pages and reports violations against a rule set. This repository has no scanner. It gives you the rule and the WCAG reference so a human can judge the cases a scanner misses. The two are complementary: the spec tells you what the requirement is, the checker tells you whether your current build meets it.

The MCP server is the part with no direct equivalent in either. Exposing the same content as tools to an MCP-aware agent means an agent can look up a requirement instead of recalling one. Whether that matters depends on whether your workflow already has agents in it.

Maintenance cost and the split licence

The licence is split, and the distinction matters if you reuse the material. Content is CC BY 4.0, which requires attribution when you republish or adapt it. Code is MIT. The repository metadata reports the licence as NOASSERTION, while the README and the badges state MIT for code and CC BY 4.0 for content, so check LICENSE and the content licence statement before you assume a single licence covers the whole repository. This is a description of what the files say, not legal advice.

Maintenance cost for a fork is mostly editorial. The build enforces the front matter schema, so adding a category means editing src/content.config.ts and then adding markdown under src/content/spec/<category>/. The derived artefacts (/llms.txt, /sitemap-index.xml, /rss.xml, the Pagefind index and the MCP bundle) regenerate from source, so there is nothing to keep in sync by hand. The recurring work is watching the sources you cite. When WCAG, an RFC or search engine guidance moves, the page and its status level need a review, and the README's contributing rules ask for exactly that: cite your sources, stay platform-agnostic, be honest about status.

If you consume the hosted MCP endpoint rather than forking, the maintenance question shifts to the upstream project. There is no release history retrieved, so there is no pinned version to depend on.

Editorial conclusion

Adopt it if you need a citable, platform-agnostic checklist for HTML, SEO, accessibility, security and agent-readiness, or if you want the same rules exposed to an MCP-aware agent through the worker in mcp/. Do not adopt it expecting implementation guidance: the README states there is no framework-specific advice, so a Next.js or WordPress team still has to translate each requirement itself. Before relying on it, check the front matter schema in src/content.config.ts against the categories you care about, and read the status level assigned to each page, since Required and Avoid carry very different weight.

Official sources

1. Issues
2. jdevalk/specification.website on GitHub
3. Project website
4. README