mcp-freecad

🛠️ Integración MCP-FreeCAD

Nota: Este repositorio se encuentra en desarrollo intensivo. Se esperan confirmaciones diarias y posibles cambios importantes.

Este proyecto proporciona una sólida integración entre los asistentes de IA y el software CAD FreeCAD mediante el Protocolo de Contexto de Modelo (MCP) . Permite que las aplicaciones externas interactúen con FreeCAD a través de una interfaz estandarizada, ofreciendo múltiples métodos de conexión y herramientas especializadas.

Inicio rápido (recomendado: AppImage + Launcher)

Para una configuración más confiable, siga estos pasos:

1. Configuración del entorno (única) : Ejecute el script de configuración. Esto clona el repositorio en ~/.mcp-freecad , crea un entorno virtual de Python, descarga la última versión estable de FreeCAD AppImage, la extrae y configura el servidor para usarla.
   curl -sSL https://raw.githubusercontent.com/jango-blockchained/mcp-freecad/main/scripts/bin/setup_freecad_env.sh | bash
   Alternativamente, clone el repositorio y ejecute ./scripts/bin/setup_freecad_env.sh manualmente.
2. Ejecutar el servidor MCP : use el script de instalación (que ahora solo garantiza que venv esté activo y ejecute el servidor) o el comando global si está instalado.
   # Option A: Run via the installer script in the default location ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh # Option B: Run the global command (if installed via install-global.sh) mcp-freecad

Esto inicia el servidor MCP usando el método launcher recomendado con la AppImage descargada y extraída.

Soporte de Docker

También puede ejecutar MCP-FreeCAD en un contenedor Docker para facilitar la implementación y el aislamiento.

Ejecutar con Docker Compose

1. Iniciar el contenedor :
   docker compose up
2. Construir desde cero (si ha realizado cambios):
   docker compose build --no-cache docker compose up

El contenedor Docker expone los siguientes puertos:

• 8080: Servidor MCP
• 12345: Servidor FreeCAD

Configuración de Docker

La configuración de Docker consta de:

• Dockerfile : define el contenedor con Python 3.12, instala dependencias y configura el entorno.
• docker-compose.yml : configura el servicio, los puertos, los volúmenes y las políticas de reinicio
• .dockerignore : excluye archivos innecesarios del contenedor

Este enfoque es especialmente útil para las canalizaciones CI/CD o cuando necesita aislar el entorno MCP-FreeCAD de su sistema.

Diagrama de flujo MCP

Este diagrama de flujo muestra los componentes principales y cómo los diferentes métodos de conexión seleccionados por freecad_connection_manager.py permiten ejecutar comandos de diversas maneras en FreeCAD. El método launcher , que suele usarse con AppImages extraídas mediante AppRun , es el enfoque recomendado para mayor fiabilidad.

Para obtener diagramas de flujo más detallados, consulte FLOWCHART.md .

🔄 Componentes principales

1. Servidor MCP de FreeCAD ( freecad_mcp_server.py )

• Descripción : El servidor principal que implementa el Protocolo de Contexto de Modelo. Actúa como el centro de conexión para que los asistentes de IA u otros clientes se comuniquen con FreeCAD mediante MCP.
• Características :
  • Maneja solicitudes MCP estándar ( mcp/listTools , mcp/executeTool ).
  • Utiliza FreeCADConnection para interactuar con FreeCAD utilizando el método configurado.
  • Expone varios conjuntos de herramientas (primitivas, manipulación, exportación, etc.) según la configuración.
  • Configurable a través de config.json .
• Uso :
  # Start the server (uses config.json by default) python src/mcp_freecad/server/freecad_mcp_server.py # Start with a specific config python src/mcp_freecad/server/freecad_mcp_server.py --config my_config.json

2. Conexión a FreeCAD ( src/mcp_freecad/freecad_connection_manager.py )

• Descripción : Una interfaz unificada de Python que encapsula la lógica para la conexión a FreeCAD. Utilizada internamente por el servidor MCP y disponible para scripting directo.
• Características :
  • Selecciona inteligentemente el mejor método de conexión según la configuración y la disponibilidad.
