# MicroStation V8i MCP Server

Cầu nối chuyên nghiệp theo chuẩn **Model Context Protocol (MCP)** giữa các Trợ lý AI (Google Antigravity, Anthropic Claude, Cursor, v.v.) và phần mềm thiết kế kỹ thuật **Bentley MicroStation V8i (SELECTseries)**.

---

## 🌟 Tính Năng Chính

- **Hệ thống 133 công cụ CAD chuyên sâu:** Bao phủ từ dựng hình 2D/3D, đo đạc kích thước, chỉnh sửa đối tượng, điều khiển khung nhìn, quản lý file/model/reference đến xử lý dữ liệu hàng loạt.
- **Kiến trúc Dual-Mode hiệu năng cao (High Performance & Zero Overhead):**
  - **Mode 1 (Native IPC - Khuyến nghị):** Giao tiếp trực tiếp với MicroStation V8i qua ứng dụng **MDL C++ Native (`MsNativePipe.ma`)** bằng **Windows Named Pipe** (`\\.\pipe\MsNativeMCP`). Tốc độ thực thi tiệm cận native (~0.05-0.2ms/call, nhanh hơn COM 10-50x), hỗ trợ **Batch Draw** (tạo hàng trăm đối tượng trong 1 transaction/round-trip), và **Undo Groups**.
  - **Mode 2 (COM Fallback):** Tự động chuyển đổi hoặc dùng song song khi chưa load MDL application, bảo đảm tính sẵn sàng 100%.
- **Công cụ bảo toàn ngữ cảnh & phòng ngừa sai lệch:** Cung cấp `get_model_snapshot` và `native_get_active_settings` giúp AI nắm bắt trạng thái thực tế của bản vẽ (bounding box, element count, active symbology) trước khi vẽ.
- **Hỗ trợ đầy đủ bộ ba MCP:**
  - **Tools (133 công cụ):** Toàn bộ primitive CAD 2D/3D, batch native, transaction control, và COM tools.
  - **Resources:** Cung cấp thông tin trực tiếp về bản vẽ (`ms://drawing/info`), danh sách level (`ms://drawing/levels`), trạng thái active (`ms://drawing/settings`).
  - **Prompts:** Khuôn mẫu hướng dẫn quy trình vẽ kỹ thuật (`cad_drawing_workflow`) và kiểm toán bản vẽ (`element_inspection`).
- **Đa kênh truyền tải (Transports):** Hỗ trợ cả `stdio` (cho Antigravity / Claude Desktop) và `sse` (Server-Sent Events qua HTTP).
- **An toàn luồng:** Quản lý an toàn luồng Overlapped I/O cho Named Pipe và COM Apartment riêng biệt trên từng worker thread.
- **Logging an toàn:** Toàn bộ log được định tuyến ra `sys.stderr`, bảo toàn 100% định dạng JSON-RPC trên kênh `stdout`.

---

## ⚡ So Sánh Hiệu Năng (COM vs MDL Named Pipe)

| Thao tác | COM Out-of-Process | MDL Native Named Pipe | Cải thiện |
|---|---|---|---|
| Vẽ 1 đoạn thẳng (`draw_line`) | ~3.0 ms | **~0.15 ms** | **20x nhanh hơn** |
| Tạo 100 đoạn thẳng tuần tự | ~300 ms | **~15 ms** | **20x nhanh hơn** |
| Batch tạo 100 đối tượng hỗn hợp | ~300 ms (100 calls) | **~3 ms** (1 round-trip) | **100x nhanh hơn** |
| Quét 500 phần tử (`scan_elements`) | ~2,000 ms | **~50 ms** | **40x nhanh hơn** |
| Lấy snapshot model (`get_model_snapshot`) | ~10,000 ms | **~200 ms** | **50x nhanh hơn** |
| Giao dịch Undo/Redo | Không hỗ trợ native | `begin_transaction` / `end_transaction` | **Native Undo Group** |

---

## 📁 Cấu Trúc Thư Mục

```text
microstation-mcp/
├── README.md                   # Tài liệu tổng quan & hướng dẫn cài đặt
├── AGENTS.md                   # Cẩm nang chỉ dẫn cho AI Agent
├── pyproject.toml              # Metadata dự án chuẩn PEP 621
├── requirements.txt            # Thư viện phụ thuộc
│
├── mdl/                        # Ứng dụng C++ Native chạy trong ustation.exe
│   ├── build_instructions.md   # Hướng dẫn biên dịch chi tiết (VS2005/2008 + V8i SDK)
│   └── MsNativePipe/
│       ├── MsNativePipe.mke    # Makefile bmake cho MDL
│       ├── MsNativePipe.cpp    # Entry point MdlMain, Timer loop
│       ├── pipe_server.h/.cpp  # Named Pipe Server (Overlapped I/O, Thread-safe)
│       ├── handlers.h/.cpp     # Dispatcher & 25 CAD Command Handlers
│       ├── geometry.h/.cpp     # MDL Geometry APIs (Native primitives & transforms)
│       ├── batch.h/.cpp        # Batch creation & Undo grouping
│       └── json_lite.h         # Header-only JSON parser/builder (zero dependency)
│
├── docs/                       # Tài liệu thiết kế nội bộ
│   ├── architecture_native.md  # Kiến trúc chi tiết luồng IPC và Wire Protocol
│   ├── architecture.md         # Kiến trúc phân tầng
│   └── features.md             # Danh mục công cụ
│
└── src/
    ├── main.py                 # Entry point chính (hỗ trợ --transport stdio|sse)
    ├── core/                   # Cầu nối IPC (Named Pipe client & COM bridge)
    │   ├── pipe_client.py      # Win32 Named Pipe client với auto-reconnect
    │   ├── _pipe_singleton.py  # Singleton quản lý kết nối pipe
    │   └── ms_bridge.py        # COM bridge fallback
    ├── server/                 # McpServer factory, logging, context
    ├── tools/                  # 18 module công cụ CAD (133 tools)
    │   ├── native_batch.py     # Batch, transaction & snapshot tools (Native)
    │   ├── drawing_native.py   # Primitive drawing tools (Native)
    │   └── ...                 # Các công cụ COM hiện hữu
    ├── resources/              # Dynamic Resources
    ├── prompts/                # CAD Prompt templates
    └── transports/             # Kênh truyền tải stdio và sse
```

---

## 🚀 Cài Đặt & Cấu Hình

### 1. Cài đặt thư viện phụ thuộc
```bash
pip install -r requirements.txt
```

### 2. Cấu hình MCP Client (Antigravity / Claude Desktop)
```json
{
  "mcpServers": {
    "microstation-v8i": {
      "command": "python",
      "args": [
        "-X",
        "utf8",
        "{path}\\microstation-mcp\\src\\main.py"
      ]
    }
  }
}
```

### 3. Chạy độc lập qua giao thức SSE (Tùy chọn)
```bash
python src/main.py --transport sse --host 127.0.0.1 --port 8000
```