Skip to main content
Glama
BricsCAD-MCP

BricsCAD-MCP

by samuelsl27
README.md
# BricsCAD-MCP

Servidor **MCP (Model Context Protocol)** para controlar **BricsCAD V25/V26** en
lenguaje natural desde Claude Desktop.

No existe un MCP oficial de Bricsys/Octave (confirmado en el foro oficial en
2025: *«There is no such a feature yet»*). Este proyecto parte del mejor servidor
libre disponible —[multiCAD-mcp](https://github.com/AnCode666/multiCAD-mcp),
Apache-2.0— y lo especializa en BricsCAD, añadiendo lo que a aquél le faltaba:
**ejecución de LISP arbitrario con retorno de valor**.

---

## Qué aporta frente al proyecto original

| | multiCAD-mcp | **BricsCAD-MCP** |
|---|---|---|
| CAD soportados | 4 (genérico) | BricsCAD V23–V26, especializado |
| Detección de ProgID | uno fijo | lista de candidatos versionados con sondeo |
| LISP arbitrario | ✗ | ✓ puente de ficheros con retorno de valor y captura de errores |
| Comandos nativos | solo internos | ✓ `send_command` y scripts `.scr` |
| Variables de sistema | ✗ | ✓ `GETVAR` / `SETVAR` por COM |
| Volcado DXF (`entget`) | ✗ | ✓ por handle |
| Deshacer agrupado | ✗ | ✓ cada operación LISP en un único grupo de UNDO |
| Diagnóstico de instalación | ✗ | ✓ `scripts/detect_bricscad.py` |
| Selección actual del usuario | ✗ | ✓ «a lo seleccionado…», sin destruir la selección |
| Inspección previa / resaltado | ✗ | ✓ `describe` y `highlight` antes de modificar |
| Textos de DXF de QGIS | ✗ | ✓ `text_height` quita el `\H` incrustado |
| Idioma | inglés | castellano |

---

## Arquitectura

```
Claude Desktop
      │  stdio (MCP)
      ▼
  src/server.py  ──────────────  FastMCP: 8 herramientas unificadas
      │
      ▼
  BricsCADAdapter  (mixins: dibujo, capas, bloques, entidades, export, LISP…)
      │
      ├─── COM  (BricscadApp.AcadApplication.25)  ──► BricsCAD V25
      │
      └─── Puente LISP  (ficheros .lsp / .res)   ──► intérprete LISP de BricsCAD
```

**El puente LISP** evita todos los problemas de escapado: el servidor escribe el
código en un `.lsp` temporal, envía `(mcp:run-file "código.lsp" "resultado.res")`
por `SendCommand`, y el puente `lisp/mcp_bridge.lsp` devuelve el valor —o el
mensaje de error— en el fichero de respuesta, que el servidor lee y convierte a
JSON. A diferencia de AutoCAD LT (que necesita trucos con `PostMessageW`),
BricsCAD completo expone `SendCommand` por COM y soporta LISP de forma nativa.

---

## Herramientas MCP

| Herramienta | Qué hace |
|---|---|
| `manage_session` | Conectar/desconectar, estado, zoom extensión, captura, deshacer/rehacer, panel web |
| `draw_entities` | Líneas, círculos, arcos, rectángulos, polilíneas, elipses, splines, textos, sombreados, cotas, directrices, tablas, matrices |
| `manage_layers` | Crear, listar, renombrar, borrar, encender/apagar, color, capa actual |
| `manage_files` | Nuevo, abrir, guardar (DWG/DXF/PDF), cerrar, cambiar entre dibujos |
| `manage_entities` | **Selección actual del usuario**, inspección, resaltado, **altura de texto (con limpieza de DXF de QGIS)**; mover, girar, escalar, copiar, borrar, propiedades; selección por tipo/capa/color |
| `manage_blocks` | Crear, insertar (individual y por lotes), listar, atributos |
| `export_data` | Extracción a JSON y Excel, depuración de entidades |
| **`execute_lisp`** | **LISP arbitrario, comandos nativos, scripts `.scr`, `GETVAR`/`SETVAR`, `entget`, purgar y auditar** |

Detalle completo en [`docs/03-HERRAMIENTAS.md`](docs/03-HERRAMIENTAS.md).

---

## Instalación

Requisitos: Windows 10/11, BricsCAD V23 o superior (probado en V25) y Python
3.10–3.14 (si solo hay uno más nuevo, el instalador consigue un 3.13 con `uv`).

Copia el repositorio a un **disco local** (sin la carpeta `.venv`) y haz doble
clic en **`INSTALAR.bat`**, o:

```powershell
cd C:\IMGA\MCP_Briccad
py install.py
```

El instalador elige un Python compatible, crea el entorno virtual (lo recrea si
viene copiado de otro equipo), instala las dependencias, **arranca el servidor
de prueba**, ejecuta el diagnóstico de BricsCAD y lo registra en
`claude_desktop_config.json` (ruta clásica o MSIX, con copia de seguridad y
conservando los servidores existentes).

Después: abre BricsCAD, reinicia Claude Desktop del todo y prueba con
*«conecta con BricsCAD y dime en qué dibujo estoy»*.

Pasos manuales y solución de problemas en
[`docs/01-INSTALACION.md`](docs/01-INSTALACION.md) y
[`docs/05-PROBLEMAS.md`](docs/05-PROBLEMAS.md). Auditoría de seguridad previa en
[`docs/06-SEGURIDAD.md`](docs/06-SEGURIDAD.md).

---

## Diagnóstico rápido

```powershell
.\.venv\Scripts\python.exe scripts\detect_bricscad.py
```

Muestra los ProgID registrados, las versiones instaladas y si hay una instancia
de BricsCAD accesible por COM.

---

## Ejemplos de uso

> «Crea la capa TALUDES en color rojo y dibuja en ella la polilínea que une
> 0,0 – 50,0 – 50,30 – 0,30 cerrada.»

> «Cuenta cuántas polilíneas hay en la capa BERMAS y dame la longitud total.»
> → resuelto con `execute_lisp`:
> ```lisp
> (setq ss (ssget "_X" '((0 . "LWPOLYLINE") (8 . "BERMAS"))))
> (setq tot 0.0 i 0)
> (if ss (repeat (sslength ss)
>   (setq e (vlax-ename->vla-object (ssname ss i)))
>   (setq tot (+ tot (vlax-curve-getDistAtParam e (vlax-curve-getEndParam e))))
>   (setq i (1+ i))))
> (list (if ss (sslength ss) 0) tot)
> ```

> «Purga y audita el dibujo, luego guárdalo como DWG en la carpeta del proyecto.»

> «A los textos que tengo seleccionados ponles altura 2,5.»
> → `current` (37 MTEXT en la capa DPH_parcela, altura 0,66) → confirma →
> `text_height|selection|2.5`: quita el `\H0.66053;` que trae el DXF de QGIS y
> fija la altura, todo en un solo UNDO.

---

## Seguridad

`execute_lisp` ejecuta código arbitrario dentro de BricsCAD, con los permisos del
usuario. Trátalo como lo que es: una consola de programación.

- El puente envuelve cada ejecución en un grupo de **DESHACER**, de modo que un
  único `UNDO` revierte la operación completa.
- Los errores de LISP se capturan con `vl-catch-all-apply`: BricsCAD nunca queda
  bloqueado en el diálogo de error.
- BricsCAD puede exigir que la carpeta del puente esté en las rutas de confianza
  (`TRUSTEDPATHS`); el instalador lo indica si hace falta.
- El servidor solo habla por *stdio* con Claude Desktop y **no abre ninguna
  conexión de red**: el panel web viene desactivado y no se hace ni una petición
  fuera de `127.0.0.1`.
- Por defecto no mueve el ratón ni escribe fuera de la carpeta de exportación.

El árbol completo se auditó antes de la primera ejecución —sin `eval`, sin
subprocesos, sin red saliente, sin ofuscación— y se endurecieron cuatro valores
por defecto. El detalle, en [`docs/06-SEGURIDAD.md`](docs/06-SEGURIDAD.md).

---

## Desarrollo

Este proyecto se desarrolla con **Spec-Driven Development**: primero la
especificación, después el código, y el código se valida contra ella.

| Documento | Qué contiene |
|---|---|
| [`DESARROLLO.md`](DESARROLLO.md) | Bitácora: cómo se construyó, los diez problemas que aparecieron y cómo se resolvieron, y un **prompt reutilizable para instalarlo en otro equipo** |
| [`AGENTS.md`](AGENTS.md) | Contexto para agentes de IA: mapa del repositorio y reglas que no se negocian |
| [`docs/constitution.md`](docs/constitution.md) | Los ocho principios del proyecto |
| [`docs/sdd/README.md`](docs/sdd/README.md) | La metodología, la notación EARS y el ciclo de trabajo |
| [`docs/sdd/PROMPTS.md`](docs/sdd/PROMPTS.md) | Prompts listos para cada fase |
| [`specs/`](specs/) | Una carpeta por funcionalidad: `spec.md`, `plan.md`, `tasks.md` |

Especificaciones actuales:

- [`001-mcp-bricscad-mvp`](specs/001-mcp-bricscad-mvp/spec.md) — Implementada
- [`002-seleccion-actual`](specs/002-seleccion-actual/spec.md) — Acordada, pendiente

Flujo de ramas y convención de commits en
[`docs/04-DESARROLLO.md`](docs/04-DESARROLLO.md).

---

## Licencia y atribución

Apache-2.0. Obra derivada de
[AnCode666/multiCAD-mcp](https://github.com/AnCode666/multiCAD-mcp) (Apache-2.0);
consulta [`NOTICE`](NOTICE) para el detalle de la atribución y los cambios.

Desarrollado por **IMGA, S.L.P.** — Ingeniería Minera, Geológica y Ambiental.