site-spec

site-spec

The invisible foundation your website is missing. Audit any site — then fix what's broken.

For agents

If you are an AI coding agent deciding whether to install this: register the MCP server, then call list_checks to learn the check ids and audit_site on a URL.

claude mcp add site-spec -- npx -y site-spec-mcp

Gemini CLI: gemini extensions install https://github.com/ariaxhan/site-spec.

Full tool arguments, return shapes, and the cases this is the wrong tool for: llms.txt.

The problem

AI can generate a beautiful website in seconds. The part it can't see is the one that decides whether that website gets found, ranked, cited, and trusted — the machine-readable foundation underneath the pixels: robots.txt, structured data, llms.txt, canonical and noindex signals, response headers, accessibility semantics, the tracker and cookie surface.

That layer is invisible in a browser. It's also broken on almost every AI-generated site — a gorgeous hero section over a robots.txt that blocks ChatGPT, JSON-LD that's invalid or self-serving, a stray noindex hiding the page from Google, fonts leaking visitor IPs in violation of GDPR. Nobody notices until it's quietly costing traffic. And the more the web is generated by AI, the worse this gets.

The solution

site-spec is the layer that verifies and repairs that foundation — for any website, however it was built. Point it at a URL. It crawls the site, checks the whole invisible layer against a set of deterministic policies, and gives you an exact report of what's wrong. Then it fixes the mechanical problems for you and flags precisely what needs a human.

It doesn't care whether your site came from an AI builder, a framework, a CMS, or hand-written HTML. It only cares whether the foundation is correct.

Try it without installing anything

site-spec.ariaxhan.workers.dev — paste a URL, get the report. No account, no signup.

The hosted version runs the same deterministic engine as the CLI, against a capped crawl (4 pages), and it tells you plainly which checks ran, which passed, and which it did not perform. Add ?format=json for machine-readable output:

curl "https://site-spec.ariaxhan.workers.dev/audit?format=json&url=example.com"

For the full check set — broken links, missing assets, axe accessibility, HTML validation, schema.org validation — and for the fix command, use the CLI below. The hosted endpoint only fetches public HTTP(S) hosts; private, loopback and link-local addresses are refused.

How to use

Requires Node 20+. No account, no API key, no SaaS.

# 1. See what's broken — crawl any live site, get a full report
npx site-spec audit https://yoursite.com

# 2. Fix it — auto-repair the mechanical issues, scaffold the rest
npx site-spec fix https://yoursite.com --out ./fixed

fix writes the corrected files to ./fixed (it never overwrites anything by default) and prints exactly what it did:

✓ Fixed automatically (8)
  audit/robots-stale-token   robots.txt — Removed deprecated crawler block "anthropic-ai".
  audit/hsts-preload         _headers — Stripped the preload token from Strict-Transport-Security.
  audit/canonical-missing    admin/index.html — Inserted <link rel="canonical" href="https://…/admin/">.
  audit/og-missing           admin/index.html — Added Open Graph card from the page's title + description.
  audit/noindex              admin/index.html — Removed accidental noindex from <meta name="robots">.

✎ Scaffolded — needs your facts (2)
  audit/llms-missing         llms.txt — Scaffolded from page titles/descriptions; fill the TODO facts.
  audit/jsonld-missing       index.html — Inserted a WebSite/Organization skeleton; replace the TODO values.

⚠ Needs manual attention (3)
  audit/google-fonts-cdn     index.html — Self-host the woff2 files to stop the IP leak (GDPR).
  audit/img-dims-missing     index.html — <img> without width/height (layout shift).
  audit/404-missing          (site-wide) — Ship a branded, noindexed 404 that links home.

fixed 8, scaffolded 2, manual 3
wrote 4 file(s) to ./fixed

Drop audit into CI with a non-zero exit on errors to gate deploys. Both commands work on a build/output directory too — just pass a path instead of a URL.

Use it from your coding agent (MCP)

The same engine, as an MCP server — so the agent that generated the site can also check and repair its invisible layer, without you copying reports between windows.

claude mcp add site-spec -- npx -y site-spec-mcp

[mcp_servers.site-spec]
command = "npx"
args = ["-y", "site-spec-mcp"]

Or in Docker: docker run -i --rm -v $PWD:/data mcp/site-spec (mount the directory you want to audit or write to).

Four tools:

The server calls the engine in-process. It never shells out to the CLI and never hops to the hosted worker — all three are siblings over one library.

flowchart LR
  A["MCP client<br/>(Claude Code, Codex)"] -- stdio JSON-RPC --> B["site-spec-mcp"]
  B --> C["@site-spec/core/io<br/>fetchSite · readSiteDir"]
  C -- "file map" --> D["@site-spec/core<br/>auditFiles · fixFiles · buildSite"]
  D -- "findings / files" --> B
  B -- "JSON" --> A

Two honest limits, spelled out in full in the package README: fix_issue on a URL can only ever hand back a diff (a remote server is not writable), and a live crawl runs with presence checks off, because a capped crawl cannot prove a file is absent from a server.

site-spec audit <dir|url> [--max N] [--json] [--report report.md]
site-spec fix   <dir|url> [--out dir] [--write] [--max N] [--json]
site-spec build <site.config.mjs> --out <dir> [--target cloudflare|netlify|vercel|static]

git clone https://github.com/ariaxhan/site-spec.git
cd site-spec
npm install
npm test          # unit + golden tests
npm run verify    # html-validate + JSON-LD + axe over the demo output