# Mcp-Wacta — opera la suite WaCta con cualquier IA

Servidor **MCP** (Model Context Protocol) que permite a Claude, Codex, Cursor o cualquier cliente MCP leer y cambiar la configuración de la suite WaCta de WordPress, gestionar el **Registro Único de CTAs** y consultar la **analítica de WhatsApp** — en remoto y con credenciales revocables.

- **Cero dependencias**: un solo archivo ([server.mjs](server.mjs)), Node ≥ 18, sin `npm install`.
- **Instalable en un comando**: `npx -y mcp-wacta` desde npm, plugin de Claude Code (servidor + skill juntos) o paquete de un clic para Claude Desktop.
- **Protocolo estándar**: transporte stdio de MCP (JSON-RPC 2.0) con tolerancia a clientes que piden `prompts`/`resources`.
- **Seguridad de serie**: Application Passwords de WordPress, `manage_options` en cada endpoint, y cada escritura pasa por los **mismos sanitizadores** que el panel de la suite.
- **Skill incluida**: [skills/wacta/SKILL.md](skills/wacta/SKILL.md) con las recetas y reglas para que el agente lo use bien desde el primer minuto.

```
┌──────────┐   stdio (MCP)   ┌────────────┐   HTTPS + App Password   ┌───────────────────┐
│ IA/agente│ ◄─────────────► │ mcp-wacta  │ ◄──────────────────────► │ WordPress + WaCta  │
│ (Claude, │                 │ (npx/plugin│      /wp-json/…/admin/*  │ core·Studio·waux·CRM│
│  Codex…) │                 │  /desktop) │                          └───────────────────┘
└──────────┘                 └────────────┘
```

## Requisitos

1. **WordPress con la suite WaCta ≥ 0.8** (el core expone `wacta/v1/admin/*`).
2. **Application Password** de un usuario administrador: wp-admin → Usuarios → Perfil → *Contraseñas de aplicación*. Requiere HTTPS (en local sin SSL: `define( 'WP_ENVIRONMENT_TYPE', 'local' );` en `wp-config.php`).
3. **Node.js ≥ 18** en la máquina del cliente MCP.

## Credenciales (3 variables, iguales en todos los clientes)

| Variable | Ejemplo |
|---|---|
| `WACTA_SITE_URL` | `https://misitio.com` |
| `WACTA_USER` | `admin` |
| `WACTA_APP_PASSWORD` | `xxxx xxxx xxxx xxxx xxxx xxxx` |

## Instalación

### Claude Desktop — un clic

Descarga `mcp-wacta.mcpb` desde [Releases](https://github.com/Kanzando/Mcp-Wacta/releases), ábrelo con doble clic e introduce los 3 datos cuando Claude Desktop los pida — la contraseña se guarda en el llavero del sistema, nunca en un archivo.

### Claude Code — plugin (servidor + skill juntos)

```
/plugin marketplace add Kanzando/Mcp-Wacta
/plugin install wacta@kanzando
```

Exporta las 3 variables de entorno en tu sistema y listo: el plugin instala el servidor **y** la skill de una vez. Alternativa sin plugin:

```bash
claude mcp add wacta -e WACTA_SITE_URL=https://misitio.com -e WACTA_USER=admin -e "WACTA_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx" -- npx -y mcp-wacta
```

### Codex CLI

En `~/.codex/config.toml`:

```toml
[mcp_servers.wacta]
command = "npx"
args = ["-y", "mcp-wacta"]

[mcp_servers.wacta.env]
WACTA_SITE_URL = "https://misitio.com"
WACTA_USER = "admin"
WACTA_APP_PASSWORD = "xxxx xxxx xxxx xxxx xxxx xxxx"
```

### Cursor / VS Code / Windsurf / Gemini CLI / genérico

El bloque universal es siempre el mismo — `command: "npx"`, `args: ["-y", "mcp-wacta"]` y las 3 variables en `env`. Guía por cliente: **[docs/clients.md](docs/clients.md)** · plantillas copiables: **[examples/](examples/)**.

> ¿Sin acceso a npm? Clona el repo y usa `node /ruta/a/Mcp-Wacta/server.mjs` como comando — todo lo demás es idéntico.

## Herramientas

| Herramienta | Qué hace |
|---|---|
| `wacta_status` | Versión del core, complementos activos, CTAs registrados y tope del plan. |
| `wacta_get_settings` | Configuración completa de `core` / `studio` / `analytics` / `crm`. |
| `wacta_update_settings` | Cambia ajustes (semántica PATCH) con los sanitizadores del panel. |
| `wacta_list_ctas` | CTAs del Registro Único con su tope. |
| `wacta_save_cta` | Crea/actualiza un CTA por slug (adopción por selector, mensaje, captura…). |
| `wacta_delete_cta` | Elimina un CTA por slug. |
| `wacta_analytics_dashboard` | Panel de Analytics en JSON — con `cta_totals` (CTAs globales) y `source_conversion` (qué fuente convierte). |
| `wacta_analytics_ctas` | Inventario de CTAs observados con contadores por página. |
| `wacta_studio_numbers` | Catálogo de números de WhatsApp de CTA Studio. |

Referencia completa con argumentos y ejemplos: **[docs/tools.md](docs/tools.md)**.

## La skill (la otra mitad de la lógica MCP + skill)

El MCP da las herramientas; la skill enseña al agente a usarlas bien: **leer antes de escribir** (`wacta_status` primero), cambios PATCH mínimos, verificación contra la respuesta saneada, confirmación humana para interruptores con impacto público y el slug como identidad intocable — más las recetas de los casos comunes.

- **Claude Code**: el plugin la instala automáticamente; también funciona sola al trabajar dentro de este repo, o cópiala a `~/.claude/skills/wacta/` para tenerla en cualquier proyecto.
- **Codex y agentes que leen AGENTS.md**: [AGENTS.md](AGENTS.md) contiene la misma doctrina en su convención.
- **Claude Desktop**: el `.mcpb` incluye la carpeta `skills/` para consulta, y las descripciones de las herramientas ya llevan lo esencial.

## Ejemplos de peticiones a la IA

- «Activa el widget de WaCta con el número 5215512345678 y el mensaje "Hola, quiero información".»
- «Crea un CTA `promo-navidad` que adopte los botones `.btn-wa` con captura activada.»
- «¿Qué campaña generó más leads este mes?»
- «Apaga el modo gobernado de botones externos de Studio.»

## Desarrollo

```bash
node test/smoke.mjs                      # handshake MCP + inventario, sin credenciales
npx -y @anthropic-ai/mcpb pack           # construir el paquete de Claude Desktop (.mcpb)
```

Solución de problemas (401, contraseñas de aplicación en local, `rest_no_route`): **[docs/troubleshooting.md](docs/troubleshooting.md)**.

## Seguridad

- Nada es público: cada endpoint exige `manage_options`; sin credenciales la API responde 401.
- El Application Password se revoca desde el perfil sin cambiar la contraseña real.
- Los ajustes con secretos (tokens de Meta del CRM, licencia MaxMind) **no** están expuestos por estas rutas.
- Este repo y el paquete npm no almacenan credenciales jamás; en Claude Desktop van al llavero del sistema.

## Licencia

[MIT](LICENSE) © KanZansio.Digital