revit-tunnel MCP（독립 세그먼트 V2）

이것은 기존 범용 Revit MCP와 별개인 전용 MCP입니다. Node.js stdio MCP, 로컬 전용 pyRevit Routes 인터페이스 및 Revit 2025 API를 통해 Agent가 쉴드 터널을 미리 보고, 생성하고, 검증할 수 있게 합니다. 기존의 "링당 하나의 통합 패밀리" 방식은 그대로 유지되며, V2에는 "세그먼트당 하나의 독립 패밀리 구성요소"가 새로 추가됩니다.

독립 세그먼트 기능

• 기본 레이아웃은 9A1K: 링당 A 9개(각 37.5°)와 K 1개(22.5°).

• 기본 10링은 개별 선택, 통계, 필터링 및 일람표 작성이 가능한 Generic Models 패밀리 인스턴스 100개를 생성합니다.

• 1–50링을 지원하지만, 한 번의 생성에서 최대 500개의 독립 세그먼트까지만 생성할 수 있습니다.

• 외경, 두께, 링 폭, 3D 시작점, 직선 종단 경사 및 인접 링의 정·부 교대 오프셋 조인트를 지원합니다.

• 각 링에는 RTM_SEG_HOST_*라는 이름의 작업 기준면이 하나만 생성되며, 같은 링의 모든 세그먼트가 이를 공유합니다.

• 각 세그먼트에는 batch-R0001-A01, batch-R0001-K01과 같은 안정적인 마크가 있습니다.

• 배치 생성은 하나의 Revit 트랜잭션 그룹으로 묶입니다. 패밀리나 구성요소가 실패하면 인스턴스, 기준면 및 이번에 새로 로드된 패밀리가 함께 롤백됩니다.

Related MCP server: RevitMCPBridge2026

업그레이드 가능한 패밀리 콘텐츠

패밀리 이름은 구성요소 역할, 치수, 각도, 콘텐츠 구성 및 콘텐츠 버전에 의해 결정됩니다:

RTM_Segment_{role}_OD{outer}_T{thickness}_W{width}_S{spanMilliDeg}_{profile}_V{version}

현재 콘텐츠 제공자는 basic 버전 1로, 각 형상에 대해 단순한 링형 섹터 패밀리를 생성합니다. 패밀리 유형의 Type Comments에는 RTM_CONTENT:<hash>가 저장됩니다. 동일한 이름의 패밀리는 콘텐츠 해시가 완전히 일치할 때만 재사용됩니다. 해시가 없거나 해시가 다르면 충돌이 보고되며, 조용히 덮어쓰지 않습니다.

따라서 향후 세그먼트에 그라우팅 구멍, 볼트 구멍, 핸드 홀, 홈 또는 철근 표현을 추가할 때 새 콘텐츠 버전을 게시할 수 있습니다. 기존 배치는 원래 패밀리 버전에 그대로 고정됩니다. 레이아웃, 구성요소 번호 및 Agent 호출 흐름은 다시 작성할 필요가 없습니다.

구성요소 식별 매개변수

모든 독립 세그먼트 패밀리는 12개의 고정 GUID 인스턴스 공유 매개변수를 사용합니다:

• RTM_BatchId, RTM_UniqueId

• RTM_RingIndex, RTM_SegmentIndex

• RTM_SegmentSlot, RTM_SegmentRole

• RTM_LayoutId

• RTM_ContentProfile, RTM_ContentVersion

• RTM_StartAngle, RTM_EndAngle, RTM_CenterAngle

고정 GUID 덕분에 향후 A, B, K 패밀리 및 다양한 정밀도 버전에서도 동일한 일람표, 필터 및 태그 세트를 계속 사용할 수 있습니다.

8개의 MCP 도구

독립 세그먼트 V2:

• list_tunnel_segment_catalog: 레이아웃 및 콘텐츠 버전을 나열합니다.

• preview_tunnel_segments: 읽기 전용 검증을 수행하고 완전한 세그먼트별 계획과 미리보기 토큰을 반환합니다.

• create_tunnel_segments: 동일한 매개변수, preview_token 및 confirm=true가 필요하며 생성합니다.

• inspect_tunnel_segment_batch: 각 구성요소의 식별 정보, 패밀리 버전, 위치, 방향, 체적 및 호스트 기준면을 읽기 전용으로 역조회합니다.

유지되는 통합 링 V1:

• preview_tunnel_rings

• create_tunnel_rings

• inspect_tunnel_batch

• get_tunnel_backend_status(V1/V2 공용)

권장 호출 순서: 백엔드 확인 → 카탈로그 나열 → 미리보기 → 사용자 확인 → 생성 → 배치 검사.

향후 6A＋2B＋1K 전환

레이아웃과 패밀리 콘텐츠는 이미 계층화되어 있습니다. 나중에 6A2B1K를 추가할 때는 버전 관리 카탈로그에 9개의 슬롯과 A/B/K 각도 규칙만 추가하면 됩니다. 배치기, 식별 매개변수, MCP 도구 및 검사 인터페이스는 변경되지 않습니다. B와 A의 형상이 다르면 시스템이 역할과 각도에 따라 새 패밀리 사양을 자동으로 해석합니다.

안전 경계

• Routes는 127.0.0.1:48884만 수신하며 LAN에 노출되지 않습니다.

• Node 미리보기와 pyRevit 백엔드는 각각 전체 계획을 검증합니다. V2는 레이아웃 요약, 링별 위치, 세그먼트별 각도, 마크, 패밀리 이름 및 콘텐츠 해시를 다시 계산합니다.

• 통합 링과 독립 세그먼트는 전역 batch_id 네임스페이스를 공유하며, 어느 한쪽에 이미 존재하면 중복 생성을 거부합니다.

• 현재 기존 배치를 삭제, 덮어쓰기 또는 업그레이드하는 도구는 없습니다.

• 기존 범용 Revit MCP와 ShieldTunnel.extension은 모두 수정되지 않았습니다.

설치

• 소스: 이 저장소를 클론한 프로젝트 디렉터리

• pyRevit 확장: %USERPROFILE%\Documents\pyRevit Extensions\RevitTunnelMcp.extension

• Codex 구성: %USERPROFILE%\.codex\config.toml의 [mcp_servers.revit_tunnel]

먼저 Node.js 22와 프로젝트 종속성을 설치합니다:

npm install

확장을 다시 설치합니다:

& '.\scripts\install.ps1' -RoutesPort 48884

설치 또는 수정 후에는 pyRevit을 다시 로드하거나(또는 Revit을 재시작)해야 합니다.

검증 및 스모크 호출

npm test
python -m pytest -q '.\pyrevit\tests'
node '.\scripts\smoke-test.mjs' --segments --inspect --batch-id=<批次>

두 링의 독립 세그먼트 테스트 배치를 생성합니다:

node '.\scripts\smoke-test.mjs' --segments --create --ring-count=2 --batch-id=segment-e2e-01

통합 링 구버전 호출에는 --segments를 추가하지 않습니다. --create는 현재 Revit 프로젝트를 실제로 수정하므로 테스트 사본 또는 확인된 프로젝트에서만 사용해야 합니다.