• Métodos :
  • Lanzador : (recomendado) utiliza freecad_connection_launcher.py y AppRun .
  • Envoltorio : utiliza freecad_connection_wrapper.py y freecad_subprocess.py .
  • Servidor : se conecta a un freecad_socket_server.py en ejecución a través de sockets.
  • Puente : utiliza la CLI de FreeCAD a través de freecad_connection_bridge.py .
  • Mock : simula FreeCAD para pruebas.
  • Automático : prueba los métodos en el orden recomendado (lanzador > contenedor > servidor > puente > simulacro).
• Uso (ejemplo de scripting directo) :
  from freecad_connection_manager import FreeCADConnection # Auto-connect using settings potentially from config.json # (Ensure config.json is present or provide args) fc = FreeCADConnection(auto_connect=True) if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}") version_info = fc.get_version() print(f"FreeCAD Version: {version_info}") fc.create_document("TestDocFromScript") else: print("Failed to connect to FreeCAD.")

3. Lanzador de FreeCAD ( freecad_connection_launcher.py )

• Descripción : Gestiona el inicio del entorno de FreeCAD, generalmente mediante AppRun desde una AppImage extraída. Ejecuta freecad_launcher_script.py dentro del entorno iniciado.
• Características :
  • Gestiona la ejecución del subproceso de FreeCAD/AppRun.
  • Pasa comandos y parámetros al script interno de FreeCAD.
  • Analiza los resultados JSON de la salida del script.
• Uso : FreeCADConnection lo utiliza principalmente internamente al seleccionar el método launcher (configurado en config.json ). Normalmente, el usuario no lo ejecuta directamente.

4. Envoltorio de FreeCAD ( freecad_connection_wrapper.py ) y subproceso ( freecad_subprocess.py )

• Descripción : freecad_connection_wrapper.py inicia freecad_subprocess.py en un proceso de Python separado. freecad_subprocess.py importa módulos de FreeCAD y se comunica con el contenedor a través de tuberías stdio.
• Características :
  • Aísla las importaciones del módulo FreeCAD en un proceso dedicado.
  • Proporciona un método de conexión alternativo si las importaciones directas de módulos son posibles pero AppRun/launcher es problemático.
• Uso : FreeCADConnection lo utiliza internamente cuando se selecciona el método wrapper (configurado en config.json ). Requiere un entorno Python donde el subproceso pueda import FreeCAD correctamente.

5. Servidor FreeCAD ( freecad_socket_server.py )

• Descripción : Un servidor de sockets independiente diseñado para ejecutarse dentro de una instancia de FreeCAD. Escucha las conexiones de FreeCADConnection .
• Características :
  • Permite la conexión a una instancia de FreeCAD potencialmente persistente.
  • Puede interactuar con la GUI si se ejecuta en modo --connect .
• Uso (Inicio manual dentro de FreeCAD) :
  # Inside FreeCAD Python Console: exec(open("/path/to/mcp-freecad/freecad_socket_server.py").read())
  Requiere connection_method: server en config.json para que el servidor MCP se conecte. (Consulte docs/FREECAD_SERVER_SETUP.md )

6. Puente de FreeCAD ( freecad_connection_bridge.py )

• Descripción : Permite la interacción mediante la línea de comandos con el ejecutable de FreeCAD. Evita los problemas de importación directa de módulos, pero puede ser más lento.
• Características :
  • Ejecuta comandos de FreeCAD mediante llamadas de subproceso al ejecutable de freecad .
• Uso : FreeCADConnection lo utiliza internamente cuando se selecciona el método bridge (configurado en config.json ). Requiere que freecad esté en la ruta del sistema o que la path esté configurada correctamente en la configuración.

7. Cliente de FreeCAD ( freecad_client.py )

• Descripción : Una utilidad de línea de comandos para interactuar directamente con la interfaz FreeCADConnection (para probar/depurar métodos de conexión, no el servidor MCP).
• Características :
  • Permite probar comandos específicos FreeCADConnection (por ejemplo, crear primitivos, obtener versión) desde la terminal.
  • Utiliza config.json para determinar la configuración de conexión.
• Ejemplos de uso :
  # Test connection and get version python freecad_client.py version # Create a box using the configured connection method python freecad_client.py create-box --length 20 --width 10

