# Revit MCP Automation

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Verified: Revit 2020](https://img.shields.io/badge/Verified-Revit%202020-blue)
![Platform: Windows x64](https://img.shields.io/badge/Platform-Windows%20x64-blue)

**让 AI 按需启动独立 Revit、连接 MCP、处理常见警告，并在弹窗解除后继续原来的模型操作。**

Revit MCP Automation 是运行在 Windows 本机的 Revit 自动化层。它复用 [mcp-servers-for-revit](https://github.com/mcp-servers-for-revit/mcp-servers-for-revit) 的模型操作工具，补齐从“发起请求”到“Revit 就绪”、以及从“出现弹窗”到“取回操作结果”的流程。

当前版本：**自动化宿主 1.0.4；31 个 MCP 工具，其中 5 个为本项目新增。** 已验证环境为 Windows x64、Revit 2020、Node.js 24.19.0，以及已安装的 Revit 2020 兼容命令插件。

> 本仓库发布自动化层源码，不包含 Revit、授权组件、Revit API DLL、第三方命令插件二进制或项目模型。首次安装需要具备下文所列依赖。Revit 会打开正常桌面窗口，运行时需要 Windows 用户保持登录。

## 能做什么

| 能力 | 实际行为 |
| --- | --- |
| 按需自动启动 | 第一次模型请求启动独立 Revit，等待桥接和默认测试模型就绪后执行；无需手动点击旧 MCP Switch |
| 使用独立实例 | 通过 PID、会话和认证值确认受管实例，不自动接管用户手动打开的 Revit，不回退到旧的固定 8080 端口 |
| 打开指定模型 | `open_revit_model` 打开 Revit 2020 兼容的本地 RVT/RFA 绝对路径；默认先进入自动创建的测试模型 |
| 复用原有工具 | 提供元素、视图、标高、房间、选择、C# 执行和本地数据存储等上游工具，完整清单见[工具说明](docs/TOOLS.md) |
| 自动处理常见提示 | 对经过匹配的缺失参照提示选择继续打开；暂缓未保存提醒；确认符合规则的单按钮通知，并保留处理记录 |
| 读取和点击弹窗 | 即使 Revit 主 API 被模态窗口阻塞，也可独立读取消息和按钮，再用新鲜快照点击已观察到的按钮 |
| 继续原操作 | 遇到选择窗口时返回 `waiting_for_dialog` 和 `operationId`；处理后获取原命令结果，避免重复提交建模命令 |
| 重连与恢复 | MCP 连接重建后可复用受管 Revit；受管实例正常退出后，下次请求重新启动；结果不明时明确返回状态 |
| 可审计、可撤销安装 | 本地保留弹窗和操作记录；安装脚本与回滚脚本公开，Codex 配置修改仅针对 `mcp_servers.revit` |

## 优势在哪里

以下比较针对本项目改造前的**本机固定端口、手动开关流程**，不代表所有 Revit MCP 产品。

| 环节 | 改造前的使用流程 | 本方案 |
| --- | --- | --- |
| 启动 | 人工打开 Revit、启用插件监听，再让 AI 连接 | 模型请求触发启动和就绪检查 |
| 实例识别 | 连接固定端口，使用者自行确认对应实例 | 随机回环端口、会话认证、PID 校验；拒绝未受管实例 |
| 弹窗阻塞 | API 等待，频繁需要人到桌面处理 | 已知提示自动处理；其余窗口通过独立 MCP 通道检查和点击 |
| 超时后的动作 | 重新发指令容易重复创建对象 | 原操作保留票据；不自动重放写请求，结果不明时先核查模型 |
| 运行环境 | 系统 Node 更新可能导致 SQLite 原生模块失配 | 私有 Node 24 运行时和锁定依赖，减少环境漂移 |
| 交付和排查 | 本机设置及处理过程难以复现 | 源码、构建/安装/回滚脚本和验证边界一并公开 |

这些优势来自工作流程和防护机制；本项目没有发布吞吐量或性能提升百分比。

## 工作原理

```mermaid
flowchart LR
    A[AI / MCP 客户端] -->|stdio| B[Node MCP Server]
    B --> C[受管实例 Broker]
    C -->|首次请求| D[当前用户交互式 Windows 任务]
    D --> E[独立 Revit 2020]
    C -->|回环 TCP + 会话认证| F[C# Automation Host]
    F --> G[现有 Revit 命令插件]
    G --> E
    C -->|独立弹窗通道| H[PowerShell / Windows UI Automation]
    H --> E
```

模型命令和弹窗处理使用不同通道，因此模态窗口阻塞 Revit 主线程时，代理仍有机会读取并处理窗口。详见[架构说明](docs/ARCHITECTURE.md)。

## 安装与首次使用

1. 准备已授权的 Revit 2020、兼容命令插件、Node.js 24 x64、Python 3.11+、.NET SDK 和 .NET Framework 4.8 targeting pack。
2. 克隆仓库，生成本地设置并安装锁定依赖。
3. 构建宿主；在 Revit 全部正常关闭后注册加载项和按需启动任务。
4. 将 MCP 客户端指向私有运行时和 `src/server.mjs`，重新连接一次以刷新工具清单。

**逐条可执行的命令、依赖接口要求、安装影响和回滚步骤见[安装指南](docs/INSTALLATION.md)。** 这里不是免依赖的双击安装包。

可向支持 MCP 的 AI 客户端发出这样的任务：

> 查看受管 Revit 的状态。如果尚未启动，读取默认测试模型的当前视图。遇到普通提示，通过 MCP 处理，并继续取回原操作结果。

或者直接使用工具：

```json
{"name":"get_revit_automation_status","arguments":{}}
```

状态查询不会启动 Revit；`get_current_view_info` 等模型操作会按需启动。需要指定模型时：

```json
{"name":"open_revit_model","arguments":{"path":"C:\\BIM\\Sandbox\\Example.rvt"}}
```

## 弹窗处理规则

- 已知提示依据对话框 ID、消息内容和按钮类型匹配；缺失参照继续打开后，仍需核对模型完整性。
- 多选窗口由代理先读取，再依据用户已有任务授权选择。`click_revit_dialog_button` 要求窗口句柄、按钮 ID、快照 hash 和选择理由。
- 不把所有 `Dialog_Revit_DocWarnDialog` 都当作“确定”：同一个 ID 也可能出现“删除图元”。
- 删除、覆盖、丢弃未保存修改、登录、许可和安全授权不属于自动确认范围；超出既有任务授权时仍需用户决定。
- 收到 `waiting_for_dialog` 后，使用 `get_revit_operation_result` 获取原结果，**不要重新提交原建模命令**。

详见[弹窗工作流与示例](docs/DIALOGS.md)。

## 验证状态与适用范围

2026-10-28 的本机真实 Revit 验收覆盖冷启动、模型/视图读取、C# 执行、重连复用、指定模型打开、正常退出后重启、真实弹窗点击，以及原命令只创建一个测试标高。15 项 Node 检查和 10 项 C# 弹窗策略检查通过，23 个原插件文件的哈希保持不变。

验证结论见[验证说明](docs/VERIFICATION.md)。测试脚本、测试模型和原始报告保留在本地，不随公开仓库发布。

当前边界：

- 只验证 **Revit 2020 + Windows x64**；启动参数为简体中文 `CHS`，规则包含部分英文匹配，未完成其他语言的实机验收。
- 需要已登录的交互式 Windows 桌面；不提供无界面服务、远程多用户调度或无人值守授权登录。
- 依赖现有插件的内部 `SocketService` 接口，替换插件版本需要重新验证；并非任意 Revit MCP 插件都可直接接入。
- 启动锁跨 MCP 进程协调；模型命令队列位于各 Broker 进程，**不是多客户端全局事务队列**。同一模型应由一个写入客户端协调。
- 超时和连接丢失不会自动重放写操作；这减少重复写入风险，**不等于跨崩溃的 exactly-once 保证**。
- 可读取到的原生窗口、按钮和策略范围有限；尚不能保证自动解决全部第三方插件窗口或系统安全桌面。
- `send_code_to_revit` 可执行 C#，具有当前用户和 Revit 的权限；本集成不是代码沙箱。

## 仓库导航

| 位置 | 内容 |
| --- | --- |
| `src/` | MCP 服务、实例 Broker、弹窗协调、C# 宿主与策略 |
| `scripts/` | 本地初始化、依赖适配、构建、安装、弹窗操作、回滚 |
| `examples/` | 不含个人路径的设置和 Codex 配置示例 |
| `docs/` | 安装、架构、工具、弹窗流程与验证说明 |

[参与开发](CONTRIBUTING.md) · [安全与权限](SECURITY.md) · [第三方依赖声明](THIRD_PARTY_NOTICES.md) · [版本记录](CHANGELOG.md)

本项目自研代码采用 [MIT License](LICENSE)。Revit 与 Autodesk 名称属于其各自权利人；本项目为独立社区项目。