Civil 3D MCP 서버 — 동적 Roslyn 포크

Autodesk Civil 3D 내부에서 AI 어시스턴트가 C# 코드를 작성하고 실행할 수 있게 해주는 MCP 서버입니다. 고정된 대규모 도구 세트 대신, AI가 Civil 3D API 접근 권한으로 실행되는 작업별 코드를 생성합니다.

프로젝트 범위 및 계보

이 포크는 동적 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이 컴파일 및 실행 → 전체 API 액세스 권한으로 Civil 3D 내부에서

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는 이미 로드된 허용 목록의 Civil 3D 호스트 어셈블리에서 공개 유형 및 멤버 이름/시그니처를 제한적으로 읽기 전용 검색하는 action: "api_lookup"도 지원합니다. 어셈블리를 로드하거나, C# 코드를 실행하거나, 활성 도면에 접근하지 않습니다. 쿼리와 선택적으로 어셈블리, 네임스페이스 접두사, 결과 제한을 제공하세요.

스킬은 skills/ 디렉토리의 문서화된 C# 코드 템플릿입니다:

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를 유지하면서, civil3d-mcp-error/v1 스키마의 structuredContent도 반환합니다. 안정적인 오류 필드는 code, category, message, source, outcome, retryable입니다. 전송 후 명령 제한 시간 초과 또는 연결 끊김은 outcome: "unknown" 및 retryable: false를 가지며, 서버는 이를 자동으로 재시도하지 않습니다. 성공적인 응답과 세 가지 도구의 공개 표면은 변경되지 않습니다.

개인 TCP 프레이밍(2C.1 단계)

각 localhost TCP 연결은 하나의 UTF-8 JSON-RPC 요청과 하나의 응답을 전달합니다. 각 JSON 본문 뒤에는 LF가 오며 크기는 LF를 제외한 UTF-8 바이트 기준 8MiB로 제한됩니다. Node 클라이언트는 완전한 JSON 본문 뒤에 정돈된 연결 종료가 오는 경우 이전 플러그인의 프레이밍되지 않은 응답도 계속 수락합니다. 과도한 크기의 요청은 작성되기 전에 거부되며, 과도한 크기 또는 잘못된 형식의 응답과 중단된 연결은 재시도 불가능한 구조화된 전송 오류를 생성합니다. 실행이 완료되었지만 플러그인이 과도한 크기의 결과를 반환할 수 없는 경우 보고된 결과는 unknown입니다.

작업 감사 로깅 및 쓰기 멱등성(2I.1 / 2I.2 단계)

기본 info 로그 수준에서 수락된 각 civil3d_query 및 civil3d_execute 작업은 하나의 제한된 stderr 감사 이벤트를 생성합니다. 여기에는 새로운 불투명 작업 ID, 도구 이름, C# 소스의 SHA-256 및 UTF-8 바이트 길이, 성공/오류 상태, 경과 밀리초가 포함됩니다. 오류는 안정적인 code/category/source/outcome 필드만 추가합니다. 감사 이벤트에는 호출자 코드, 설명, 도면 식별자, 결과 또는 오류 메시지가 절대 포함되지 않습니다.

civil3d_execute는 선택적 불투명 idempotencyKey(1~128자의 ASCII 문자, 숫자, ., _, :, -)도 허용합니다. 하나의 플러그인 세션에서 키를 UTF-8 C# SHA-256 및 정규화된 expectedDrawing 식별자에 바인딩합니다. 중복은 진행 중, 충돌 또는 이미 커밋됨으로 거부되며, 커밋된 항목은 결과를 보유하지 않으므로 호출자는 읽기 전용 쿼리로 조정해야 합니다. 세션은 완료된 키를 최대 256개까지 유지하며 가장 오래된 것을 결정적으로 제거합니다. 이는 지속성이나 자동 재시도 또는 정확히 한 번 실행 의미론을 추가하지 않습니다.

보안

Roslyn 샌드박스는 다음을 차단합니다:

• 프로세스 실행(Process.Start)

• 파일 삭제(File.Delete)

• 네트워크 요청(HttpClient, Sockets)

• 레지스트리 액세스

• 동적 어셈블리 로딩

모든 Civil 3D API 작업은 허용됩니다.

이 정규식 샌드박스는 심층 방어이지 신뢰 경계가 아닙니다. 두 코드 도구 모두 변경 가능한 Civil 3D 및 AutoCAD API 객체를 수신하며, civil3d_query는 호스트의 트랜잭션 커밋을 건너뛰지만 임의의 동적 C#이 부작용이 없음을 보장할 수 없습니다. 신뢰할 수 있고 승인 게이트가 있는 코드만 실행하세요. 루프백 TCP는 원격 네트워크 액세스를 방지하지만 다른 로컬 프로세스를 인증하지는 않습니다.

라이선스

MIT