kiubi-local-mcp

Serveur MCP local pour l'intégration de thèmes graphiques Kiubi. Il expose aux agents IA (Claude, Cursor…) un ensemble d'outils dédiés : documentation opérationnelle, introspection du thème courant et validation statique des fichiers.

Table des matières

• Prérequis
• Architecture
• Installation
• Configuration MCP
  • Claude Desktop
  • VS Code
  • PHPStorm
• Intégration dans un projet Kiubi
  • Structure du projet
  • kiubi-sync
  • Déploiement du CLAUDE.md
• Tools disponibles

Prérequis

| Outil | Version minimale | Notes | |:---------|:-----------------|:----------------------------------------------------------| | Node.js | 22.18 | Requis pour --strip-types (exécution native TypeScript) | | npm | 10+ | Inclus avec Node.js |

Architecture

Projet intégrateur/
├── theme/               ← fichiers du thème (géré par kiubi-sync)
├── gulpfile.js          ← tâches kiubi-sync (pull / deploy / watch)
├── config.json          ← credentials FTP kiubi-sync (ne pas committer)
└── CLAUDE.md            ← instructions agent (copie de CLAUDE.exemple.md)

~/tools/kiubi-local-mcp/ ← serveur MCP (installation fixe, partagée)

Le serveur MCP est lancé automatiquement par l'éditeur au démarrage d'une session. Il communique via stdio et accède au thème à travers le répertoire de travail de l'éditeur.

Installation

Cloner le dépôt dans un emplacement fixe sur la machine (partagé entre tous les projets) :

git clone https://github.com/Kiubi/dev-mcp.git ~/tools/kiubi-local-mcp
cd ~/tools/kiubi-local-mcp
npm ci

Configuration MCP

Le serveur se déclare dans la configuration MCP de l'éditeur. Adapter ~/tools/kiubi-local-mcp si le dépôt a été cloné ailleurs.

Claude Desktop

Éditer ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "kiubi-mcp": {
      "command": "npx",
      "args": ["/Users/VOTRE_NOM/tools/kiubi-local-mcp"]
    }
  }
}

Remplacer /Users/VOTRE_NOM/tools/kiubi-local-mcp par le chemin absolu réel. npx résout ce chemin local et exécute le bin déclaré dans son package.json, sans passer par le registre npm.

Redémarrer Claude Desktop pour prendre en compte la modification.

Alternative — npx via le registre npm public (à venir)

Prérequis non encore en place — cette option suppose que @kiubi/dev-mcp soit publié sur le registre npm public, ce qui n'est pas encore le cas. Une fois publié, la configuration suivante permet d'utiliser toujours la dernière version sans dépendre d'un clone local :

{
  "mcpServers": {
    "kiubi-mcp": {
      "command": "npx",
      "args": ["-y", "@kiubi/dev-mcp@latest"]
    }
  }
}

npx se charge de télécharger et d'exécuter la dernière version publiée, sans installation manuelle ni chemin à adapter.

VS Code

Éditer .vscode/mcp.json à la racine du projet intégrateur (ou le fichier de configuration MCP globale de l'extension) :

{
  "servers": {
    "kiubi-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["/Users/VOTRE_NOM/tools/kiubi-local-mcp"]
    }
  }
}

Remplacer /Users/VOTRE_NOM/tools/kiubi-local-mcp par le chemin absolu réel. npx résout ce chemin local et exécute le bin déclaré dans son package.json, sans passer par le registre npm.

Remarque — Le répertoire de travail du serveur MCP doit être la racine du projet intégrateur (là où se trouve theme/). Les éditeurs MCP-compatibles utilisent en général le workspace ouvert comme répertoire de travail.

Alternative — npx via le registre npm public (à venir)

Prérequis non encore en place — cette option suppose que @kiubi/dev-mcp soit publié sur le registre npm public, ce qui n'est pas encore le cas. Une fois publié, la configuration suivante permet d'utiliser toujours la dernière version sans dépendre d'un clone local :

{
  "servers": {
    "kiubi-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kiubi/dev-mcp@latest"]
    }
  }
}

npx se charge de télécharger et d'exécuter la dernière version publiée, sans installation manuelle ni chemin à adapter.

PHPStorm

Le support MCP dans PHPStorm passe par le plugin Claude Code (JetBrains Marketplace). La configuration se fait en ligne de commande via le CLI claude, depuis le terminal intégré de PHPStorm.

Option A — Configuration projet (fichier .mcp.json commité dans le dépôt, recommandé) :

claude mcp add kiubi-mcp --scope project -- npx /Users/VOTRE_NOM/tools/kiubi-local-mcp

