site-spec

site-spec

A fundação invisível que falta no seu site. Audite qualquer site — e depois corrija o que está quebrado.

Para agentes

Se você é um agente de IA de codificação decidindo se deve instalar isto: registre o servidor MCP e, em seguida, chame list_checks para aprender os IDs de verificação e audit_site em uma URL.

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

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

Argumentos completos das ferramentas, formatos de retorno e os casos em que esta é a ferramenta errada: llms.txt.

O problema

A IA pode gerar um site bonito em segundos. A parte que ela não consegue ver é a que decide se esse site será encontrado, ranqueado, citado e confiável — a fundação legível por máquina sob os pixels: robots.txt, dados estruturados, llms.txt, sinais de canonical e noindex, cabeçalhos de resposta, semântica de acessibilidade, a superfície de rastreadores e cookies.

Essa camada é invisível no navegador. Também está quebrada em quase todo site gerado por IA — uma seção hero deslumbrante sobre um robots.txt que bloqueia o ChatGPT, JSON-LD inválido ou autosserviço, um noindex perdido escondendo a página do Google, fontes vazando IPs de visitantes em violação ao GDPR. Ninguém percebe até que isso comece a custar tráfego silenciosamente. E quanto mais a web é gerada por IA, pior isso fica.

A solução

site-spec é a camada que verifica e repara essa fundação — para qualquer site, independentemente de como foi construído. Aponte-o para uma URL. Ele rastreia o site, verifica toda a camada invisível contra um conjunto de políticas determinísticas e fornece um relatório exato do que está errado. Em seguida, ele corrige os problemas mecânicos para você e sinaliza com precisão o que precisa de um humano.

Ele não se importa se o seu site veio de um construtor de IA, um framework, um CMS ou HTML escrito à mão. Ele só se importa se a fundação está correta.

Experimente sem instalar nada

site-spec.ariaxhan.workers.dev — cole uma URL e obtenha o relatório. Sem conta, sem cadastro.

A versão hospedada executa o mesmo mecanismo determinístico da CLI, com um rastreamento limitado (4 páginas), e informa claramente quais verificações foram executadas, quais passaram e quais não foram realizadas. Adicione ?format=json para saída legível por máquina:

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

Para o conjunto completo de verificações — links quebrados, assets ausentes, acessibilidade axe, validação de HTML, validação de schema.org — e para o comando fix, use a CLI abaixo. O endpoint hospedado só busca hosts HTTP(S) públicos; endereços privados, loopback e link-local são recusados.

Como usar

Requer Node 20+. Sem conta, sem chave de API, sem 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 grava os arquivos corrigidos em ./fixed (nunca sobrescreve nada por padrão) e imprime exatamente o que fez:

✓ 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

Coloque audit no CI com saída não zero em erros para bloquear deploys. Ambos os comandos funcionam também em um diretório de build/saída — basta passar um caminho em vez de uma URL.

Use a partir do seu agente de codificação (MCP)

O mesmo mecanismo, como um servidor MCP — para que o agente que gerou o site também possa verificar e reparar sua camada invisível, sem que você copie relatórios entre janelas.

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

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

Ou em Docker: docker run -i --rm -v $PWD:/data mcp/site-spec (monte o diretório que deseja auditar ou gravar).

Quatro ferramentas:

O servidor chama o mecanismo em processo. Ele nunca invoca a CLI externamente e nunca passa pelo worker hospedado — todos os três são irmãos sobre uma única biblioteca.

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

Dois limites honestos, detalhados no README do pacote: fix_issue em uma URL só pode sempre devolver um diff (um servidor remoto não é gravável), e um rastreamento ao vivo é executado com verificações de presença desativadas, porque um rastreamento limitado não pode provar que um arquivo está ausente de um servidor.

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