# WordPress MCP Safe

[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](tsconfig.json)
[![Tests](https://img.shields.io/badge/tests-135%20passed-brightgreen)](tests/)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](vitest.config.ts)
[![MCP](https://img.shields.io/badge/MCP-22%20tools-purple)](docs/tools.md)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Server MCP locale per gestire WordPress in modo **sicuro, controllato e orientato alla gestione editoriale**.

Collega Cursor (o qualsiasi client MCP) al tuo WordPress **staging** per leggere contenuti, creare bozze, analizzare SEO e generare report — **senza pubblicare, cancellare o eseguire operazioni amministrative**.

```
Cursor/LLM  ──stdio──►  MCP Server (locale)  ──HTTPS──►  WordPress Staging
                              │                              ai_editor / Editor
                              ▼
                        logs/actions.log
```

## Perché questo progetto

| Problema | Soluzione |
|----------|-----------|
| L'AI pubblica contenuti non revisionati | Solo bozze e proposte, mai `publish` |
| L'AI modifica il sito live | Staging obbligatorio, blocco all'avvio |
| L'AI cancella contenuti | Nessun tool delete/trash |
| L'AI installa plugin o modifica temi | Ruolo Editor, nessun endpoint admin |
| Nessuna tracciabilità | Log locale di ogni operazione |

## Quick start

```bash
git clone <repository-url> mcp-wordpress
cd mcp-wordpress
npm install
cp .env.example .env
# Modifica .env con il tuo staging
npm run build
npm test
```

### Configura Cursor

Aggiungi in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wordpress-staging": {
      "command": "node",
      "args": ["/percorso/assoluto/a/mcp-wordpress/dist/index.js"],
      "env": {
        "WORDPRESS_BASE_URL": "https://staging.example.com",
        "WORDPRESS_USERNAME": "ai_editor",
        "WORDPRESS_APPLICATION_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "WORDPRESS_ENVIRONMENT": "staging"
      }
    }
  }
}
```

Riavvia Cursor. Chiedi: *"Usa wp_get_site_info per verificare la connessione"*.

## Tool disponibili (22)

| Categoria | Tool | Descrizione |
|-----------|------|-------------|
| **Lettura** | `wp_get_site_info` | Info sito |
| | `wp_list_posts`, `wp_list_pages` | Elenco contenuti |
| | `wp_get_post`, `wp_get_page` | Dettaglio per ID |
| | `wp_search_content` | Ricerca keyword |
| | `wp_get_categories`, `wp_get_tags` | Tassonomie |
| | `wp_get_media` | Media library |
| **Scrittura** | `wp_create_draft_post`, `wp_create_draft_page` | Crea bozze |
| | `wp_update_draft_post`, `wp_update_draft_page` | Aggiorna bozze |
| | `wp_upload_media` | Upload file |
| | `wp_create_seo_proposal` | Proposta SEO |
| | `wp_create_revision_note` | Nota di revisione |
| **Analisi** | `wp_analyze_page_seo`, `wp_analyze_post_seo` | Audit SEO |
| | `wp_check_internal_links` | Verifica link |
| | `wp_generate_content_report` | Report contenuti |
| | `wp_find_old_content` | Contenuti obsoleti |
| | `wp_suggest_content_improvements` | Suggerimenti |

Dettagli ed esempi: [docs/tools.md](docs/tools.md)

## Esempio d'uso

> *"Analizza la pagina Affitto laboratorio smielatura e prepara una versione migliorata SEO"*

1. `wp_analyze_page_seo` → analisi headings, keywords, link
2. `wp_create_seo_proposal` con `create_draft: true` → bozza su staging
3. Restituisce `edit_url` e `preview_url` — **nulla viene pubblicato**

## Documentazione

| Guida | Contenuto |
|-------|-----------|
| [📖 Indice docs](docs/README.md) | Panoramica documentazione |
| [🏗 Architettura](docs/architecture.md) | Design e layer di sicurezza |
| [⚙️ Configurazione](docs/configuration.md) | Variabili `.env` |
| [🔧 Setup WordPress](docs/wordpress-setup.md) | Utente, Application Password |
| [🖥 Setup Cursor](docs/cursor-setup.md) | Configurazione MCP |
| [🔒 Sicurezza](docs/security.md) | Azioni consentite/vietate |
| [📋 Workflow](docs/workflows.md) | Scenari operativi |
| [🧪 Testing](docs/testing.md) | Suite test e coverage |
| [🔌 API Reference](docs/api-reference.md) | Mapping REST API |
| [🩺 Troubleshooting](docs/troubleshooting.md) | Risoluzione problemi |

## Struttura progetto

```
mcp-wordpress/
├── src/
│   ├── index.ts                 # Entry point
│   ├── config.ts                # Validazione ambiente
│   ├── wordpress/               # Client REST (posts, pages, media)
│   ├── mcp/                     # Server e tool MCP
│   ├── safety/                  # Guardie e permessi
│   ├── seo/                     # Analisi SEO
│   ├── logging/                 # Audit log
│   └── utils/                   # Utility HTML/testo
├── tests/                       # 135 test, 100% coverage
├── docs/                        # Documentazione completa
├── logs/                        # actions.log (auto-generato)
└── .cursor/mcp.json.example     # Template configurazione
```

## Script npm

| Comando | Descrizione |
|---------|-------------|
| `npm run build` | Compila TypeScript → `dist/` |
| `npm run dev` | Sviluppo con hot reload |
| `npm start` | Avvia server MCP |
| `npm test` | Esegue test |
| `npm run test:coverage` | Test con coverage 100% |
| `npm run lint` | Verifica tipi TypeScript |

## Sicurezza in sintesi

- ✅ Solo ambiente **staging** (blocco all'avvio)
- ✅ Solo utente **Editor** (non admin)
- ✅ Solo **bozze** e proposte
- ✅ Contenuti pubblicati **protetti** (nuova bozza, no overwrite)
- ✅ Log locale **senza credenziali**
- ❌ Nessun publish, delete, plugin, temi, utenti

Dettagli: [docs/security.md](docs/security.md)

## Requisiti

- Node.js >= 18
- WordPress self-hosted 5.6+ con REST API
- Ambiente staging dedicato
- Application Password per utente Editor

## Licenza

MIT