revit-tunnel MCP（独立管片 V2）

这是一个独立于现有通用 Revit MCP 的专用 MCP。它通过 Node.js stdio MCP、仅限本机的 pyRevit Routes 接口和 Revit 2025 API，让 Agent 预览、创建并核验盾构隧道。旧版“每环一个整体族”仍完整保留；V2 新增“每块管片一个独立族构件”。

独立管片能力

• 默认布局为 9A1K：每环 9 块 A（各 37.5°）和 1 块 K（22.5°）。

• 默认 10 环会创建 100 个可单独选择、统计、过滤和排表的 Generic Models 族实例。

• 支持 1–50 环，但任何一次创建最多 500 块独立管片。

• 支持外径、厚度、环宽、三维起点、直线纵坡以及相邻环正负交替错缝。

• 每环只创建一个命名为 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 族以及不同精度版本仍可使用同一套明细表、过滤器和标签。

八个 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，不暴露到局域网。

• 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 项目，只应在测试副本或确认过的项目中使用。