🔄 Estructura del proyecto

El proyecto MCP-FreeCAD está organizado con la siguiente estructura de directorios:

Para obtener más detalles sobre los scripts, consulte scripts/README.md .

⚙️ Detalles de instalación y configuración

Esta sección proporciona más detalles sobre las diferentes opciones de instalación y configuración.

Configuración recomendada: AppImage + Launcher (pasos detallados)

Esto implica dos scripts principales:

1. scripts/bin/setup_freecad_env.sh : prepara el entorno.
   • Clona o actualiza el repositorio a ~/.mcp-freecad .
   • Crea/actualiza un entorno virtual de Python ( .venv ) e instala los requisitos.
   • Ejecuta download_appimage.py para obtener la última AppImage estable de FreeCAD Linux en ~/.mcp-freecad .
   • Ejecuta extract_appimage.py que:
     • Extrae la AppImage descargada a ~/.mcp-freecad/squashfs-root .
     • Actualiza ~/.mcp-freecad/config.json para usar connection_method: launcher y use_apprun: true con rutas absolutas correctas.
   • Cómo ejecutar : curl -sSL <URL>/setup_freecad_env.sh | bash o ./scripts/bin/setup_freecad_env.sh
2. scripts/bin/mcp-freecad-installer.sh : ejecuta el servidor.
   • Nota : A pesar del nombre, este script ya no realiza la instalación completa . Principalmente, garantiza la actualización del repositorio, activa el entorno virtual e inicia freecad_mcp_server.py .
   • Se asume que el entorno (descarga/extracción de AppImage) ha sido preparado por setup_freecad_env.sh o manualmente.
   • Cómo ejecutar : ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh o mcp-freecad (comando global).

Otros métodos de instalación

Instalación global ( install-global.sh )

• Crea un enlace simbólico mcp-freecad en /usr/local/bin que apunta a mcp-freecad-installer.sh en el repositorio.
• Permite ejecutar mcp-freecad desde cualquier lugar.
• Requiere que el entorno se configure primero usando setup_freecad_env.sh si desea utilizar el método de inicio recomendado.

Instalación manual

• Clonar el repositorio.
• Crear venv, instalar requisitos.
• Descargue y extraiga AppImage manualmente : ejecute python download_appimage.py y python extract_appimage.py /path/to/downloaded.AppImage usted mismo.
• Ejecute el servidor: python freecad_mcp_server.py .

🚀 Uso del servidor MCP

Esta es la forma principal de interactuar con FreeCAD utilizando asistentes de IA como Claude.

Iniciando el servidor MCP

El servidor se ejecutará y escuchará las conexiones de los clientes MCP.

Conexión de un cliente MCP

Utilice cualquier cliente compatible con MCP. Ejemplo con el mcp client de referencia:

O usar uv si tienes un script de cliente como el que se encuentra en los documentos de MCP:

Alternativa: iniciar FreeCAD con el servidor integrado

También puedes iniciar FreeCAD con el servidor integrado usando:

Esto iniciará FreeCAD y automáticamente iniciará el servidor dentro de él.

Configuración del servidor MCP ( config.json )

El archivo config.json controla varios aspectos del servidor. A continuación, se muestra un ejemplo que refleja la configuración recomendada del lanzador tras ejecutar extract_appimage.py :

Nota: reemplace las rutas de ejemplo con sus rutas absolutas reales.

Consulte FREECAD_INTEGRATION.md para obtener más detalles sobre las opciones de integración.

🛠️ Herramientas MCP disponibles

El servidor MCP actualmente expone las siguientes herramientas principales. Se planean conjuntos de herramientas adicionales.

• freecad.create_document : Crea un nuevo documento.
• freecad.list_documents : enumera todos los documentos abiertos.
• freecad.list_objects : enumera objetos en un documento específico (o uno activo).
• freecad.create_box : Crea un cuadro primitivo.
• freecad.create_cylinder : Crea un cilindro primitivo.
• freecad.create_sphere : Crea una esfera primitiva.
• freecad.create_cone : Crea un cono primitivo.
• freecad.boolean_union : Realiza una unión booleana (fusión) entre dos objetos.
• freecad.boolean_cut : Realiza un corte booleano (diferencia) entre dos objetos.
• freecad.boolean_intersection : Realiza una intersección booleana (común) entre dos objetos.
• freecad.move_object : Mover un objeto a una nueva posición absoluta.
• freecad.rotate_object : rota un objeto según ángulos especificados.
• freecad.export_stl : exporta objetos especificados (o todos) a un archivo STL.

