Tutoriels inédits sur le CMS Joomla

Le développement Joomla évolue vite. Très vite. Et depuis l'émergence des IA comme Claude d'Anthropic, les possibilités d'automatisation de la gestion de contenu s'ouvrent à des horizons que l'on n'imaginait pas il y a encore deux ans. Cet article raconte comment web54 a développé, pas à pas et en conditions réelles, la gestion complète des médias Joomla depuis une conversation avec Claude Desktop.

À l'origine : une discussion avec Cyrille de Joomnet

Tout a commencé lors d'un échange avec Cyrille de Joomnet, acteur bien connu de la communauté Joomla francophone. La question posée était simple : jusqu'où peut-on aller avec le protocole MCP pour piloter un site Joomla depuis une IA ? Les articles, les catégories, les menus — tout cela fonctionnait déjà. Mais qu'en était-il des médias ? Images, dossiers, médiathèque...

C'est cette discussion qui a lancé le chantier. Chez web54, agence web spécialisée en développement Joomla en Lorraine, nous avons décidé de pousser l'expérience jusqu'au bout et de documenter chaque étape — y compris les erreurs, les pièges et les solutions trouvées.

Le protocole MCP et l'API REST Joomla : rappel du contexte

Le Model Context Protocol (MCP) est un standard développé par Anthropic qui permet à Claude Desktop de se connecter à des "serveurs d'outils" locaux. Ces serveurs exposent des fonctions que Claude peut appeler en langage naturel. Pour Joomla, nous avons développé un petit serveur Node.js qui fait le pont entre Claude et l'API REST native de Joomla 5.

L'API REST de Joomla expose un endpoint /api/index.php/v1/media/files qui permet, en théorie, de lister, uploader et organiser les fichiers de la médiathèque. En théorie — parce que dans la pratique, plusieurs comportements non documentés nous ont réservé quelques surprises.

Développement de l'outil uploader_image (depuis une URL)

Le premier outil développé permet à Claude d'uploader une image directement depuis une URL distante. L'idée : pouvoir dire à Claude "uploade cette image dans le dossier articles, nom 'ma-photo' : https://example.com/photo.jpg" et la voir apparaître immédiatement dans la médiathèque Joomla.

Le principe technique est le suivant :

1. Le serveur MCP télécharge l'image depuis l'URL avec node-fetch
2. L'image est convertie en base64
3. Le contenu encodé est envoyé à l'API Joomla via un POST sur /media/files
4. Le Content-Type HTTP de la réponse est analysé pour détecter automatiquement l'extension (.jpg, .png, .webp, .gif)

server.tool('uploader_image', 'Uploader une image depuis une URL distante',
  {
    url:     z.string(),
    nom:     z.string(),
    dossier: z.string().optional(),
  },
  async ({ url, nom, dossier = 'articles' }) => {
    const imageRes = await fetch(url);
    const ct  = imageRes.headers.get('content-type') || 'image/jpeg';
    const ext = ct.includes('png') ? 'png' : ct.includes('webp') ? 'webp'
              : ct.includes('gif') ? 'gif' : 'jpg';
    const base64 = Buffer.from(await imageRes.arrayBuffer()).toString('base64');
    await joomla('/media/files', 'POST', {
      path: `${dossier}/${nom}.${ext}`,
      content: base64
    });
  }
);

Cet outil fonctionne très bien pour récupérer des images depuis des banques d'images libres de droits (Unsplash, Picsum, etc.) ou depuis n'importe quelle URL publique.

Développement de l'outil uploader_image_locale (depuis le PC)

Le second outil est plus ambitieux : uploader une image depuis le disque dur local de l'utilisateur. Claude Desktop ayant accès au système de fichiers Windows via le serveur MCP (qui tourne localement), il suffit de passer le chemin absolu du fichier :

"Uploade C:\Users\serge\Pictures\photo.jpg dans le dossier produits"

Techniquement, le serveur utilise fs/promises de Node.js pour lire le fichier, l'encoder en base64, puis l'envoyer à l'API Joomla :

import fs from 'fs/promises';
import path from 'path';

server.tool('uploader_image_locale', 'Uploader une image depuis votre PC',
  {
    chemin_local: z.string(),
    nom:          z.string().optional(),
    dossier:      z.string().optional(),
  },
  async ({ chemin_local, nom, dossier = 'articles' }) => {
    const buffer   = await fs.readFile(chemin_local);
    const ext      = path.extname(chemin_local).replace('.', '').toLowerCase() || 'jpg';
    const basename = nom ?? path.basename(chemin_local, path.extname(chemin_local));
    const base64   = buffer.toString('base64');
    await joomla('/media/files', 'POST', {
      path: `${dossier}/${basename}.${ext}`,
      content: base64
    });
  }
);

Le piège du double préfixe images/ — un bug silencieux

C'est LE piège qui nous a coûté plusieurs heures de débogage, et que nous documentons ici précisément pour que vous ne tombiez pas dedans.

L'API REST Joomla pour les médias ajoute automatiquement le préfixe images/ à tous les chemins envoyés. Si vous envoyez :

path: "images/articles/photo.jpg"

Joomla va créer le fichier dans :

images/images/articles/photo.jpg  ← CHEMIN FANTÔME

Le plus traître : l'API répond 200 OK avec les métadonnées complètes du fichier (dimensions, taille, date...). Tout semble parfait. Mais en FTP, le fichier est introuvable. Et dans le backend Joomla, la médiathèque ne l'affiche pas. Aucun message d'erreur, aucun avertissement.

Développement de l'outil creer_dossier_media

Lors des premiers tests d'upload, nous avons constaté que l'API Joomla refusait d'uploader une image dans un dossier inexistant — sans créer automatiquement le dossier. Il fallait donc un outil dédié à la création de dossiers.

Bonne nouvelle : l'API /media/files accepte un paramètre type: 'dir' pour créer un dossier :

server.tool('creer_dossier_media', 'Créer un dossier dans la médiathèque',
  { dossier: z.string() },
  async ({ dossier }) => {
    await joomla('/media/files', 'POST', { path: dossier, type: 'dir' });
  }
);

Workflow typique :

1. "Crée un dossier evenements/2026" → Claude appelle creer_dossier_media
2. "Uploade cette image dans evenements/2026" → Claude appelle uploader_image

Lors des tests, nous avons également découvert que Joomla crée automatiquement le dossier si celui-ci n'existe pas, lorsqu'on uploade un fichier. L'outil creer_dossier_media reste utile pour pré-créer des dossiers vides ou des arborescences avant tout upload.

Les outils MCP médias disponibles aujourd'hui

Au terme de ce développement, le serveur MCP Joomla expose quatre outils dédiés à la gestion de la médiathèque, tous pilotables en langage naturel depuis Claude Desktop :

Ce que ce développement Joomla change concrètement

Au-delà de l'aspect technique, ce qui est frappant dans cette expérience, c'est la fluidité du workflow une fois le serveur MCP en place. Rédiger un article, y associer une image récupérée sur le web, organiser sa médiathèque par dossiers thématiques — tout cela se fait en langage naturel, sans quitter Claude Desktop, sans ouvrir l'administration Joomla.

Pour une agence web comme web54, qui gère de nombreux sites Joomla pour ses clients, les perspectives sont réelles : alimentation de sites en contenu, gestion de médiathèques volumineuses, automatisation de tâches répétitives. Le développement Joomla entre dans une nouvelle ère où l'IA devient un véritable co-pilote du CMS.

Article rédigé par Serge Billon — web54.fr | Agence web Joomla en Lorraine — en collaboration avec la communauté Joomla francophone