Civil 3D MCP Server – Dynamischer Roslyn-Fork

Ein MCP-Server, der es KI-Assistenten ermöglicht, C#-Code direkt in Autodesk Civil 3D zu schreiben und auszuführen. Anstelle einer großen Anzahl fester Werkzeuge generiert die KI aufgabenspezifischen Code, der mit Zugriff auf die Civil 3D API ausgeführt wird.

Projektumfang und Herkunft

Dieser Fork behält das dynamische Roslyn/C#-Ausführungsmodell und eine bewusst kleine öffentliche Oberfläche von drei MCP-Werkzeugen bei. Die aktuelle Kompatibilitätsbasis ist Autodesk Civil 3D 2025, wobei die lokale Arbeit auf Zuverlässigkeit, Sicherheit, messbare Effizienz und wiederverwendbare Civil-3D-Skills ausgerichtet ist. Andere Civil-3D-Versionen können später durch separat verifizierte Kompatibilitätsarbeit hinzugefügt werden.

Das Projekt ist von barbosaihan/civil3d-mcp abgeleitet. SantosSjba/mcp-to-c3d wurde für ausgewählte, testgestützte Ideen evaluiert, während Sacred-G/Civil3D-mcp nur als architektonische Referenz diente. Siehe PROVENANCE.md für die detaillierte Zuschreibung und Lizenzgrenzen.

Dieses unabhängige Projekt ist weder mit Autodesk verbunden noch von Autodesk unterstützt. Autodesk-Assemblys und andere proprietäre Civil-3D-Dateien sind nicht enthalten.

Architektur

┌─────────────────┐     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-Tools

So funktioniert es

1. KI liest einen Skill → Erhält eine dokumentierte C#-Codevorlage

2. KI passt den Code an → Füllt Parameter aus, kombiniert Muster

3. KI sendet Code → Über civil3d_execute oder civil3d_query

4. Roslyn kompiliert und führt aus → Innerhalb von Civil 3D mit vollem API-Zugriff

5. Ergebnisse werden als JSON zurückgegeben → Zurück an die KI

Beispielinteraktion

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" }, ...]

Skills-Bibliothek

civil3d_skills unterstützt auch action: "api_lookup" für eine begrenzte, schreibgeschützte Suche nach öffentlichen Typ- und Membernamen/-signaturen aus bereits geladenen, auf der Whitelist stehenden Civil-3D-Host-Assemblys. Es lädt keine Assemblys, führt keinen C#-Code aus und greift nicht auf die aktive Zeichnung zu. Geben Sie eine Abfrage und optional eine Assembly, einen Namespace-Präfix und ein Ergebnislimit an.

Skills sind dokumentierte C#-Codevorlagen in skills/:

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

Globale Skriptvariablen

Code, der über civil3d_execute oder civil3d_query ausgeführt wird, hat Zugriff auf:

Alle Civil-3D-Namespaces werden automatisch importiert.

Einrichtung

1. MCP-Server erstellen

npm install && npm run build

2. Plugin erstellen

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

3. In Civil 3D laden

NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running

4. KI konfigurieren

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

Umgebungsvariablen

Benchmarking

Der hostunabhängige Rekorder der Phase 2A, der optionale interne Live-Trace-Vertrag der Phase 2A.1 und der schreibgeschützte Live-Runner der Phase 2A.2 sind in benchmark/README.md dokumentiert. Keiner fügt ein MCP-Werkzeug, eine Warteschlange oder einen Wiederholungsversuch hinzu; der 2A.2-Runner kann nur seine feste schreibgeschützte Abfrage aufrufen, wenn er explizit gestartet wird.

Strukturierte Fehler (Phase 2B.1)

