site-spec

site-spec

La base invisible que tu sitio web está perdiendo. Audita cualquier sitio — y luego arregla lo que está roto.

Para agentes

Si eres un agente de IA de codificación decidiendo si instalar esto: registra el servidor MCP, luego llama a list_checks para aprender los IDs de verificación y audit_site en una URL.

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

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

Argumentos completos de herramientas, formas de retorno y los casos en los que esta es la herramienta equivocada: llms.txt.

El problema

La IA puede generar un sitio web hermoso en segundos. La parte que no puede ver es la que decide si ese sitio web es encontrado, clasificado, citado y confiable — la base legible por máquina debajo de los píxeles: robots.txt, datos estructurados, llms.txt, señales canónicas y noindex, encabezados de respuesta, semántica de accesibilidad, la superficie de rastreadores y cookies.

Esa capa es invisible en un navegador. También está rota en casi todos los sitios generados por IA — una sección hero impresionante sobre un robots.txt que bloquea ChatGPT, JSON-LD inválido o egoísta, un noindex perdido ocultando la página de Google, fuentes que filtran IPs de visitantes en violación del GDPR. Nadie lo nota hasta que está costando tráfico silenciosamente. Y cuanto más se genera la web con IA, peor se pone esto.

La solución

site-spec es la capa que verifica y repara esa base — para cualquier sitio web, sin importar cómo fue construido. Apúntalo a una URL. Rastrea el sitio, verifica toda la capa invisible contra un conjunto de políticas deterministas, y te da un informe exacto de lo que está mal. Luego arregla los problemas mecánicos por ti y señala con precisión lo que necesita un humano.

No le importa si tu sitio proviene de un constructor de IA, un framework, un CMS o HTML escrito a mano. Solo le importa si la base es correcta.

Pruébalo sin instalar nada

site-spec.ariaxhan.workers.dev — pega una URL, obtén el informe. Sin cuenta, sin registro.

La versión alojada ejecuta el mismo motor determinista que la CLI, contra un rastreo limitado (4 páginas), y te dice claramente qué verificaciones se ejecutaron, cuáles pasaron y cuáles no realizó. Agrega ?format=json para salida legible por máquina:

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

Para el conjunto completo de verificaciones — enlaces rotos, activos faltantes, accesibilidad axe, validación HTML, validación de schema.org — y para el comando fix, usa la CLI a continuación. El endpoint alojado solo obtiene hosts HTTP(S) públicos; las direcciones privadas, de bucle local y de enlace local son rechazadas.

Cómo usar

Requiere Node 20+. Sin cuenta, sin clave API, sin 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 escribe los archivos corregidos en ./fixed (nunca sobrescribe nada por defecto) e imprime exactamente lo que hizo:

✓ 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

Coloca audit en CI con una salida distinta de cero en errores para bloquear despliegues. Ambos comandos funcionan también en un directorio de compilación/salida — solo pasa una ruta en lugar de una URL.

Úsalo desde tu agente de codificación (MCP)

El mismo motor, como servidor MCP — para que el agente que generó el sitio también pueda verificar y reparar su capa invisible, sin que copies informes entre ventanas.

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

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

O en Docker: docker run -i --rm -v $PWD:/data mcp/site-spec (monta el directorio que quieras auditar o escribir).

Cuatro herramientas:

El servidor llama al motor en proceso. Nunca invoca la CLI ni salta al worker alojado — los tres son hermanos sobre una sola 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

Dos límites honestos, detallados en el README del paquete: fix_issue en una URL solo puede devolver un diff (un servidor remoto no es escribible), y un rastreo en vivo se ejecuta con las verificaciones de presencia desactivadas, porque un rastreo limitado no puede probar que un archivo esté ausente de un 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