# superaudit-mcp

Servidor MCP (Model Context Protocol) que expone la auditoría real y
gratuita de [SuperAudit](https://superaudit.airpagents.pro) 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.airpagents.pro/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.

## 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.
- El backend cachea cada dominio auditado durante **24 horas**, así que
  volver a auditar la misma web en poco tiempo es instantáneo.
- 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 (para un desarrollador externo)

Requisitos: Node.js 18 o superior.

```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.airpagents.pro`.
  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/
```

No hay tests automatizados en este entregable inicial — se verificó
manualmente con un cliente MCP real (handshake `initialize` + `tools/list`
+ `tools/call`) contra el endpoint de producción.