civil3d_query und civil3d_execute behalten ihren vorhandenen Textfehlerinhalt und isError: true bei, geben aber auch structuredContent mit dem Schema civil3d-mcp-error/v1 zurück. Die stabilen Fehlerfelder sind code, category, message, source, outcome und retryable. Ein Befehls-Timeout oder ein Verbindungsverlust nach dem Senden hat outcome: "unknown" und retryable: false; der Server wiederholt es nie automatisch. Erfolgreiche Antworten und die öffentliche Oberfläche der drei Werkzeuge bleiben unverändert.

Privates TCP-Framing (Phase 2C.1)

Jede localhost-TCP-Verbindung überträgt eine UTF-8-JSON-RPC-Anfrage und eine Antwort. Jeder JSON-Body wird von LF gefolgt und ist auf 8 MiB begrenzt, gemessen als UTF-8-Bytes ohne das LF. Der Node-Client akzeptiert weiterhin die ungerahmte Antwort des vorherigen Plugins, wenn dieser vollständige JSON-Body von einem ordnungsgemäßen Verbindungsabbruch gefolgt wird. Überdimensionierte Anfragen werden abgelehnt, bevor sie geschrieben werden; überdimensionierte oder fehlerhafte Antworten und unterbrochene Verbindungen erzeugen nicht wiederholbare strukturierte Transportfehler. Wenn die Ausführung abgeschlossen wurde, das Plugin aber kein überdimensioniertes Ergebnis zurückgeben konnte, wird das Ergebnis als unknown gemeldet.

Betriebs-Audit-Protokollierung und Schreib-Idempotenz (Phase 2I.1 / 2I.2)

Bei der Standard-Protokollebene info gibt jeder akzeptierte civil3d_query- und civil3d_execute-Vorgang ein begrenztes stderr-Audit-Ereignis aus. Es enthält eine neue undurchsichtige Vorgangs-ID, den Werkzeugnamen, SHA-256 und UTF-8-Byte-Länge des C#-Quellcodes, den Erfolgs-/Fehlerstatus und die verstrichenen Millisekunden; Fehler fügen nur stabile Code-/Kategorie-/Quell-/Ergebnis-Felder hinzu. Das Audit-Ereignis enthält niemals Aufrufercode, Beschreibung, Zeichnungsidentität, Ergebnis oder Fehlermeldung.

civil3d_execute akzeptiert auch einen optionalen undurchsichtigen idempotencyKey (1–128 ASCII-Buchstaben, Ziffern, ., _, :, -). In einer Plugin-Sitzung bindet es den Schlüssel an die UTF-8-C#-SHA-256 und die normalisierte expectedDrawing-Identität. Ein Duplikat wird als in Bearbeitung, widersprüchlich oder bereits committet abgelehnt; committete Einträge behalten kein Ergebnis und Aufrufer müssen mit einer schreibgeschützten Abfrage abgleichen. Die Sitzung behält höchstens 256 abgeschlossene Schlüssel und entfernt deterministisch den ältesten. Dies fügt weder Persistenz noch automatische Wiederholung oder Exactly-Once-Semantik hinzu.

Sicherheit

Die Roslyn-Sandbox blockiert:

• Prozessausführung (Process.Start)

• Dateilöschung (File.Delete)

• Netzwerkanfragen (HttpClient, Sockets)

• Registrierungszugriff

• Dynamisches Laden von Assemblys

Alle Civil-3D-API-Vorgänge sind erlaubt.

Diese Regex-Sandbox ist Verteidigung in der Tiefe, keine Vertrauensgrenze. Beide Code-Werkzeuge erhalten veränderbare Civil-3D- und AutoCAD-API-Objekte; civil3d_query überspringt den Transaktions-Commit des Hosts, kann aber nicht garantieren, dass beliebiger dynamischer C#-Code nebenwirkungsfrei ist. Führen Sie nur vertrauenswürdigen, genehmigungspflichtigen Code aus. Loopback-TCP verhindert entfernten Netzwerkzugriff, authentifiziert jedoch keine anderen lokalen Prozesse.

Lizenz

MIT