kazaplan-mcp

Piloter le concepteur 3D Leroy Merlin (Virtual Home, moteur Kazaplan) en langage naturel, depuis n'importe quel assistant compatible MCP (Claude, Codex, Gemini CLI, Cursor, VS Code…) :

« Mets une baignoire de 170 cm dans la salle de bain » « Meuble le salon en scandinave » « Dessine ma maison d'après cette photo du plan »

Le dépôt contient :

• un serveur MCP (kazaplan-mcp) : ouvrir un plan, chercher dans le catalogue Leroy Merlin, poser des meubles, peindre, construire des murs, contrôler la circulation, dessiner des plans SVG, enregistrer ;
• deux skills au format ouvert Agent Skills : kazaplan-decorator (aménager et décorer une pièce à partir de l'identité décorative de la maison) et kazaplan-floorplan (dupliquer un plan, le tracer d'après la photo d'un plan).

Sommaire

1. Démarrage rapide
2. Jeton et identifiant du plan
3. Configuration
4. Brancher le serveur sur votre assistant
5. Installer les skills
6. Utilisation
7. Sécurité et sauvegardes
8. Dépannage
9. Développement

1. Démarrage rapide

Deux façons de lancer le serveur, sans rien cloner :

Installer uv : curl -LsSf https://astral.sh/uv/install.sh | sh (macOS / Linux) ou powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).

Au premier lancement, le serveur télécharge le catalogue Leroy Merlin (≈ 350 Mo, quelques minutes), en construit un index local (≈ 25 Mo) et jette le reste. Pendant ce temps, les outils du catalogue répondent « catalogue en cours de téléchargement ». Pour le faire à l'avance, ou récupérer plus tard les nouveautés :

uvx --from git+https://github.com/padupuy/kazaplan-mcp kazaplan-mcp catalog

Vous n'utilisez pas Claude Code ? Passez à l'étape 2. Avec Claude Code, le plugin installe le serveur et les skills d'un coup :

/plugin marketplace add padupuy/kazaplan-mcp
/plugin install kazaplan@kazaplan-mcp

2. Jeton et identifiant du plan

Le jeton

Le serveur agit avec votre session Leroy Merlin. Le jeton est valable environ 7 jours.

1. Ouvrez https://www.leroymerlin.fr/config-3d/virtual-home, connectez-vous et ouvrez votre projet.
2. Outils de développement : F12 (Windows / Linux) ou ⌥ ⌘ I (macOS), onglet Réseau, filtre api.kazaplan.com.
3. Enregistrez une petite modification dans le planner (ou rechargez la page).
4. Cliquez sur une requête, section En-têtes de la requête, ligne Authorization: Bearer eyJ….
5. Copiez tout ce qui suit Bearer .

L'identifiant du plan

Dans le même onglet Réseau, une requête api.kazaplan.com/plans/12345678 : le nombre à la fin est l'identifiant de votre plan.

3. Configuration

Sans KZ_ALLOWED_PLANS, le serveur peut lire vos plans mais refuse d'enregistrer : c'est voulu.

4. Brancher le serveur sur votre assistant

Les exemples utilisent uvx. Pour Docker, remplacez la commande par :

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "KZ_TOKEN", "-e", "KZ_ALLOWED_PLANS",
         "-v", "kazaplan-data:/data", "ghcr.io/padupuy/kazaplan-mcp"]

claude mcp add kazaplan --scope user \
  -e KZ_TOKEN="$KZ_TOKEN" -e KZ_ALLOWED_PLANS="22222222" \
  -- uvx --from git+https://github.com/padupuy/kazaplan-mcp kazaplan-mcp

{
  "mcpServers": {
    "kazaplan": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/padupuy/kazaplan-mcp", "kazaplan-mcp"],
      "env": { "KZ_TOKEN": "collez-votre-jeton-ici", "KZ_ALLOWED_PLANS": "22222222" }
    }
  }
}

[mcp_servers.kazaplan]
command = "uvx"
args = ["--from", "git+https://github.com/padupuy/kazaplan-mcp", "kazaplan-mcp"]
env = { KZ_TOKEN = "collez-votre-jeton-ici", KZ_ALLOWED_PLANS = "22222222" }

gemini extensions install https://github.com/padupuy/kazaplan-mcp

{
  "mcpServers": {
    "kazaplan": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/padupuy/kazaplan-mcp", "kazaplan-mcp"],
      "env": { "KZ_TOKEN": "collez-votre-jeton-ici", "KZ_ALLOWED_PLANS": "22222222" }
    }
  }
}

{
  "inputs": [{ "id": "kz-token", "type": "promptString", "description": "Jeton Kazaplan", "password": true }],
  "servers": {
    "kazaplan": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/padupuy/kazaplan-mcp", "kazaplan-mcp"],
      "env": { "KZ_TOKEN": "${input:kz-token}", "KZ_ALLOWED_PLANS": "22222222" }
    }
  }
}

5. Installer les skills

Les skills apprennent à l'assistant à s'en servir comme un décorateur ou un dessinateur : relevé de la pièce, identité décorative de la maison (DECOR.md : foyer, palette 60 / 30 / 10, matières, programme par pièce), règles d'ergonomie et de circulation, validation avant de poser, planches d'architecte en fin de projet.

6. Utilisation

Parlez normalement à l'assistant :

1. « Ouvre mon plan 22222222 et fais-moi un résumé des pièces. »
2. « Trouve une baignoire de moins de 175 cm et pose-la dans la salle de bain. »
3. « Carrelage blanc 60×60 au sol du WC. »
4. « Décore la chambre 1 » : sol, murs, lumière, tapis, textiles, miroir, déco ; l'assistant présente le projet et attend votre accord avant de poser quoi que ce soit.
5. « Enregistre. »

Puis rechargez la page du planner pour voir le résultat. Rien n'est envoyé tant que vous n'avez pas demandé d'enregistrer.

Les murs, ouvertures et pièces neufs se finalisent dans le planner : après l'enregistrement, rechargez-le et enregistrez depuis le planner (il détecte alors les pièces fermées), puis demandez de nommer les nouvelles pièces.

Les outils

Toutes les cotes sont en centimètres. Sans jeton, on peut travailler sur un .kzp local : « ouvre ~/Downloads/mon-plan.kzp » puis « enregistre dans ~/Downloads/mon-plan-modifie.kzp ».

7. Sécurité et sauvegardes

• Liste blanche : le serveur n'enregistre en ligne que les plans de KZ_ALLOWED_PLANS.
• Sauvegardes automatiques dans backups/ du dossier de données : <plan>-<date>-orig.kzp (à l'ouverture), <plan>-<date>-sent.kzp (ce qui a été envoyé). Pour revenir en arrière : « ouvre le fichier …-orig.kzp et enregistre-le sur le plan 22222222 ».
• Le jeton n'est jamais écrit sur disque par le serveur.
• Les fichiers écrits à la demande de l'assistant sont limités : .kzp pour kz_save, .svg pour kz_sketch, dossier du DECOR.md pour kz_board.

8. Dépannage

9. Développement

src/kazaplan_mcp/
  kzp.py         conteneur .kzp (WPRJ)
  catalog.py     téléchargement du catalogue, index local, recherche
  geometry.py    géométrie 2D
  plan.py        modèle du plan : résumé, géométrie des pièces, placement, construction
  circulation.py contrôle de circulation
  sketch.py      plans SVG, livrable PLANCHES.md
  section.py     coupes des pièces ; mesh.py : modèles 3D .glb rendus au trait
  api.py         API Kazaplan, sauvegardes ; paths.py : dossier de données
  server.py      serveur MCP (outils kz_*) et CLI
skills/          skills Agent Skills
tests/           tests (plan synthétique, catalogue simulé)
HANDOFF.md       notes techniques : format .kzp, conventions vérifiées, règles du planner

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/python -m pytest -q

Pour essayer le plugin Claude Code depuis le dépôt : claude --plugin-dir ..

Inspecter un plan :

python -m kazaplan_mcp.kzp unpack plan.kzp dossier/   # → metadata.json, project.json
python -m kazaplan_mcp.kzp pack dossier/ nouveau.kzp

Publication : un tag v* publie le paquet sur PyPI (release.yml, trusted publishing) et l'image ghcr.io/padupuy/kazaplan-mcp (docker.yml, aussi edge à chaque push sur main).

Licence

MIT. Leroy Merlin et Kazaplan sont des marques de leurs propriétaires respectifs.