revit-tunnel MCP (Independent Segments V2)

This is a dedicated MCP independent of the existing general-purpose Revit MCP. It lets an Agent preview, create, and verify shield tunnels through a Node.js stdio MCP, a local-only pyRevit Routes interface, and the Revit 2025 API. The legacy "one family per ring" approach is fully preserved; V2 adds "one independent family instance per segment."

Independent Segment Capabilities

• Default layout is 9A1K: 9 A segments (37.5° each) and 1 K segment (22.5°) per ring.

• The default 10 rings create 100 Generic Models family instances that can be individually selected, scheduled, filtered, and tabulated.

• Supports 1–50 rings, but any single creation is capped at 500 independent segments.

• Supports outer diameter, thickness, ring width, 3D start point, straight-line longitudinal slope, and alternating positive/negative staggered joints between adjacent rings.

• Each ring creates only one named work plane, RTM_SEG_HOST_*, shared by all segments in that ring.

• Every segment has a stable marker, e.g. batch-R0001-A01, batch-R0001-K01.

• Batch creation is wrapped in a single Revit transaction group; if any family or element fails, the instances, work planes, and newly loaded families in this batch are rolled back together.

Related MCP server: RevitMCPBridge2026

Upgradable Family Content

The family name is determined by the segment role, dimensions, angles, content profile, and content version:

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

The current content provider is basic version 1, which generates one simple annular sector family per geometry. The family type's Type Comments stores RTM_CONTENT:<hash>. Families with the same name are reused only when the content hash matches exactly; a missing or mismatched hash reports a conflict and is never silently overwritten.

Therefore, when adding grout holes, bolt holes, hand holes, grooves, or rebar representation to segments in the future, a new content version can be published. Old batches remain frozen on their original family version; the layout, element numbering, and Agent invocation flow do not need to change.

Element Identity Parameters

All independent segment families use 12 instance shared parameters with fixed GUIDs:

• RTM_BatchId, RTM_UniqueId

• RTM_RingIndex, RTM_SegmentIndex

• RTM_SegmentSlot, RTM_SegmentRole

• RTM_LayoutId

• RTM_ContentProfile, RTM_ContentVersion

• RTM_StartAngle, RTM_EndAngle, RTM_CenterAngle

The fixed GUIDs mean future A, B, and K families, as well as different precision versions, can still use the same schedules, filters, and tags.

Eight MCP Tools

Independent segments V2:

• list_tunnel_segment_catalog: lists layouts and content versions.

• preview_tunnel_segments: read-only validation that returns the full per-segment plan and a preview token.

• create_tunnel_segments: requires the same parameters, preview_token, and confirm=true before creating.

• inspect_tunnel_segment_batch: read-only reverse lookup of each element's identity, family version, position, orientation, volume, and hosting work plane.

Preserved whole-ring V1:

• preview_tunnel_rings

• create_tunnel_rings

• inspect_tunnel_batch

• get_tunnel_backend_status (shared by V1/V2)

The recommended call order is: check backend → list catalog → preview → user confirmation → create → inspect batch.

Future Switch to 6A＋2B＋1K

The layout and family content are already layered. When 6A2B1K is added later, only 9 slots and the A/B/K angle rules need to be added to the versioned catalog; the placer, identity parameters, MCP tools, and inspection interface remain unchanged. If B's geometry differs from A's, the system automatically resolves the new family spec by role and angle.

Safety Boundaries

• Routes listens only on 127.0.0.1:48884 and is not exposed to the LAN.

• The Node preview and the pyRevit backend each validate the full plan independently; V2 also recomputes the layout summary, per-ring positions, per-segment angles, markers, family names, and content hashes.

• Whole rings and independent segments share the global batch_id namespace; duplicate creation is rejected if either side already exists.

• There are currently no tools to delete, overwrite, or upgrade existing batches.

• The existing general-purpose Revit MCP and ShieldTunnel.extension are both unmodified.

Installation

• Source: the project directory after cloning this repository

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

• Codex config: [mcp_servers.revit_tunnel] in %USERPROFILE%\.codex\config.toml

First install Node.js 22 and the project dependencies:

npm install

Reinstall the extension:

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

After installing or modifying, reload pyRevit (or restart Revit).

Verification and Smoke Calls

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

Create a two-ring independent segment test batch:

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

The legacy whole-ring calls do not use --segments. --create actually modifies the current Revit project and should only be used on a test copy or a confirmed project.