# vn-revit-mcp

**Cho AI làm việc với Autodesk Revit.** Mã nguồn mở, miễn phí, do [InnoPro](https://innopro.vn) phát triển.

- **Một lệnh cài**, tự kết nối mọi AI trên máy: Claude, Cursor, VS Code Copilot, Gemini CLI, Codex, LM Studio...
- **Chat ngay trong Revit** với Claude, OpenAI, Gemini, DeepSeek, Qwen, Kimi, GLM..., hoặc AI chạy trên máy; dùng được tài khoản Claude, kể cả gói Free, qua Claude Desktop.
- **Mỗi lệnh dùng được hai cách:** người bấm nút trên tab **InnoPro** (form nhập tự sinh), hoặc AI gọi.
- **Viết lệnh mới bằng một file `.cs`**, không cần build: thả vào thư mục, bấm *Nạp lại lệnh*. Hoặc nhờ AI viết.
- **Tiết kiệm token:** AI chỉ thấy vài lệnh hay dùng, tra thêm khi cần; kết quả trả dạng bảng gọn.
- **Làm được cả việc không có API:** "bàn tay ảo" chạy lệnh có sẵn của Revit và bấm vào view như người dùng (vd dim, vẽ), tự kiểm tra kết quả; AI nhìn được view qua ảnh.
- **Hiểu Revit sâu:** tra Revit API của bản cài trên máy kèm bài The Building Coder, bộ kỹ năng đã kiểm chứng (`revit_skill`).
- **Tự cập nhật và nạp nóng:** server, add-in, tiện ích tự lên bản mới (kiểm SHA-256); Revit đang mở tự chuyển sang bản mới, không cần tắt.
- **Cửa hàng tiện ích:** cài thêm bộ lệnh (vd Mô phỏng 4D) bằng một câu nói với AI.
- Chạy trên máy bạn, không mở cổng mạng. Lệnh sửa mô hình Undo được. Revit **2025 trở lên**.

## Cài đặt

**Cách dễ nhất: nhờ AI cài.** Gõ vào Claude Code, Codex, Gemini CLI, Cursor hoặc Copilot (chế độ agent):

> Cài vn-revit-mcp cho Revit theo hướng dẫn ở github.com/Innoprovn/vn-revit-mcp

AI tự cài, tự kiểm tra bằng `vn-revit-mcp doctor` và tự sửa nếu có lỗi (hướng dẫn cho AI: [llms.txt](llms.txt)).

Hoặc tự cài:

mở **PowerShell** và chạy (không cần quyền admin; Revit đang mở thì lần đầu mở lại Revit để có tab InnoPro):

```powershell
irm https://raw.githubusercontent.com/Innoprovn/vn-revit-mcp/main/install.ps1 | iex
```

Hoặc tải `vn-revit-mcp-<phiên bản>-win-x64.zip` ở [Releases](https://github.com/Innoprovn/vn-revit-mcp/releases),
giải nén rồi bấm đúp **`Cai-dat.cmd`**.

**Dùng Claude Desktop:** tải `vn-revit-mcp-<phiên bản>.mcpb` ở [Releases](https://github.com/Innoprovn/vn-revit-mcp/releases)
rồi bấm đúp (hoặc Claude Desktop → Settings → Extensions → Install Extension). Extension tự cài add-in Revit ở lần chạy đầu.

Xong: mở Revit, tab **InnoPro**. Dùng theo một trong ba cách:
- **Chat trong Revit:** bấm **Chat AI**, chọn nhà cung cấp, nhập API key. Có Claude, OpenAI, Gemini, DeepSeek, Qwen, Kimi,
  GLM, MiniMax, OpenRouter, hoặc AI chạy trên máy (Ollama, LM Studio) không cần key.
- **Tài khoản Claude (Free, Pro, Max):** trong khung chat chọn *Claude Desktop (Free/Pro/Max)* → *Kết nối và mở Claude*. Gói Free có hạn mức thấp, đủ để thử.
- **Claude Code đã đăng nhập:** trong khung chat chọn *Claude Code (tài khoản đang đăng nhập)*, hỏi ngay trong Revit, không cần API key (dùng gói Claude của máy).
- **AI bên ngoài** (Claude Desktop, Cursor, VS Code...): đã tự kết nối khi cài; khởi động lại ứng dụng AI rồi hỏi.

Hướng dẫn chi tiết: [docs/huong-dan-su-dung.md](docs/huong-dan-su-dung.md). Dựng hình từ CAD: [docs/dung-hinh-tu-cad.md](docs/dung-hinh-tu-cad.md).

| Việc | Cách làm |
|---|---|
| Kết nối thêm AI client | nút **Hệ thống → Kết nối AI** trong Revit |
| Cập nhật | **tự động**: mỗi khi mở Revit hoặc AI, tối đa 12 giờ/lần (kiểm SHA-256, tiện ích marketplace cũng tự lên bản mới). Cập nhật ngay: `vn-revit-mcp.exe update`. Tắt: biến môi trường `VN_REVIT_MCP_AUTO_UPDATE=0` |
| Gỡ cài đặt | `uninstall.ps1` trong file zip (thêm `-Purge` để xóa cả lệnh tự thêm) |
| Hộp thoại "Load Once" của Revit | Bộ cài ghi sẵn lựa chọn *Always Load* cho vn-revit-mcp nên Revit không hỏi. Muốn Revit hỏi: cài với `-NoTrust`. Ký số: [chính sách](docs/code-signing-policy.md) |

AI client khác: khai báo MCP server kiểu **stdio**, command `%LOCALAPPDATA%\InnoPro\vn-revit-mcp\current\server\vn-revit-mcp.exe`.
Mở nhiều Revit cùng lúc: AI tự làm việc với Revit bạn thao tác gần nhất; muốn đổi thì nói với AI (vd "làm trên Revit 2025").

## Có những gì (100+ lệnh)

| Nhóm | Ví dụ |
|---|---|
| Truy vấn, Tham số | thông tin dự án/view, phần tử đang chọn, tìm phần tử, tham số, thống kê; sửa tham số hàng loạt |
| QA-QC | cảnh báo, phần tử trùng (tìm/xóa), tham số trống, va chạm, va chạm với link, sức khỏe mô hình, dim tới trục |
| Dựng hình | tầng, lưới trục, tường, dầm, sàn, đặt family; sàn theo dầm, gộp/tách sàn, tự join, lớp hoàn thiện tường |
| Dựng hình CAD | tường, sàn/trần, cột, dầm, cọc + đài, cửa từ bản vẽ CAD; tạo type dầm từ mặt cắt |
| Rebar | thống kê kiểu BBS, chọn nhanh, ngắt/gắn host, dịch thép, tránh va chạm, QA thép, so sánh thay đổi, thư viện hình dạng |
| Bản vẽ | tạo sheet, đặt view, nhân bản view, gán template, tag tự động, dim trục, xuất PDF |
| Dữ liệu | đọc/xuất schedule, khối lượng vật liệu, chiều dài tường, danh sách sheet, tìm phần tử trong link |
| Nâng cao | `run_csharp`: AI chạy mã C#; mặc định chỉ đọc; mode=write sửa mô hình ngay, Undo được |

Ribbon gọn: vài nút nhỏ mỗi nhóm, mọi lệnh khác trong menu **Tất cả**. Thêm lệnh từ **Cửa hàng** (cộng đồng đóng góp).

**Công thức** (MCP prompts, ví dụ gõ `/` trong Claude): `kiem-tra-chat-luong`, `boc-khoi-luong`, `dung-tang-luoi-truc`,
`viet-lenh-moi`. Mỗi công thức là một file Markdown, ai cũng viết thêm được.
## Viết lệnh mới

Cách nhanh nhất: một file `.cs`, không cần project hay build.

```csharp
public sealed class CountWalls : RevitCommandBase
{
    public override string Name => "count_walls";
    public override string Category => "Của tôi";
    public override string Description => "Đếm số tường trong mô hình.";
    public override RibbonButton Ribbon => new("Đếm\ntường", "#");   // có nút trên ribbon

    public override object Execute(RevitCommandContext context, JsonElement arguments) =>
        new { count = new FilteredElementCollector(context.Document).OfClass(typeof(Wall)).GetElementCount() };
}
```

Thả vào `%LOCALAPPDATA%\InnoPro\vn-revit-mcp\Scripts\`, bấm **Nạp lại lệnh**. Lệnh có nút, có form nhập, và AI gọi được ngay.
Không biết code: dùng công thức `viet-lenh-moi` hoặc nói với AI *"viết cho tôi lệnh vn-revit-mcp ..."*.

Hướng dẫn đầy đủ (3 cấp: file `.cs`, CommandSet, đóng góp): [docs/viet-lenh-moi.md](docs/viet-lenh-moi.md).
AI lập trình (Claude Code, Cursor, Copilot, Codex...) đọc [AGENTS.md](AGENTS.md).

## Kiến trúc

```
AI client ──MCP (stdio)──▶ vn-revit-mcp.exe ──named pipe──▶ Add-in InnoPro (trong Revit) ──▶ Revit API
Khung chat trong Revit ──────────────────────────────────────▲      ├─ CommandSet (DLL)
                                                                    └─ Scripts (*.cs, tự biên dịch)
```

| Thành phần | Vai trò |
|---|---|
| `src/InnoPro.Revit.Sdk` | Interface viết lệnh: `RevitCommandBase`, `Args`, `Table`, `Lookup`, `UnitConvert` |
| `src/InnoPro.Revit.Loader` | Bộ nạp (InnoPro.Revit.Addin.dll): Revit nạp trực tiếp, tự nạp nóng lõi khi có bản mới |
| `src/InnoPro.Revit.Addin` | Lõi (InnoPro.Revit.Core.dll): ribbon tự sinh, form tự sinh, nạp lệnh nóng, cầu nối, khung chat |
| `src/InnoPro.Revit.Chat` | Module chat (nạp riêng): Claude qua SDK Anthropic, các AI khác qua API OpenAI-compatible |
| `src/InnoPro.Bridge` | Giao thức named pipe, tra cứu lệnh dùng chung |
| `src/InnoPro.Mcp.Server` | MCP server, công thức, lệnh `setup` cấu hình AI client |
| `src/InnoPro.Revit.Commands.*` | CommandSet đi kèm: Core, QA-QC, Modeling, Data, Code |

Chi tiết: [docs/kien-truc.md](docs/kien-truc.md).

## Cho nhà phát triển

Cần [.NET SDK 8](https://dotnet.microsoft.com/download).

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install-dev.ps1   # build + cài bản "dev", cùng bố cục với người dùng
powershell -ExecutionPolicy Bypass -File scripts\dev-reload.ps1    # sửa CommandSet: Revit đang mở nạp lại ngay
powershell -ExecutionPolicy Bypass -File scripts\package.ps1       # đóng gói artifacts\release\*.zip
```

Lõi, SDK, Bridge, module chat cũng được nạp nóng (bộ nạp tự đổi lõi khi Revit rảnh). Chỉ khi sửa bộ nạp (`InnoPro.Revit.Loader`) mới cần chạy `install-dev.ps1` rồi mở lại Revit.

## Lộ trình

| Giai đoạn | Nội dung | Trạng thái |
|---|---|---|
| P0 | Add-in, tab InnoPro, cầu nối, MCP server | ✅ |
| P1 | CommandSet Core, QA-QC, Modeling, Data, Code; lệnh từ file `.cs`; nút và form tự sinh; tiết kiệm token | ✅ (đang mở rộng) |
| P2 | Khung chat trong Revit đa nhà cung cấp | ✅ bản đầu |
| P3 | Bộ cài một dòng, tự cấu hình AI client; phát hành GitHub, MCP Registry, tự cập nhật | ✅ |
| P4 | Bộ lệnh chuyên sâu (Kết cấu, Rebar, Bản vẽ, vẽ từ CAD); cửa hàng lệnh cộng đồng | ⏳ |

## Đóng góp

Mọi người đều có thể đóng góp lệnh, CommandSet, công thức. Mở issue hoặc pull request.

## License

Ký số miễn phí bởi [SignPath.io](https://about.signpath.io), chứng chỉ của [SignPath Foundation](https://signpath.org) (đang đăng ký) — [chính sách ký số](docs/code-signing-policy.md).


[GPLv3](LICENSE) kèm [ngoại lệ plugin](LICENSE-EXCEPTION.md): CommandSet và file lệnh của bạn được giữ license riêng
(kể cả đóng mã nguồn), và được phép chạy cùng Autodesk Revit.

Một số lệnh tham khảo đặc tả từ [mcp-servers-for-revit](https://github.com/mcp-servers-for-revit) (MIT).
Đọc chữ và leader trong file DWG/DXF dùng [ACadSharp](https://github.com/DomCR/ACadSharp) (MIT).

---

# English

**vn-revit-mcp** lets AI work with Autodesk Revit 2025+. One-line install (no admin):
`irm https://raw.githubusercontent.com/Innoprovn/vn-revit-mcp/main/install.ps1 | iex` — it registers the MCP server
with every detected AI client (Claude Desktop/Code, Cursor, VS Code, Windsurf, Gemini CLI, LM Studio, Codex CLI, Cline).
Inside Revit, an **InnoPro** tab offers a chat pane (Claude via the Anthropic SDK; OpenAI, Gemini, OpenRouter, Ollama,
LM Studio via OpenAI-compatible APIs) and a button for every command with an auto-generated input form.
Add a command by dropping a single `.cs` file into the Scripts folder — it is compiled in Revit and hot-reloaded.
**AI agents installing this for a user:** follow [llms.txt](llms.txt) (install one-liner, then `vn-revit-mcp doctor --json` and apply each `fix`).
Licensed GPLv3 with a plugin exception. See [AGENTS.md](AGENTS.md) for AI coding agents working on the code.