superaudit-mcp
by Jorucmor
README.md
# superaudit-mcp
Servidor MCP (Model Context Protocol) que expone la auditoría real de [SuperAudit](https://superaudit.es) como una tool
que cualquier agente de IA compatible con MCP puede llamar.
Con esto, un desarrollador externo puede pedirle a su propio agente (Claude,
u otro cliente MCP) cosas como *"audita esta web con SuperAudit"* sin hablar
con nadie del equipo de SuperAudit — la tool llama directamente al endpoint
público de producción.
## Qué hace
Expone una única tool: **`audit_website`**.
- **Input:**
- `url` (obligatorio): dominio o URL a auditar, p. ej. `"minegocio.es"` o
`"https://minegocio.es"`.
- `raw_json` (opcional, `boolean`, por defecto `false`): si es `true`,
además del resumen legible devuelve el JSON completo tal cual lo entrega
SuperAudit (todos los módulos, todas las puntuaciones, los planes).
- **Qué hace por dentro:** llama a
`POST https://superaudit.es/api/quick-audit` con
`{ "web": "<url>" }` — el mismo endpoint público que usa hoy la landing de
SuperAudit para el escaneo gratuito. No necesita ninguna clave ni token.
- **Output:** un resumen en texto con el score global (0-100), la
puntuación de cada uno de los ~27 módulos (SEO, seguridad, legal/RGPD,
Core Web Vitals, accesibilidad WCAG, posicionamiento en IA generativa,
WordPress/CVEs, OWASP Top 10, etc.), los principales problemas detectados
y el plan de pago que SuperAudit recomienda según el resultado.
## Novedades de la 1.0.1 (28-oct-2026)
- **Legal y seguridad primero:** «Principales hallazgos» y la lista de módulos
empiezan por legal/RGPD y seguridad; después, lo demás por peor nota. Antes
salían en el orden en que llegaban los módulos (con el SEO el primero).
- **«Plan recomendado» corregido:** usa el precio y el texto que manda el
servidor hoy (antes imprimía «(undefined€) — undefined»).
- Indica si la medición está **confirmada** y qué áreas no se pudieron confirmar.
- `npm test` compila y ejecuta las pruebas del resumen.
## Límites conocidos (importante)
- El endpoint público tiene un **límite de 10 peticiones por minuto por
IP** en el servidor de SuperAudit. Si se supera, la tool devuelve un
error indicándolo — no reintenta automáticamente para no saturar el
servicio.
- Además del límite por minuto, desde el 28-oct-2026 hay un **tope diario por
IP: 8 radiografías nuevas al día** (las que ya están en caché no cuentan).
Y un máximo de mediciones simultáneas: con mucha demanda el servidor
responde 503 («inténtalo de nuevo en un minuto»).
- El backend cachea cada dominio auditado durante **24 horas**, así que
volver a auditar la misma web en poco tiempo es instantáneo.
- Desde el 28-oct-2026 cada auditoría se **mide dos veces** y las dos tienen
que coincidir (si no, una tercera); por eso una auditoría en frío tarda
~40-60 s (tope de 85 s). El resumen lo indica: «Medición confirmada: N
pasadas que coinciden».
- Una auditoría "en frío" (dominio no cacheado) puede tardar bien varios
segundos: el cliente espera hasta 90s antes de dar el intento por
fallido.
- El backend valida que la URL apunte a un dominio público real (bloquea
IPs privadas/localhost como medida SSRF) — si la web no existe o no está
online, la tool devuelve un error legible, no un fallo silencioso.
## Instalación rápida (desde GitHub)
Requisitos: Node.js 18 o superior. No hace falta clonar nada:
```bash
claude mcp add superaudit -- npx -y github:Jorucmor/superaudit-mcp
```
Para Claude Desktop u otro cliente MCP, usa `"command": "npx"` y `"args": ["-y", "github:Jorucmor/superaudit-mcp"]`.
## Instalación desde el código (alternativa)
```bash
git clone <este repositorio> # o simplemente copia esta carpeta
cd superaudit-mcp
npm install
npm run build
```
Esto genera `dist/index.js`, que es el binario del servidor MCP (habla por
`stdio`, el transporte estándar de MCP).
### Probarlo suelto (opcional)
```bash
npm run build
node dist/index.js
```
El proceso se queda esperando en stdio — es normal, así funcionan los
servidores MCP. Se conecta desde un cliente MCP, no se usa como CLI
interactiva.
## Cómo conectarlo a un cliente MCP
### Claude Code
```bash
claude mcp add superaudit -- node "/ruta/completa/a/superaudit-mcp/dist/index.js"
```
### Claude Desktop
Editar el archivo de configuración de Claude Desktop (`claude_desktop_config.json`)
y añadir:
```json
{
"mcpServers": {
"superaudit": {
"command": "node",
"args": ["/ruta/completa/a/superaudit-mcp/dist/index.js"]
}
}
}
```
Reiniciar Claude Desktop. La tool `audit_website` aparecerá disponible para
que el agente la use cuando la conversación lo requiera (p. ej. "audita
minegocio.es con SuperAudit").
### Cualquier otro cliente MCP
Cualquier cliente que soporte servidores MCP por `stdio` puede lanzar
`node dist/index.js` como comando del servidor — no requiere configuración
adicional ni variables de entorno.
## Variables de entorno (opcionales)
- `SUPERAUDIT_BASE_URL`: por defecto `https://superaudit.es`.
Solo tiene sentido cambiarla para apuntar a un entorno de pruebas propio.
No hace falta ninguna API key: el endpoint que usa esta tool es el mismo
que la landing pública de SuperAudit usa para el escaneo gratuito.
## Desarrollo
```bash
npm install
npm run build # compila TypeScript → dist/
```
`npm test` compila y ejecuta las pruebas del resumen (10). Además se verificó
con un cliente MCP real (handshake `initialize` + `tools/list` + `tools/call`)
contra el endpoint de producción.
## Uso responsable
Audita solo webs propias o de clientes que te hayan dado permiso. La radiografía
mira la web desde fuera, como cualquier visitante, y no cambia nada en ella.
Más información: https://superaudit.es/guias/mcp/
TDQS
A4.2/5.0
Scored across 1 tool
Disambiguation5/5
Only one tool exists, so there is no ambiguity between tools. The single tool has a clear, distinct purpose around website auditing.
Naming Consistency5/5
With a single tool, the naming is trivially consistent. 'audit_website' follows a clear verb_noun pattern.
Tool Count3/5
A single tool feels thin and borderline for a server. It consolidates many audit checks into one call, but offers no auxiliary operations like listing or retrieving past audits.
Completeness4/5
The tool comprehensively covers the core audit workflow, including many modules. Minor gaps exist, such as no ability to fetch historical audits or compare results over time.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues