Jump to content

Atelier Robust MCP Bridge

From FreeCAD Documentation
This page is a translated version of the page Robust MCP Bridge Workbench and the translation is 100% complete.
Icône de l'atelier Robust MCP Bridge

Description

L'atelier Robust MCP Bridge relie FreeCAD au Robust MCP Server. Ensemble, ils permettent aux applications compatibles de contrôler FreeCAD via le Model Context Protocol (MCP). L'atelier s'exécute au sein de FreeCAD ; le serveur MCP, installé séparément, s'y connecte via un pont XML-RPC ou JSON-RPC local authentifié.

Cet atelier est conçu pour fonctionner avec le Robust MCP Server (disponible sur PyPI), qui permet à des assistants IA tels que Claude d'interagir avec FreeCAD via un langage naturel. La documentation complète et le code source sont disponibles sur dépôt GitHub, où vous trouverez le serveur MCP, Bridge et certaines macros FreeCAD utilisées à diverses fins, pas nécessairement liées à l'IA ou au travail MCP.

Principales fonctions :

  • Barre d'outils pour démarrer/arrêter le pont MCP.
  • Indicateur d'état affichant l'état du pont, avec la version et les détails relatifs au listener dans son info-bulle.
  • Serveur XML-RPC sur un port configurable (par défaut : 9875).
  • Serveur socket JSON-RPC sur port configurable (par défaut : 9876).
  • Prise en charge du mode sans affichage pour l'automatisation et les pipelines CI/CD.
  • Système de file d'attente thread-safe garantissant la sécurité des opérations FreeCAD.
  • Démarrage automatique configurable au lancement de FreeCAD.

Le serveur MCP fournit également des outils pour la modélisation paramétrique, les esquisses, les feuilles de calcul, la rédaction de texte, l'importation et l'exportation de fichiers, ainsi que des flux de travail FAO tels que la création de tâches, la génération de parcours d'outils et la production de G-code. Les opérations FAO disponibles dépendent de la version de FreeCAD et de la présence ou non de l'interface graphique. Voir la référence des outils pour obtenir la liste complète et plus de détails.

Installation

FreeCAD 1.0.2 ou une version plus récente est requis. FreeCAD 1.1.4 ou une version plus récente est recommandé, car il inclut des correctifs de sécurité.

Via le gestionnaire d'extensions (recommandé)

Disponibilité : l'atelier a été soumis à l'index des extensions de FreeCAD, mais il se peut qu'il ne soit pas encore disponible dans le catalogue public du gestionnaire des extensions. En attendant qu'il y figure, utilisez la procédure d'installation manuelle à partir des versions GitHub décrite ci-dessous.

  1. Lancez FreeCAD.
  2. Allez dans Outils → Gestionnaire d'extensions.
  3. Recherchez « Robust MCP Bridge ».
  4. Cliquez sur Installer.
  5. Redémarrez FreeCAD.

Installation manuelle

Téléchargez l'archive ZIP ou .tar.gz de la version stable de l'atelier à partir de la page versions de l'atelier.

  1. Quittez FreeCAD.
  2. Repérez le répertoire Mod dans le profil FreeCAD que vous utilisez. Pour trouver le profil actif, ouvrez la console Python de FreeCAD et exécutez App.getUserAppDataDir(), puis quittez à nouveau FreeCAD.
  3. Déplacez toute ancienne copie de l'atelier « Robust MCP Bridge » hors du répertoire Mod de ce profil.
  4. Extrayez l'archive et copiez son répertoire de paquets de niveau supérieur dans Mod. Ne copiez pas uniquement le répertoire interne freecad ou RobustMCPBridge.
  5. Redémarrez FreeCAD.

Le répertoire du paquet extrait doit contenir directement les fichiers package.xml et freecad/RobustMCPBridge/. Répétez la procédure d'installation pour chaque profil FreeCAD que vous comptez utiliser.

Utilisation

Mode interface utilisateur

Barre d'outils de l'atelier Robust MCP Bridge

  1. Installez et associez le serveur MCP et l'atelier comme décrit dans Connexion des clients MCP.
  2. Passez à l'atelier Robust MCP Bridge à l'aide du sélecteur d'ateliers.
  3. Cliquez sur Démarrer Bridge dans la barre d'outils.
  4. Vérifiez l'état de Bridge dans la barre d'état de FreeCAD. Son info-bulle indique la version du pont et les détails du listener.
  5. Lancez votre client MCP ou votre assistant configuré.

Pour arrêter le bridge, cliquez sur Stop Bridge dans la barre d'outils.

Barre d'état de l'atelier Robust MCP Bridge

Mode sans affichage

Pour l'automatisation et le CI/CD, le bridge peut fonctionner sans interface graphique. Commencez par l'appairer, puis suivez les instructions relatives au mode de connexion correspondant à votre plateforme.

Le chemin de démarrage dépend du profil FreeCAD actif et de la manière dont le Workbench a été installé. Utilisez App.getUserAppDataDir() dans la console Python de FreeCAD pour identifier le profil ; ne partez pas du principe que son répertoire s'appelle v1-2.

Configuration

Accédez aux préférences via Édition → Préférences → Robust MCP Bridge ou Robust MCP Bridge → MCP Bridge Preferences....

Paramètre Description Par défaut
Démarrage automatique du bridge au lancement de l'interface graphique de FreeCAD Démarre automatiquement le bridge dans l'interface graphique de FreeCAD Désactivé
Démarrage automatique dans la console FreeCAD Démarre automatiquement le bridge dans la console FreeCAD Désactivé
Démarrage automatique également lors des exécutions par lots en console Démarrer également le bridge lors des exécutions par lots en console ; nécessite le démarrage automatique de la console Désactivé
Afficher l'indicateur d'état Afficher l'état de la connexion dans la barre d'état de FreeCAD Activé
Port XML-RPC Port pour les connexions XML-RPC 9875
Port de socket Port pour les connexions JSON-RPC par socket 9876

Panneau des préférences de l'atelier Robust MCP Bridge

Fonctions par mode

Fonction Mode graphique Mode sans interface graphique
Gestion des documents et des objets Oui Oui
Formes 3D et opérations booléennes Oui Oui
Modélisation paramétrique, esquisses et contraintes Oui Oui
Tableurs et texte de Draft Oui Oui
Importation et exportation Oui Oui
Exécution de macros et de scripts Python Oui Oui
Tâches FAO, parcours d'outils et G-code Oui Pris en charge avec certaines limitations
Captures d'écran Oui Non
Couleurs et visibilité des objets Oui Non
Contrôle de la caméra et de la vue Oui Non

Les fonctions CAM varient selon la version de FreeCAD et le mode d'exécution. Certaines opérations nécessitent l'interface graphique, et certaines versions de FreeCAD présentent des limitations connues en mode sans interface graphique. Utilisez cam_get_capabilities pour vérifier les fonctions disponibles. Pour plus de détails, voir la référence des outils de CAM.

Connexion des clients MCP

L'atelier fournit le bridge de FreeCAD utilisé par le serveur Robust MCP, qui doit être installé séparément. Votre client MCP ou votre assistant IA se connecte au serveur MCP, lequel se connecte au pont associé. Installez le serveur à l'aide de la commande suivante :

pip install freecad-robust-mcp

Ou en utilisant uv :

uv tool install freecad-robust-mcp

Une fois les deux composants installés, exécutez la commande d'appairage en vous connectant sous le même compte utilisateur que celui utilisé pour exécuter FreeCAD :

freecad-mcp --pair-bridge

Si le compte est déjà associé, conservez les identifiants existants. Lancez FreeCAD, sélectionnez l'atelier Robust MCP Bridge et démarrez le bridge.

Configurez votre assistant pour qu'il lance freecad-mcp, puis vérifiez la connexion :

freecad-mcp --check --mode xmlrpc

Le guide d'installation contient des instructions pour Claude Desktop, Claude Code, Codex Desktop et l'interface CLI de Codex. La procédure d'installation est similaire pour les autres clients compatibles MCP.

Le bridge écoute sur la boucle de retour et nécessite un appairage. Un client appairé peut exécuter du code Python avec les droits de l'utilisateur de FreeCAD. L'appairage n'isole pas les programmes malveillants s'exécutant sous le même compte utilisateur du système d'exploitation.

Dépannage

Bridge ne démarre pas

  1. Vérifiez que l'appairage est bien terminé pour l'utilisateur du système d'exploitation qui exécute FreeCAD.
  2. Vérifiez la console Python de FreeCAD (Affichage → Panneaux → Console Python) pour voir s'il y a des messages d'erreur.
  3. Assurez-vous qu'aucun autre processus n'utilise les ports 9875/9876.
  4. Essayez de redémarrer FreeCAD.

Connexion refusée

  1. Vérifiez que FreeCAD et le bridge sont en cours d'exécution. Consultez l'indicateur d'état et son info-bulle pour connaître l'état du listener et les ports utilisés.
  2. Assurez-vous que le serveur MCP et le bridge utilisent les mêmes identifiants de couplage.
  3. Vérifiez que les ports correspondent bien entre les préférences de l'atelier et la configuration du serveur MCP.
  4. Exécutez freecad-mcp --check --mode xmlrpc.

Docker Desktop peut rediriger host.docker.internal vers un listener de bouclage hôte. Docker Engine sous Linux ne peut pas utiliser son adresse de passerelle hôte pour accéder à un pont réservé au bouclage hôte de la même manière ; pour une configuration avec interface graphique sous Linux, exécutez le serveur MCP directement sur l'hôte. Voir le guide des modes de connexion pour plus de détails.

Le mode sans affichage ne démarre pas

  1. Vérifiez que le bridge est bien appairé pour l'utilisateur du système d'exploitation qui exécute FreeCAD.
  2. Vérifiez que vous utilisez bien l'exécutable de la console FreeCAD et le script de démarrage adaptés à votre plateforme et à votre installation.
  3. Vérifiez que la sortie de la console ne contient pas d'erreurs, notamment des conflits de ports ou des échecs d'appairage.

Liens