bricks-builder-mcp 3.6.5 → 3.7.2

package/README.md

@@ -1,28 +1,44 @@
 # Bricks Builder MCP
 
-Serveur **Model Context Protocol (MCP)** qui permet à Claude (Desktop, Cowork, Claude Code) de piloter **Bricks Builder** sur un site WordPress : lister les pages, lire/modifier le JSON Bricks, ajouter ou réorganiser des sections, etc.
+Serveur **Model Context Protocol (MCP)** qui permet à Claude (Desktop, Cowork, Claude Code) de **piloter Bricks Builder** sur un site WordPress : créer des pages, ajouter des sections, modifier des éléments, uploader des images optimisées, vérifier visuellement le rendu, etc.
 
-## Architecture
+💬 **Communauté Discord** : [https://discord.gg/rX22zHRzH](https://discord.gg/rX22zHRzH) — discussions Bricks + IA, partage de builds, signalement de bugs.
+
+---
+
+## Comment ça marche
 
 ```
-Claude (Desktop / Cowork)
+Claude (Desktop / Cowork / Code)
     ↓ MCP (stdio)
-bricks-builder-mcp  (ce package)
-    ↓ HTTPS + X-API-Key
+bricks-builder-mcp  ← ce package npm, lancé par Claude
+    ↓ HTTPS + clé API
 WordPress + plugin "Bricks Builder MCP Server"
     ↓
-Pages Bricks Builder
+Tes pages Bricks Builder
 ```
 
-## Installation
+Tu installes **2 choses** :
+1. Le plugin WordPress (sur ton site)
+2. Le serveur MCP (ce package npm, lancé automatiquement par Claude)
+
+---
+
+## Installation en 4 étapes
+
+### 1. Installer le plugin WordPress
 
-### Prérequis côté WordPress
+Télécharge la dernière version ici → **[Releases GitHub](https://github.com/Scott1012/bricks-builder-mcp/releases)** (fichier `bricks-mcp.zip`).
 
-Le plugin compagnon **Bricks Builder MCP Server** doit être installé et activé sur le WordPress cible. Il expose les endpoints REST `/wp-json/bricks-mcp/v2/*` et permet de générer la clé API.
+Dans WP admin → Extensions → Ajouter → Téléverser une extension → choisis le `.zip` → Activer.
 
-### Configuration côté Claude
+### 2. Générer ta clé API
 
-Ajoute dans le fichier de configuration Claude (`claude_desktop_config.json` ou équivalent) :
+Dans WP admin → **Réglages → Bricks MCP** → clique "Générer une clé API" → copie-la (commence par `bricks_...`).
+
+### 3. Configurer Claude Desktop
+
+Édite ton fichier `claude_desktop_config.json` (Cmd+, dans Claude Desktop → Developer → Edit Config) :
 
 ```json
 {
@@ -31,7 +47,7 @@ Ajoute dans le fichier de configuration Claude (`claude_desktop_config.json` ou
       "command": "npx",
       "args": ["-y", "bricks-builder-mcp"],
       "env": {
-        "WORDPRESS_URL": "https://exemple-de-site.com",
+        "WORDPRESS_URL": "https://ton-site.com",
         "API_KEY": "bricks_xxxxxxxx"
       }
     }
@@ -39,32 +55,88 @@ Ajoute dans le fichier de configuration Claude (`claude_desktop_config.json` ou
 }
 ```
 
-Redémarre Claude. C'est tout.
+Remplace `WORDPRESS_URL` par l'URL de ton site et `API_KEY` par la clé copiée à l'étape 2.
+
+### 4. Pour utiliser `verify_element` (recommandé) — 1 commande supplémentaire
+
+Dans un terminal, lance une fois :
+
+```bash
+npx playwright install chromium
+```
+
+Ça télécharge Chromium (~130 Mo) pour que Claude puisse prendre des screenshots de tes pages et vérifier le rendu visuellement.
+
+### Redémarre Claude Desktop. C'est tout.
+
+Demande à Claude : *"Liste les pages Bricks de mon site"* — si ça répond, tout marche.
+
+---
 
 ## Variables d'environnement
 
 | Variable | Requis | Description |
 |---|---|---|
-| `WORDPRESS_URL` | oui | URL racine du site WordPress (ex : `https://exemple.com`) |
-| `API_KEY` | oui | Clé API générée dans les réglages du plugin WordPress |
-| `INSECURE_SSL` | non | `true` pour désactiver la vérification SSL (utile en pré-prod avec certificat invalide). **N'utiliser qu'en pré-prod !** |
-
-## Outils MCP exposés
-
-| Outil | Description |
-|---|---|
-| `list_bricks_pages` | Liste toutes les pages Bricks |
-| `get_page_json` | Récupère le JSON complet d'une page |
-| `update_page_json` | Sauvegarde le JSON complet d'une page |
-| `analyze_json_structure` | Analyse la structure d'un JSON Bricks |
-| `get_page_structure` | Vue d'ensemble légère (économe en tokens) |
-| `find_elements` | Recherche d'éléments par critères |
-| `get_element` | Récupère un élément précis |
-| `update_element` | Modifie un élément précis |
-| `add_element` | Ajoute un élément |
-| `batch_add` | Ajoute plusieurs éléments en une fois |
-| `delete_element` | Supprime un élément |
-| `reorder_sections` | Réorganise l'ordre des sections (header en haut, footer en bas) |
+| `WORDPRESS_URL` | oui | URL de ton site (ex : `https://mon-site.com`) |
+| `API_KEY` | oui | Clé API (générée à l'étape 2) |
+| `INSECURE_SSL` | non | `true` pour ignorer un certificat SSL invalide. **Pré-prod uniquement.** |
+
+---
+
+## Outils disponibles (résumé)
+
+**Pages & structure**
+- `list_bricks_pages`, `get_page_structure`, `get_page_json`, `update_page_json`
+- `create_page`, `delete_page`, `update_page_meta`, `duplicate_page`, `set_homepage`
+
+**Éléments**
+- `find_elements`, `get_element`, `update_element` (avec param `label` pour renommer dans le builder), `add_element`, `batch_add`, `delete_element`, `reorder_sections`
+
+**⭐ Vérification visuelle**
+- `verify_element` — screenshot crop + report (computed style vs settings attendus, fonts chargées, erreurs JS console, etc.). **À utiliser après chaque batch_add significatif.**
+
+**⭐ Upload optimisé (v3.8+)**
+- `upload_local_file`, `upload_local_files_batch` — l'IA donne juste le path local, le MCP server lit le fichier, conversion WebP automatique (-80 à -95% de poids), renommage SEO via le `title`
+- `upload_media`, `upload_media_batch` (accepte URL HTTP/HTTPS **ou** data URI)
+- `list_media`
+
+**Design system Bricks natif**
+- `set_custom_code`, `get_custom_code` (CSS + scripts header/footer)
+- `register_google_font_locally`, `list_custom_fonts`
+- `list_color_palette`, `add_color_to_palette`
+- `list_typography_scales`, `set_typography_scale`, `list_spacing_scales`, `set_spacing_scale`
+- `list_global_classes`, `create_global_class`, `update_global_class`
+- `list_theme_styles`, `create_theme_style`
+
+**Menu, médias, navigation**
+- `list_menus`, `add_menu_item`, `list_all_pages`
+
+**Code & sécurité**
+- `set_code_execution`, `get_code_execution_status`
+- `set_page_custom_code`, `get_page_custom_code`
+
+**Feedback (⭐ v3.7+)**
+- `report_missing_feature` — si Bricks supporte une feature nativement mais que le MCP ne l'expose pas, le chat AI le remonte pour qu'on l'ajoute
+- `list_missing_features`, `resolve_missing_feature`
+
+Doc complète + cheat-sheets + patterns dans le skill `bricks-builder` embarqué dans le plugin WP.
+
+---
+
+## Mise à jour
+
+Le plugin WP a un système d'auto-update via GitHub Releases. WP admin → Extensions → "Vérifier les mises à jour" → update.
+
+Le serveur MCP se met à jour automatiquement au prochain lancement de Claude Desktop (grâce à `npx -y`).
+
+---
+
+## Aide
+
+- Bug ou question → [Discord](https://discord.gg/rX22zHRzH)
+- Issue technique → [GitHub Issues](https://github.com/Scott1012/bricks-builder-mcp/issues)
+
+---
 
 ## Licence
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "type": "module",
   "name": "bricks-builder-mcp",
-  "version": "3.6.5",
-  "description": "Serveur MCP pour piloter Bricks Builder (WordPress) depuis Claude — édition de pages, gestion d'éléments, réordonnancement des sections, vérification visuelle + technique (verify_element).",
+  "version": "3.7.2",
+  "description": "Serveur MCP pour piloter Bricks Builder (WordPress) depuis Claude — édition de pages, gestion d'éléments, réordonnancement des sections, vérification visuelle (verify_element), upload optimisé WebP. Communauté Discord : https://discord.gg/rX22zHRzH",
+  "homepage": "https://discord.gg/rX22zHRzH",
   "main": "server.js",
   "bin": {
     "bricks-builder-mcp": "./server.js"

package/server.js

@@ -76,6 +76,49 @@ process.on('exit', () => {
     try { _browser.close(); } catch {}
   }
 });
+
+// ===== v3.7.0 — Helpers upload local =====
+// Le MCP server tourne sur la machine user (lancé par Claude Desktop via stdio),
+// donc il a accès direct au filesystem user. Il peut lire les fichiers et les
+// encoder en base64 LOCALEMENT pour les envoyer au plugin sans jamais que les
+// bytes passent dans le contexte de l'AI.
+
+const MIME_BY_EXT = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mov: 'video/quicktime',
+};
+
+function readLocalFileAsDataUri(localPath) {
+  if (!fs.existsSync(localPath)) {
+    throw new Error(`Fichier introuvable : ${localPath}`);
+  }
+  const stat = fs.statSync(localPath);
+  if (!stat.isFile()) {
+    throw new Error(`Pas un fichier : ${localPath}`);
+  }
+  const ext = (localPath.split('.').pop() || '').toLowerCase();
+  const mime = MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new Error(`Extension non supportée : ${ext} (formats: ${Object.keys(MIME_BY_EXT).join(', ')})`);
+  }
+  const bytes = fs.readFileSync(localPath);
+  const b64 = bytes.toString('base64');
+  return {
+    dataUri: `data:${mime};base64,${b64}`,
+    size: stat.size,
+    mime,
+    ext,
+    basename: localPath.split('/').pop(),
+  };
+}
 process.on('SIGINT', () => {
   if (_browser) {
     try { _browser.close(); } catch {}
@@ -1014,6 +1057,51 @@ mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
         },
       },
 
+      // ===== v3.7.0 — UPLOAD FROM LOCAL FILESYSTEM =====
+      // Lit le fichier directement sur le disque (le MCP server tourne en local),
+      // encode en base64 LOCALEMENT, et l'envoie au plugin via data URI.
+      // L'AI ne voit JAMAIS les bytes — elle donne juste le path.
+      {
+        name: "upload_local_file",
+        description: "⭐ UPLOAD OPTIMAL pour des fichiers locaux. L'AI donne juste le path, le MCP server lit le fichier en local et l'envoie au plugin. Aucun b64 ne transite par le contexte AI. Param `optimize: true` (recommandé) convertit en WebP qualité 80, redim à 2000px max, et renomme avec extension .webp. Idéal pour SEO + perf web. Retourne {success, id, url, filename, optimization: {originalSize, optimizedSize, savings}}.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            localPath: { type: "string", description: "Chemin absolu du fichier local (ex: /Users/.../jt-assets/logo.png)" },
+            title: { type: "string", description: "Titre WP (sert aussi de nom de fichier slugifié — utilisé pour SEO)" },
+            alt: { type: "string", description: "Texte alternatif (OBLIGATOIRE pour SEO + accessibilité)" },
+            caption: { type: "string", description: "Légende optionnelle" },
+            optimize: { type: "boolean", description: "Convertit en WebP qualité 80, redim à 2000px max. Défaut: true (recommandé)." },
+          },
+          required: ["localPath"],
+        },
+      },
+      {
+        name: "upload_local_files_batch",
+        description: "Upload plusieurs fichiers locaux en 1 appel. Même principe que upload_local_file mais en lot. Continue même si certains échouent. Recommandé pour intégrer un dossier d'assets (logos, photos, etc.) en 1 commande.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            items: {
+              type: "array",
+              description: "Liste des fichiers à uploader",
+              items: {
+                type: "object",
+                properties: {
+                  localPath: { type: "string", description: "Chemin absolu du fichier local" },
+                  title: { type: "string", description: "Titre WP (slugifié pour le nom de fichier)" },
+                  alt: { type: "string", description: "Alt SEO" },
+                  caption: { type: "string", description: "Légende" },
+                },
+                required: ["localPath"],
+              },
+            },
+            optimize: { type: "boolean", description: "Convertit tous en WebP. Défaut: true." },
+          },
+          required: ["items"],
+        },
+      },
+
       // ===== v3.6.0 — UPLOAD MEDIA BATCH =====
       {
         name: "upload_media_batch",
@@ -1733,9 +1821,65 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "upload_media_batch":
         result = await callWordPressAPI("/upload-media-batch", "POST", {
           items: args.items,
+          optimize: args.optimize,
         });
         break;
 
+      // ===== v3.7.0 — UPLOAD FROM LOCAL FILESYSTEM =====
+      case "upload_local_file": {
+        try {
+          const fileData = readLocalFileAsDataUri(args.localPath);
+          logToFile(`[upload_local_file] ${args.localPath} (${fileData.size} bytes ${fileData.mime})`);
+          // Le b64 est généré ici, dans le MCP server. Il part vers le plugin
+          // mais ne transite JAMAIS par le contexte AI.
+          result = await callWordPressAPI("/upload-media", "POST", {
+            sourceUrl: fileData.dataUri,
+            title: args.title || fileData.basename.replace(/\.[^.]+$/, ''),
+            alt: args.alt,
+            caption: args.caption,
+            optimize: args.optimize !== false, // défaut true
+          });
+        } catch (err) {
+          result = { success: false, error: err.message, localPath: args.localPath };
+        }
+        break;
+      }
+
+      case "upload_local_files_batch": {
+        const batchItems = [];
+        const readErrors = [];
+        for (const item of (args.items || [])) {
+          try {
+            const fileData = readLocalFileAsDataUri(item.localPath);
+            batchItems.push({
+              sourceUrl: fileData.dataUri,
+              title: item.title || fileData.basename.replace(/\.[^.]+$/, ''),
+              alt: item.alt,
+              caption: item.caption,
+            });
+          } catch (err) {
+            readErrors.push({ localPath: item.localPath, error: err.message });
+          }
+        }
+        if (batchItems.length === 0) {
+          result = {
+            success: false,
+            error: "Aucun fichier lisible",
+            readErrors,
+          };
+          break;
+        }
+        result = await callWordPressAPI("/upload-media-batch", "POST", {
+          items: batchItems,
+          optimize: args.optimize !== false, // défaut true
+        });
+        // Joindre les erreurs de lecture locales au résultat
+        if (readErrors.length > 0) {
+          result.localReadErrors = readErrors;
+        }
+        break;
+      }
+
       default:
         console.error(`[LOG] Tool inconnu: ${name}`);
         result = { error: `Tool ${name} not found` };