Servidor MCP de Civil 3D — Bifurcación dinámica de Roslyn

Un servidor MCP que permite a los asistentes de IA escribir y ejecutar código C# directamente dentro de Autodesk Civil 3D. En lugar de un gran conjunto de herramientas fijas, la IA genera código específico para la tarea que se ejecuta con acceso a la API de Civil 3D.

Alcance del proyecto y linaje

Esta bifurcación mantiene el modelo dinámico de ejecución de Roslyn/C# y una superficie pública deliberadamente pequeña de tres herramientas MCP. Su línea base de compatibilidad actual es Autodesk Civil 3D 2025, con trabajo local centrado en fiabilidad, seguridad, eficiencia medible y habilidades reutilizables de Civil 3D. Otras versiones de Civil 3D pueden añadirse más adelante mediante trabajo de compatibilidad verificado por separado.

El proyecto deriva de barbosaihan/civil3d-mcp. SantosSjba/mcp-to-c3d fue evaluado para ideas seleccionadas respaldadas por pruebas, mientras que Sacred-G/Civil3D-mcp se utilizó solo como referencia arquitectónica. Consulte PROVENANCE.md para conocer la atribución detallada y los límites de licencia.

Este proyecto independiente no está afiliado ni respaldado por Autodesk. Los ensamblados de Autodesk y otros archivos propietarios de Civil 3D no están incluidos.

Arquitectura

┌─────────────────┐     stdio      ┌──────────────────┐     TCP/JSON-RPC    ┌──────────────────┐
│   AI Assistant   │ ◄────────────► │  MCP Server (TS) │ ◄──────────────────► │  Civil 3D Plugin │
│ (Claude, Cline)  │               │   3 meta-tools    │     port 8080       │  Roslyn Engine   │
└─────────────────┘               └──────────────────┘                      └──────────────────┘
                                         │                                         │
                                    Skills Library                           C# Code Execution
                                   (.skill.md files)                      (full Civil 3D API)

3 Meta-herramientas

Cómo funciona

1. La IA lee una habilidad → Obtiene una plantilla de código C# documentada

2. La IA adapta el código → Rellena parámetros, combina patrones

3. La IA envía el código → Mediante civil3d_execute o civil3d_query

4. Roslyn compila y ejecuta → Dentro de Civil 3D con acceso completo a la API

5. Los resultados se devuelven como JSON → De vuelta a la IA

Ejemplo de interacción

User: "What surfaces are in my drawing?"

AI: Uses civil3d_query with:
  var surfaces = new List<object>();
  foreach (ObjectId id in CivilDoc.GetSurfaceIds()) {
    var s = Transaction.GetObject(id, OpenMode.ForRead) as TinSurface;
    surfaces.Add(new { s.Name, s.Layer });
  }
  return surfaces;

Result: [{ "Name": "EG", "Layer": "C-TOPO-EG" }, ...]

Biblioteca de habilidades

civil3d_skills también admite action: "api_lookup" para una búsqueda acotada y de solo lectura de nombres y firmas de tipos y miembros públicos de ensamblados de host de Civil 3D ya cargados en la lista de permitidos. No carga ensamblados, ejecuta código C# ni accede al dibujo activo. Proporcione una consulta y opcionalmente un ensamblado, un prefijo de espacio de nombres y un límite de resultados.

Las habilidades son plantillas de código C# documentadas en skills/:

skills/
├── surfaces/           # Surface operations
├── alignments/         # Alignment + station/offset
├── points/             # COGO points
├── geometry/           # Lines, polylines, text
├── drawing/            # Drawing info
└── workflows/          # Complex multi-object operations

Variables globales de script

El código ejecutado mediante civil3d_execute o civil3d_query tiene acceso a:

Todos los espacios de nombres de Civil 3D se importan automáticamente.

Configuración

1. Compilar el servidor MCP

npm install && npm run build

2. Compilar el complemento

# Copy DLLs from Civil 3D to C_References/ (see C_References/README.md)
cd plugin/Civil3dMcpPlugin
dotnet build

