Skip to main content
Glama
deenesjakoruzh
nezolder

Civil 3D MCP Server

by nezolder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

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 amplio conjunto de herramientas fijas, la IA genera código específico para cada tarea que se ejecuta con acceso a la API de Civil 3D.

Alcance del proyecto y procedencia

Esta bifurcación mantiene el modelo dinámico de ejecución de Roslyn/C# y una superficie pública deliberadamente reducida de tres herramientas MCP. Su línea base de compatibilidad actual es Autodesk Civil 3D 2025, con el 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 trabajos de compatibilidad verificados por separado.

El proyecto deriva de barbosaihan/civil3d-mcp. SantosSjba/mcp-to-c3d se evaluó para ideas seleccionadas respaldadas por pruebas, mientras que Sacred-G/Civil3D-mcp se utilizó únicamente 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.

Related MCP server: Civil 3D MCP Server

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

Herramienta

Propósito

Seguridad

civil3d_execute

Ejecutar código C# con acceso de escritura; guardado opcional tras la confirmación

⚠️ Modifica el dibujo

civil3d_query

Ejecutar código C# solo lectura (sin confirmación)

✅ Sin efectos secundarios

civil3d_skills

Explorar/buscar/leer plantillas de habilidades de código; api_lookup busca metadatos públicos ya cargados de la API de Civil 3D

✅ Solo metadatos

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 los ensamblados anfitriones de Civil 3D ya cargados y permitidos. No carga ensamblados, no 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:

Global

Tipo

Descripción

Document

Document

Documento activo de AutoCAD

CivilDoc

CivilDocument

Documento activo de Civil 3D

Database

Database

Base de datos del documento

Transaction

Transaction

Transacción activa

Editor

Editor

Editor del documento

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

Confirmar la transacción de civil3d_execute modifica el dibujo abierto, pero por sí solo no escribe el archivo DWG en disco. Establezca saveDrawing: true cuando el cambio completado también deba guardarse. El complemento guarda únicamente después de que la transacción del script y el bloqueo del documento se hayan cerrado; los scripts no deben llamar a Database.SaveAs ni poner en cola QSAVE por sí mismos. La solicitud de guardado utiliza un tiempo de espera predeterminado independiente de 10 minutos y nunca se reintenta 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

Variable

Valor predeterminado

Descripción

CIVIL3D_HOST

localhost

Host del complemento

CIVIL3D_PORT

8080

Puerto del complemento

CIVIL3D_COMMAND_TIMEOUT

120000

Tiempo de espera de ejecución (ms)

CIVIL3D_SAVE_TIMEOUT

600000

Tiempo de espera para solicitudes de ejecución con saveDrawing: true (ms)

LOG_LEVEL

info

Nivel de registro

Evaluación comparativa

El grabador independiente del host de la fase 2A, el contrato de seguimiento en vivo interno 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 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 correctas y la superficie pública de tres herramientas no cambian.

Enmarcado TCP privado (fase 2C.1)

Cada conexión TCP de bucle local transporta una solicitud y una respuesta JSON-RPC UTF-8. Cada cuerpo JSON va seguido de LF y está limitado a 8 MiB, medido en bytes UTF-8 sin el LF. El cliente Node sigue aceptando la respuesta sin enmarcar del complemento anterior cuando ese cuerpo JSON completo va seguido de un cierre de conexión ordenado. Las solicitudes sobredimensionadas se rechazan antes de escribirse; las respuestas sobredimensionadas 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 sobredimensionado, el resultado notificado 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 acotado en stderr. Contiene un nuevo ID de operación opaco, 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 únicamente los campos estables code/category/source/outcome. El evento de auditoría nunca contiene código del llamador, descripción, identidad del dibujo, resultado ni mensaje de error.

civil3d_execute también acepta una idempotencyKey opaca opcional (1–128 caracteres ASCII: letras, dígitos, ., _, :, -). En una sesión del complemento, vincula la clave al SHA-256 del C# UTF-8, a la identidad normalizada de expectedDrawing y a la elección de saveDrawing. Un duplicado se rechaza como en curso, conflictivo o ya confirmado; las entradas confirmadas no conservan ningún resultado y los llamadores deben conciliar con una consulta de solo lectura. Un fallo de guardado ocurre después de la confirmación de escritura en memoria, por lo que su clave se mantiene como completada para evitar una modificación duplicada accidental. La sesión conserva como máximo 256 claves completadas, desalojando la más antigua de forma determinista. Esto no añade persistencia ni reintento automático ni semántica de exactamente una vez.