(Nota: Los nombres de las herramientas utilizadas en las solicitudes de MCP pueden diferir levemente, por ejemplo, se utilizan guiones bajos en lugar de puntos, según los detalles de implementación del cliente y del servidor. Consulte la salida mcp/listTools del servidor para conocer los nombres exactos).

📝 Ejemplos de interacciones MCP

A continuación se muestran ejemplos conceptuales del uso del servidor MCP con un asistente de IA:

Creación y exportación de un cuadro

🔍 Solución de problemas

• Problemas de conexión al servidor MCP :
  • Asegúrese de que python src/mcp_freecad/server/freecad_mcp_server.py pueda ejecutarse sin errores inmediatos. Verifique la salida de la terminal.
  • Verifique la configuración del firewall si es relevante (poco probable para stdio ).
  • Verifique que config.json sea JSON válido.
• Problemas de conexión de FreeCAD (especialmente con el método launcher ) :
  • Ejecutar extract_appimage.py : asegúrese de que AppImage se haya extraído correctamente y de config.json se haya actualizado.
  • Verificar las rutas config.json : verifique que todas las rutas absolutas en la sección freecad sean correctas para su sistema.
  • Comprobar permisos : asegúrese de que squashfs-root/AppRun tenga permisos de ejecución ( chmod +x ).
  • Verificar registros : examine mcp_freecad.log (creado en la raíz del proyecto si se inicia el registro), freecad_server_stdout.log y freecad_server_stderr.log en busca de errores de freecad_connection_launcher.py , AppRun o el propio proceso de FreeCAD.
  • Variables de entorno : Si AppRun no encuentra bibliotecas, asegúrese de que LD_LIBRARY_PATH y PYTHONPATH estén correctamente configuradas, posiblemente dentro de .cursor/mcp.json si usa Cursor, o exportadas manualmente si prueba en la terminal. El script extract_appimage.py intenta que esto sea menos necesario, pero puede ser un factor.
  • Problemas de funcionamiento sin interfaz gráfica : FreeCAD a veces presenta problemas al ejecutarse completamente sin interfaz gráfica ( QT_QPA_PLATFORM=offscreen ). Revise los registros para detectar errores relacionados con la interfaz gráfica.
• Método server : asegúrese de que freecad_socket_server.py se esté ejecutando dentro de una instancia activa de FreeCAD, escuchando en el host/puerto correcto configurado en config.json .
• Método bridge : Verifique que FreeCAD esté instalado en todo el sistema y que el comando freecad funcione en su terminal. Verifique freecad_path en config.json .
• SDK de MCP faltante : instalar mediante pip install modelcontextprotocol .
• Problemas de ruta de Python : si no se encuentran los módulos de FreeCAD cuando no se utiliza la configuración recomendada de AppImage, consulte PYTHON_INTERPRETER_SETUP.md .

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

🖥️ Integración del cursor

El servidor MCP está diseñado para la integración con herramientas como Cursor IDE.

