Civil 3D MCP Server — Dynamic Roslyn Fork

MCP-сервер, который позволяет AI-ассистентам писать и выполнять код на C# непосредственно внутри Autodesk Civil 3D. Вместо большого набора фиксированных инструментов AI генерирует код под конкретную задачу, который выполняется с доступом к API Civil 3D.

Область проекта и происхождение

Этот форк сохраняет динамическую модель выполнения Roslyn/C# и намеренно небольшой публичный интерфейс из трёх MCP-инструментов. Его текущая базовая совместимость — Autodesk Civil 3D 2025, а локальная работа сосредоточена на надёжности, безопасности, измеримой эффективности и переиспользуемых навыках Civil 3D. Другие версии Civil 3D могут быть добавлены позже через отдельно проверенную работу по совместимости.

Проект происходит из barbosaihan/civil3d-mcp. SantosSjba/mcp-to-c3d был оценён на предмет отдельных идей, подкреплённых тестами, а Sacred-G/Civil3D-mcp использовался только как архитектурный справочник. См. PROVENANCE.md для подробной атрибуции и границ лицензирования.

Этот независимый проект не аффилирован с Autodesk и не одобрен им. Сборки Autodesk и другие проприетарные файлы Civil 3D не включены.

Архитектура

┌─────────────────┐     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 мета-инструмента

Как это работает

1. AI читает навык → Получает документированный шаблон кода C#

2. AI адаптирует код → Заполняет параметры, комбинирует шаблоны

3. AI отправляет код → Через civil3d_execute или civil3d_query

4. Roslyn компилирует и выполняет → Внутри Civil 3D с полным доступом к API

5. Результаты возвращаются в JSON → Обратно к AI

Пример взаимодействия

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

Библиотека навыков

civil3d_skills также поддерживает action: "api_lookup" для ограниченного поиска только для чтения по именам и сигнатурам публичных типов и членов из уже загруженных разрешённых сборок хоста Civil 3D. Он не загружает сборки, не выполняет код C# и не обращается к активному чертежу. Укажите запрос и, при необходимости, сборку, префикс пространства имён и лимит результатов.

Навыки — это документированные шаблоны кода C# в skills/:

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

Глобальные переменные скрипта

Код, выполняемый через civil3d_execute или civil3d_query, имеет доступ к:

Все пространства имён Civil 3D автоматически импортируются.

Настройка

1. Сборка MCP-сервера

npm install && npm run build

2. Сборка плагина

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

3. Загрузка в Civil 3D

NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running

4. Настройка AI

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

Переменные окружения

Бенчмаркинг

Независимый от хоста рекордер фазы 2A, опциональный внутренний контракт трассировки в реальном времени фазы 2A.1 и раннер только для чтения фазы 2A.2 документированы в benchmark/README.md. Ни один из них не добавляет MCP-инструмент, очередь или повторные попытки; раннер 2A.2 может вызывать только свой фиксированный запрос только для чтения при явном запуске.

Структурированные ошибки (фаза 2B.1)

civil3d_query и civil3d_execute сохраняют существующее текстовое содержимое ошибок и isError: true, а также возвращают structuredContent со схемой civil3d-mcp-error/v1. Стабильные поля ошибок: code, category, message, source, outcome и retryable. Таймаут команды или потеря соединения после отправки имеют outcome: "unknown" и retryable: false; сервер никогда не повторяет их автоматически. Успешные ответы и публичный интерфейс из трёх инструментов не изменяются.

Приватная TCP-фрейминг (фаза 2C.1)

Каждое TCP-соединение localhost передаёт один UTF-8 JSON-RPC запрос и один ответ. Каждое JSON-тело сопровождается LF и ограничено 8 МиБ, измеряемых в байтах UTF-8 без LF. Node-клиент по-прежнему принимает нефреймированный ответ предыдущего плагина, когда полное JSON-тело сопровождается корректным закрытием соединения. Чрезмерно большие запросы отклоняются до записи; чрезмерно большие или повреждённые ответы и прерванные соединения вызывают не повторяемые структурированные ошибки транспорта. Если выполнение завершилось, но плагин не смог вернуть чрезмерно большой результат, сообщается outcome: "unknown".

Журналирование операций и идемпотентность записи (фаза 2I.1 / 2I.2)

При уровне журналирования по умолчанию info каждая принятая операция civil3d_query и civil3d_execute генерирует одно ограниченное событие аудита в stderr. Оно содержит новый непрозрачный идентификатор операции, имя инструмента, SHA-256 и длину в байтах UTF-8 исходного кода C#, статус успеха/ошибки и затраченные миллисекунды; ошибки добавляют только стабильные поля code/category/source/outcome. Событие аудита никогда не содержит код вызывающего, описание, идентичность чертежа, результат или сообщение об ошибке.

civil3d_execute также принимает опциональный непрозрачный idempotencyKey (1–128 ASCII-букв, цифр, ., _, :, -). В одной сессии плагина он связывает ключ с SHA-256 UTF-8 кода C# и нормализованной идентичностью expectedDrawing. Дубликат отклоняется как выполняющийся, конфликтующий или уже зафиксированный; зафиксированные записи не сохраняют результат, и вызывающий должен свериться с запросом только для чтения. Сессия хранит не более 256 завершённых ключей, детерминированно вытесняя самые старые. Это не добавляет ни персистентности, ни автоматических повторных попыток, ни семантики ровно один раз.

Безопасность

Песочница Roslyn блокирует:

• Запуск процессов (Process.Start)

• Удаление файлов (File.Delete)

• Сетевые запросы (HttpClient, Sockets)

• Доступ к реестру

• Динамическую загрузку сборок

Все операции API Civil 3D разрешены.

Эта regex-песочница — защита в глубину, а не граница доверия. Оба инструмента для кода получают изменяемые объекты API Civil 3D и AutoCAD; civil3d_query пропускает фиксацию транзакции хоста, но не может гарантировать, что произвольный динамический C# не имеет побочных эффектов. Выполняйте только доверенный код, прошедший проверку. Loopback TCP предотвращает удалённый сетевой доступ, но не аутентифицирует другие локальные процессы.

Лицензия

MIT