Seguridad

El entorno aislado 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 entorno aislado basado en expresiones regulares es una 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 únicamente código confiable y sujeto a aprobación. El TCP de bucle local impide el acceso remoto a la red, pero no autentica otros procesos locales.

Licencia

MIT

Available Tools

3 tools
civil3d_executeA

Execute C# code in Civil 3D with write access. The code runs inside a committed transaction. Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results back as JSON. Use this for operations that MODIFY the drawing (create, edit, delete objects). expectedDrawing must come from a prior read-only identity query. To persist the drawing file, set saveDrawing=true; do not call Database.SaveAs or queue QSAVE from the C# code.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesC# code to execute. Has access to Document, CivilDoc, Database, Transaction, Editor. Example: var id = TinSurface.Create(Database, "MySurface"); return new { success = true };
descriptionNoOptional human-readable summary; excluded from operation audit logs.
saveDrawingNoWhen true, save the currently named DWG after the write transaction commits and wait for completion. Use this instead of Database.SaveAs or Document.SendStringToExecute("QSAVE") in code. An unsaved drawing must first be named in Civil 3D.
idempotencyKeyNoOptional opaque session key. Reuse it only to manually reconcile an uncertain outcome; use a new key for an intentional new write.
expectedDrawingYesExpected active drawing identity checked immediately before Civil API access.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well: it notes the committed transaction, available globals, JSON return, drawing identity check, and save workflow. It does not mention exception handling or failure rollback, but that is a minor gap for a code-execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, then elaborates on key parameters and constraints. It is not overly verbose, though bullet formatting could improve scannability; still, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex code-execution tool with no output schema, the description explains available globals, return format, drawing identity requirements, save behavior, and sibling distinction. No critical operational detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, yet the description adds significant context: expectedDrawing provenance and check timing, saveDrawing conditions (must be named), idempotencyKey purpose, and an example for code. It clearly enhances schema-only information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise purpose: executing C# code with write access in Civil 3D. It explicitly scopes the tool to modifying the drawing ('Use this for operations that MODIFY the drawing'), which distinguishes it from the read-only sibling civil3d_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage criteria: use for modifications, not for reads; requires expectedDrawing from a prior civil3d_query; and warns against calling Database.SaveAs or queuing QSAVE, directing the user to the saveDrawing parameter instead. This fully covers when and how to use it versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

civil3d_queryA

Execute C# code in Civil 3D in READ-ONLY mode (no changes saved). Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results as JSON. Use this for querying data: listing objects, getting properties, analyzing surfaces, etc. Omit expectedDrawing only to bootstrap Database.Filename and Database.FingerprintGuid; otherwise supply it to guard the active drawing.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesC# code to query data. Has access to Document, CivilDoc, Database, Transaction, Editor. Example: 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;
expectedDrawingNoExpected active drawing identity checked immediately before Civil API access.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does substantial work: it discloses read-only semantics ('no changes saved'), available globals (Document, CivilDoc, Database, Transaction, Editor), auto-imported namespaces, the JSON return mechanism, and the expectedDrawing guard vs. bootstrap behavior. It does not cover error behavior for failed compilation or thrown exceptions at runtime, which is a notable gap for a code-execution tool, but the disclosed traits are rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose/globals/return semantics, when-to-use, and the expectedDrawing rule. The first sentence is dense but not wasteful; the most critical differentiator (READ-ONLY) is front-loaded before supporting details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex code-execution tool with no annotations and no output schema, the description covers the essentials: execution mode, environment globals, namespaces, return format, and the identity-guard parameter semantics. The main omissions are error/exception behavior and the exact failure mode when expectedDrawing mismatches, which an agent invoking arbitrary C# code would benefit from knowing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by explaining when to omit expectedDrawing entirely — 'Omit expectedDrawing only to bootstrap Database.Filename and Database.FingerprintGuid; otherwise supply it to guard the active drawing' — a semantic the schema's field descriptions do not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Execute C# code in Civil 3D in READ-ONLY mode (no changes saved).' It further scopes the tool with 'Use this for querying data: listing objects, getting properties, analyzing surfaces, etc.', which clearly differentiates it from the sibling civil3d_execute. An agent can tell immediately what this tool does and how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this for querying data' is an explicit when-to-use statement with concrete examples. The READ-ONLY framing implies that mutations belong to the sibling civil3d_execute, though it never names that alternative or states a when-not-to-use condition explicitly, so it stops short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