1. Configurar Cursor : Agregue el servidor MCP en la configuración de Cursor (Configuración > Características > Servidores MCP > Agregar nuevo servidor MCP). Configúrelo para que ejecute el script de Python directamente, configurando las variables de entorno y el directorio de trabajo necesarios. Un ejemplo de configuración en .cursor/mcp.json sería el siguiente:
   { "mcpServers": { "mcp-freecad": { "command": "python3", // Command to run python "args": [ "src/mcp_freecad/server/freecad_mcp_server.py" // Corrected script path ], "env": { // Environment variables needed for headless AppRun "QT_QPA_PLATFORM": "offscreen", "DISPLAY": "", "FREECAD_CONSOLE": "1", "PYTHONNOUSERSITE": "1", // These might be needed if AppRun doesn't set them automatically "LD_LIBRARY_PATH": "/path/to/mcp-freecad/squashfs-root/usr/lib:/path/to/mcp-freecad/squashfs-root/usr/Ext:...", "PYTHONPATH": "/path/to/mcp-freecad/squashfs-root/usr/lib/python3.11/site-packages:..." }, "cwd": "/path/to/mcp-freecad" // Set working directory to project root } // ... other servers like memory ... } }
   Reemplace /path/to/mcp-freecad con la ruta absoluta de su proyecto. Asegúrese de que LD_LIBRARY_PATH y PYTHONPATH coincidan con la estructura de AppImage si es necesario.
2. Reiniciar el cursor : reinicie completamente el cursor para que los cambios de configuración surtan efecto.
3. Comunicación con el servidor : El servidor utiliza el transporte stdio por defecto (configurado en config.json , en server.mcp.transport ), compatible con el protocolo de comunicación de Cursor. Los errores deben reportarse a Cursor mediante respuestas de error de MCP.

Consideraciones específicas del cursor

• El script freecad_mcp_server.py carga config.json por defecto. Asegúrese de que este archivo contenga la configuración correcta, especialmente la sección freecad actualizada por extract_appimage.py .
• Las variables de entorno establecidas en .cursor/mcp.json son cruciales para permitir que el método launcher funcione correctamente dentro del entorno que proporciona Cursor.

📋 Opciones disponibles y casos de uso

🔧 Métodos de conexión

1. Conexión del lanzador (recomendado)
   • Utiliza AppRun desde una AppImage extraída. Es la opción más fiable.
   • Configurado automáticamente por extract_appimage.py .
   • Configuración ( config.json ): GXP19
2. Conexión de envoltura
   • Ejecuta la lógica de FreeCAD en un subproceso independiente de Python. Una buena alternativa si AppImage/AppRun causa problemas.
   • Configuración ( config.json ): GXP20
3. Conexión al servidor de sockets
   • Requiere ejecutar freecad_socket_server.py dentro de FreeCAD.
   • Úselo cuando se ejecuta FreeCAD como un servidor en segundo plano persistente.
   • Configuración ( config.json ): GXP21
4. Conexión de puente CLI
   • Utiliza la herramienta de línea de comandos freecad . Puede ser más lento o menos fiable.
   • Configuración ( config.json ): GXP22
5. Conexión simulada
   • Para probar sin FreeCAD.
   • Configuración ( config.json ): GXP23
6. Conexión automática
   • Selecciona automáticamente el mejor método disponible (lanzador > contenedor > servidor > puente > simulacro).
   • Predeterminado si falta connection_method o está configurado en "auto" .

🛠️ Categorías de herramientas y casos de uso

1. Operaciones básicas de FreeCAD
   • Gestión esencial de documentos
   • Casos de uso:
     • Creación de nuevos documentos
     • Guardar y cargar proyectos
     • Exportación a varios formatos
     • Gestión de la estructura del documento
2. Manipulación de modelos
   • Transformar y modificar objetos
   • Casos de uso:
     • Rotar objetos con precisión
     • Objetos en movimiento en el espacio 3D
     • Modelos de escala
     • Creación de espejos y copias
     • Operaciones booleanas (unión, corte, intersección)
3. Herramientas de medición
   • Análisis y verificación
   • Casos de uso:
     • Mediciones de distancia
     • Cálculos de ángulos
     • Análisis del área de superficie
     • Cálculos de volumen
     • Propiedades de la masa
4. Creación primitiva
   • Generación de formas básicas
   • Casos de uso:
     • Creación de cajas y cilindros
     • Generando esferas
     • Fabricación de conos y toros
     • Creación de polígonos regulares
     • Dibujar elipses
5. Operaciones de Exportación/Importación
   • Conversión de formatos de archivo
   • Casos de uso:
     • Exportación/importación de archivos STEP
     • Manejo del formato IGES
     • Procesamiento de archivos DXF
     • Exportación STL para impresión 3D
6. Generación de código
   • Creación automatizada de código
   • Casos de uso:
     • Generación de scripts de Python
     • Exportación de código OpenSCAD
     • Generación de código G para CNC
     • Optimización de la configuración de la impresora 3D

💻 Escenarios de integración

1. Integración de Cursor IDE
   • Integración del entorno de desarrollo
   • Casos de uso:
     • Manipulación directa del modelo desde el IDE
     • Retroalimentación en tiempo real
     • Registro de depuración
     • Seguimiento de errores
2. Integración del asistente de IA
   • Automatización del diseño impulsada por IA
   • Casos de uso:
     • Creación de modelos de lenguaje natural
     • Modificaciones de diseño automatizadas
     • Optimización de parámetros
     • Validación del diseño
3. Uso de la línea de comandos
   • Scripting y automatización
   • Casos de uso:
     • Procesamiento por lotes
     • Pruebas automatizadas
     • Integración CI/CD
     • Herramientas de línea de comandos

Ejemplos de casos de uso comunes

1. Prototipado rápido

2. Procesamiento automatizado

⚙️ Opciones de configuración

1. Configuración del servidor

2. Habilitación de herramientas

3. Configuración de depuración

Características

• Conecte asistentes de IA a FreeCAD a través del protocolo MCP
• Crear y manipular modelos 3D mediante programación
• Soporte para formas primitivas (caja, cilindro, esfera, cono)
• Operaciones booleanas (unión, intersección, corte)
• Transformaciones de objetos (mover, rotar)
• Exportar modelos a formato STL
• Gestión de documentos y objetos

Prerrequisitos

• Python 3.8 o más reciente
• Recomendado : una imagen de aplicación FreeCAD (descargada y extraída mediante scripts/bin/setup_freecad_env.sh ) para el método de conexión launcher confiable.
• Alternativamente : una instalación del sistema de FreeCAD 0.20+ (para métodos bridge o server , potencialmente menos confiable).
• Git (para clonar el repositorio).

Las dependencias se administran a través de pyproject.toml y se instalan en el entorno virtual durante la configuración.

Herramientas disponibles

(Esta sección duplica la lista anterior, consolidándola para mayor claridad)

Las herramientas actualmente implementadas disponibles a través de MCP son:

Gestión de documentos

• freecad.create_document
• freecad.list_documents
• freecad.list_objects

Primitivas 3D

• freecad.create_box
• freecad.create_cylinder
• freecad.create_sphere
• freecad.create_cone

Operaciones booleanas

• freecad.boolean_union
• freecad.boolean_cut
• freecad.boolean_intersection

Transformaciones

• freecad.move_object
• freecad.rotate_object

Exportar

• freecad.export_stl

Se planean para futuras versiones herramientas adicionales que cubran mediciones, otros formatos de importación/exportación y generación de código.

Pruebas

El proyecto incluye pruebas de extremo a extremo (E2E) para verificar la funcionalidad del sistema.

Pruebas de extremo a extremo

Estas pruebas verifican las interacciones desde la perspectiva del cliente utilizando el protocolo MCP.

Para ejecutar todas las pruebas E2E:

Las pruebas E2E se encuentran en el directorio tests/e2e/ y están organizadas por funcionalidad.

Escritura de nuevas pruebas E2E

Para agregar nuevas pruebas E2E:

1. Cree un nuevo archivo de prueba en el directorio tests/e2e/
2. Amplíe la clase de prueba base adecuada ( MCPClientTestBase )
3. Agregue métodos de prueba que utilicen el cliente MCP para interactuar con las herramientas
4. Ejecute sus pruebas con el ejecutor de pruebas

Consulte los archivos de prueba existentes para ver ejemplos.

Documentación

El proyecto incluye varios archivos de documentación para diferentes aspectos:

• PYTHON_INTERPRETER_SETUP.md - Cómo configurar el intérprete de Python
• FREECAD_SERVER_SETUP.md - Guía de configuración del servidor
• FREECAD_INTEGRATION.md - Métodos de integración de FreeCAD
• FLOWCHART.md - Diagramas de flujo detallados
• OPTIMIZATION_FEATURES.md - Guía de optimización del rendimiento
• scripts/README.md - Documentación de scripts

Para los asistentes de IA, consulte AI_ASSISTANT_GUIDE.md para obtener instrucciones de uso detalladas y ejemplos.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Expresiones de gratitud

• Equipo de desarrollo de FreeCAD para el increíble software CAD
• Anthropic y Claude para el SDK del Protocolo de Contexto de Modelo (MCP)