Cela crée ou met à jour .mcp.json à la racine du projet :

{
  "mcpServers": {
    "kiubi-mcp": {
      "command": "npx",
      "args": ["/Users/VOTRE_NOM/tools/kiubi-local-mcp"]
    }
  }
}

Option B — Configuration globale (partagée entre tous les projets de la machine) :

claude mcp add kiubi-mcp --scope user -- npx /Users/VOTRE_NOM/tools/kiubi-local-mcp

Remplacer /Users/VOTRE_NOM/tools/kiubi-local-mcp par le chemin absolu réel. npx résout ce chemin local et exécute le bin déclaré dans son package.json, sans passer par le registre npm. Le serveur est disponible immédiatement dans la session Claude Code sans redémarrage.

Remarque — Le répertoire de travail du serveur MCP doit être la racine du projet intégrateur (là où se trouve theme/). Les éditeurs MCP-compatibles utilisent en général le workspace ouvert comme répertoire de travail.

Alternative — npx via le registre npm public (à venir)

Prérequis non encore en place — cette option suppose que @kiubi/dev-mcp soit publié sur le registre npm public, ce qui n'est pas encore le cas. Une fois publié, la configuration suivante permet d'utiliser toujours la dernière version sans dépendre d'un clone local :

claude mcp add kiubi-mcp --scope project -- npx -y @kiubi/dev-mcp@latest

ou pour une configuration globale :

claude mcp add kiubi-mcp --scope user -- npx -y @kiubi/dev-mcp@latest

npx se charge de télécharger et d'exécuter la dernière version publiée, sans installation manuelle ni chemin à adapter.

Intégration dans un projet Kiubi

Structure du projet

Un projet d'intégration de thème Kiubi se structure ainsi :

mon-projet-kiubi/
├── theme/               ← thème graphique Kiubi (synchronisé avec kiubi-sync)
│   ├── theme.xml
│   └── fr/
│       ├── templates/
│       ├── widgets/
│       ├── billets/
│       └── ...
├── gulpfile.js
├── config.json          ← credentials FTP (à exclure du dépôt git)
├── package.json
└── CLAUDE.md            ← voir ci-dessous

kiubi-sync

kiubi-sync est le module npm officiel Kiubi pour synchroniser les fichiers du thème entre l'environnement local et le serveur. Il remplace le client FTP et s'intègre via Gulp.

Il expose trois commandes principales :

| Commande | Rôle | |:------------------|:----------------------------------------------------------| | npm run pull | Télécharge tous les fichiers du thème depuis le serveur | | npm run deploy | Envoie les fichiers locaux vers le serveur | | npm run watch | Surveille les modifications et synchronise en temps réel |

Procédure recommandée : exécuter d'abord un pull pour récupérer le thème existant, puis démarrer watch pendant le développement. Le serveur MCP travaillera sur ces fichiers locaux.

Consulter la documentation kiubi-sync pour l'installation complète et la configuration du gulpfile.js.

Déploiement du CLAUDE.md

Le fichier storage/documents/CLAUDE.exemple.md contient les instructions nécessaires pour que l'agent IA comprenne le contexte Kiubi et utilise correctement les tools MCP. Il doit être copié à la racine du projet intégrateur sous le nom CLAUDE.md :

cp ~/tools/kiubi-local-mcp/storage/documents/CLAUDE.exemple.md ./CLAUDE.md

Ou téléchargé à l'adresse : https://github.com/Kiubi/dev-mcp/blob/main/storage/documents/CLAUDE.exemple.md

Ce fichier est lu automatiquement par Claude à chaque session. Il définit notamment :

• Le comportement de l'agent face au thème (validation obligatoire avant toute modification)
• Les workflows d'intégration (micro-correction, intervention standard)
• Les règles CSS et les conventions git à respecter
• Le pipeline complet d'une tâche d'intégration

Important — CLAUDE.md est spécifique à chaque projet. Il peut être versionné dans le dépôt git du projet intégrateur.

Tools disponibles

| Tool | Description | |:------------------|:----------------------------------------------------------------------------| | validate_theme | Valide la syntaxe et la cohérence de tous les fichiers du thème | | ruleset | Retourne les règles du moteur de template Kiubi (balises, filtres, syntaxe) | | get_doc_section | Accède à la documentation : guide d'intégration, exemples, API front-office | | list_types | Liste les éléments du thème par type (billets, composants, produits…) | | detail_type | Retourne le détail d'un élément (champs, zones, collection) | | list_widgets | Liste tous les widgets et leurs templates alternatifs | | create_type | Crée ou met à jour un type d'élément (génère les fichiers XML et HTML) | | search_doc | Recherche transversale dans la documentation |