civil3d_skillsA

Browse and read Civil 3D code skills (documented C# code templates). Use 'list' to see available skills, 'search' to find by keyword, 'get' to read the full skill with code template, or 'api_lookup' to search public metadata from already-loaded Civil 3D host assemblies. Skills are pre-built C# patterns you can adapt and execute via civil3d_execute or civil3d_query.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum list/search/api_lookup results to return (integer 1-50; default 20)
queryNoSearch query for 'search' or 'api_lookup' action
actionYeslist = browse skill metadata, search = find by keyword, get = read full skill, api_lookup = read-only public API metadata search
cursorNoOpaque nextCursor from a prior list/search call with the same filters
assemblyNoAllowlisted loaded host assembly filter for api_lookup
categoryNoFilter by category (surfaces, alignments, points, etc.)
namespaceNoNamespace prefix filter for api_lookup
skillNameNoSkill name for 'get' action

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It clearly labels the tool as read-only ('Browse and read', 'read-only public API metadata search'), implying no state changes. It also notes that execution happens via sibling tools, which further clarifies that this tool itself does not modify anything. The absence of side-effect warnings is acceptable given the read-only framing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding critical information: the core purpose, the list of actions, and the relationship to sibling tools. It front-loads the main purpose and avoids redundancy or filler. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with four actions, the description is nearly complete. It explains the actions, implies the output (list of skills, search results, full skill content, API metadata), and points to the execution siblings. While it doesn't detail pagination or output structure, those are typically understood and the schema covers cursor details. The description is sufficient for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters have descriptions in the schema. The tool description adds contextual meaning (e.g., what 'get' does, that api_lookup is read-only) but does not explain parameter syntax or constraints beyond the schema. This meets the baseline of 3 but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Browse and read Civil 3D code skills') and immediately enumerates the four supported actions (list, search, get, api_lookup). It also distinguishes itself from the sibling tools by noting that skills 'can be adapted and execute via civil3d_execute or civil3d_query.' This clearly sets its scope apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool's role as a browsing/reading layer and explicitly points to the sibling tools for execution. It also differentiates between read actions (list/search/get) and the read-only metadata api_lookup. While it doesn't list explicit 'when not to use' scenarios, the purpose is clear enough for an agent to decide between this and its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcivil3d_execute
    • First observedcivil3d_query
    • First observedcivil3d_skills
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear, non-overlapping purpose: execute for write operations, query for read-only operations, and skills for browsing code templates. The read/write distinction is explicitly stated, so agents should not confuse execute and query.

Naming Consistency4/5

All tools share the civil3d_ prefix and snake_case, but the suffixes mix verbs (execute, query) with a noun (skills), making it not a strictly consistent verb_noun pattern. The naming is still predictable and readable.

Tool Count5/5

Three tools is a well-scoped set for a server that provides arbitrary C# execution capabilities; each tool serves a distinct and necessary function. The count falls within the typical 3-15 range.

Completeness5/5

The combination of execute and query covers the full range of Civil 3D operations (create, edit, delete, query), and skills fills the learning gap. No obvious missing functionality for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Civil 3D MCP Server

    DaniGhosy
    A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to interact with Autodesk Civil 3D through natural language, supporting tools for surfaces, alignments, profiles, corridors, pipe networks, COGO points, and AutoCAD geometry.
    9
    3
    MIT

  • Autodesk MCP Platform

    hjlrosales
    A
    license
    Not graded
    quality
    A
    maintenance
    Lets any MCP-compatible AI assistant read and edit Autodesk Civil 3D drawings through tools for alignments, surfaces, corridors, pipe networks, quantity takeoff, and cut/fill, using a local bridge plugin and named pipes.
    MIT