3. Cargar en Civil 3D

NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running

4. Configurar la IA

{
  "mcpServers": {
    "civil3d": {
      "command": "node",
      "args": ["/path/to/civil3d-mcp/build/index.js"]
    }
  }
}

Variables de entorno

Evaluación comparativa

El grabador independiente del host de la fase 2A, el contrato de seguimiento interno en vivo opcional de la fase 2A.1 y el ejecutor en vivo de solo lectura de la fase 2A.2 están documentados en benchmark/README.md. Ninguno añade una herramienta MCP, cola o reintento; el ejecutor 2A.2 solo puede invocar su consulta fija de solo lectura cuando se inicia explícitamente.

Errores estructurados (fase 2B.1)

civil3d_query y civil3d_execute mantienen su contenido de error de texto existente y isError: true, al tiempo que también devuelven structuredContent con el esquema civil3d-mcp-error/v1. Los campos de error estables son code, category, message, source, outcome y retryable. Un tiempo de espera de comando o una pérdida de conexión después del envío tiene outcome: "unknown" y retryable: false; el servidor nunca lo reintenta automáticamente. Las respuestas exitosas y la superficie pública de tres herramientas no cambian.

Encuadre TCP privado (fase 2C.1)

Cada conexión TCP de bucle local transporta una solicitud JSON-RPC UTF-8 y una respuesta. Cada cuerpo JSON va seguido de LF y está limitado a 8 MiB, medido como bytes UTF-8 sin el LF. El cliente Node todavía acepta la respuesta sin encuadre del complemento anterior cuando ese cuerpo JSON completo va seguido de un cierre de conexión ordenado. Las solicitudes de tamaño excesivo se rechazan antes de escribirse; las respuestas de tamaño excesivo o malformadas y las conexiones interrumpidas producen errores de transporte estructurados no reintentables. Si la ejecución se completó pero el complemento no pudo devolver un resultado de tamaño excesivo, el resultado informado es unknown.

Registro de auditoría de operaciones e idempotencia de escritura (fase 2I.1 / 2I.2)

En el nivel de registro info predeterminado, cada operación aceptada de civil3d_query y civil3d_execute emite un evento de auditoría de stderr acotado. Contiene un ID de operación opaco nuevo, nombre de la herramienta, SHA-256 y longitud en bytes UTF-8 del código fuente C#, estado de éxito/error y milisegundos transcurridos; los errores añaden solo campos estables de código/categoría/origen/resultado. El evento de auditoría nunca contiene código del llamador, descripción, identidad del dibujo, resultado o mensaje de error.

civil3d_execute también acepta una idempotencyKey opcional y opaca (1–128 caracteres ASCII de letras, dígitos, ., _, :, -). En una sesión de complemento, vincula la clave al SHA-256 del C# UTF-8 y a la identidad normalizada de expectedDrawing. Un duplicado se rechaza como en progreso, conflictivo o ya confirmado; las entradas confirmadas no conservan ningún resultado y los llamadores deben conciliar con una consulta de solo lectura. La sesión mantiene como máximo 256 claves completadas, expulsando la más antigua de manera determinista. Esto no añade persistencia ni reintento automático ni semántica de exactamente una vez.

Seguridad

El sandbox de Roslyn bloquea:

• Ejecución de procesos (Process.Start)

• Eliminación de archivos (File.Delete)

• Solicitudes de red (HttpClient, Sockets)

• Acceso al registro

• Carga dinámica de ensamblados

Todas las operaciones de la API de Civil 3D están permitidas.

Este sandbox de expresiones regulares es defensa en profundidad, no un límite de confianza. Ambas herramientas de código reciben objetos mutables de las API de Civil 3D y AutoCAD; civil3d_query omite la confirmación de transacción del host pero no puede garantizar que el C# dinámico arbitrario esté libre de efectos secundarios. Ejecute solo código confiable y con aprobación previa. El TCP de bucle local evita el acceso remoto a la red pero no autentica otros procesos locales.

Licencia

MIT