civil3d-mcp-civil3d-mcp: Instructions file for Claude Code

CLAUDE.md

Guía para trabajar en este repo. Complementa a README.md (setup, tabla de acciones) y a C_References/README.md (DLLs) — no los duplica.

Qué es esto

MCP de automatización para Autodesk Civil 3D. Dos procesos:

Asistente de IA ──stdio (MCP)── Servidor Node/TS ──TCP/JSON-RPC (8080)── Plugin C# dentro de Civil3D

• Servidor MCP (src/, TypeScript/Node): expone tools MCP, valida input con Zod, reenvía cada acción al plugin como un método JSON-RPC.
• Plugin C# (plugin/Civil3dMcpPlugin/, .NET 8.0-windows): corre dentro de Civil3D, recibe el JSON-RPC, ejecuta contra la API real de Civil3D/AutoCAD.

Esta sesión de Claude Code (desarrollo) no tiene las herramientas civil3d_* cargadas — esas solo existen en la sesión de asistente de IA que el usuario conecta contra el plugin ya corriendo dentro de Civil3D (C3DMCPSTART). Para probar un cambio contra un dibujo real, el usuario debe recompilar el plugin, recargarlo (NETLOAD) y probarlo desde esa otra sesión — no se puede verificar aquí más allá de que compile.

Filosofía: primitivas, no comandos de negocio

En vez de un comando monolítico por tarea, se construyen primitivas atómicas reutilizables (detectar, filtrar, leer propiedades, modificar, calcular) más comandos específicos por dominio. Esto permite componer tareas no anticipadas de antemano combinando primitivas en el momento, en vez de depender de que exista un comando exacto ya escrito. Las primitivas genéricas clave, todas en plugin/Civil3dMcpPlugin/GenericObjectCommands.cs (tool civil3d_object):

• resolve_location — ubicar CUALQUIER punto por coordenadas, click interactivo del mouse, o relativo a un objeto de referencia + offset. Diseñado para componerse con comandos de creación existentes, no como un "crear cualquier cosa" monolítico.
• get_properties / list_by_type — introspección genérica vía reflexión (GenericObjectCommands.SerializeSimpleProperties, reutilizado en ~8 dominios distintos).
• set_style_name — motor de estilos universal: cualquier objeto con una propiedad StyleName escribible puede recibir un estilo por nombre; Civil3D resuelve el ObjectId internamente.
• EnsureLayerId(db, tr, layerName, colorIndex?) — crea la capa si no existe, devuelve su ObjectId. Consolida 3 copias casi idénticas (inline en SurfaceCommands.cs, helper privado en ProfileCommands.cs, y la ausencia total del patrón en GeometryCommands.cs — causa raíz del bug de eKeyNotFound reportado en pruebas en vivo). También expuesta como ensure_layer. Usarla siempre que se vaya a asignar Entity.Layer a un nombre que podría no existir todavía.
• delete_entity/move_entity/copy_entity/rotate_entity/get_entity_bounds/set_layer/ list_layers — primitivas genéricas sobre cualquier Entity por handle (post-Mes 9). Cierran el ciclo de prueba/limpieza: antes de esto no había forma de deshacer objetos de prueba sin entrar manualmente a Civil3D.