Content
# vn-sketchup-mcp
Điều khiển **SketchUp** từ **Claude Code / Codex / Antigravity** (và mọi MCP client dùng stdio) thông qua Model Context Protocol.
Bản Việt hoá + **đã vá lỗi** của [mhyrr/sketchup-mcp](https://github.com/mhyrr/sketchup-mcp): cài phát chạy ngay, không còn crash do lệch phiên bản thư viện `mcp`.
> Control SketchUp from Claude Code / Codex / Antigravity via MCP. A fixed, ready-to-run fork of mhyrr/sketchup-mcp.
---
## Vá gì so với bản gốc? (What is fixed)
Bản gốc crash ngay khi khởi động server vì:
1. Nó `import mcp.server.fastmcp` (lớp `FastMCP`). Nhưng thư viện `mcp` bản **2.x** đã **đổi tên** `FastMCP` -> `MCPServer`, xoá `mcp.server.fastmcp`. Khi cài bằng `uvx`/`pip` không ghim phiên bản, máy kéo về `mcp 2.x` -> **ModuleNotFoundError / crash** -> MCP client báo `Connection closed`.
2. Gói trên PyPI còn dùng API cũ `FastMCP(description=...)` (đã bỏ), lỗi `unexpected keyword argument 'description'`.
**Cách vá ở repo này:**
- `pyproject.toml` **ghim `mcp[cli]>=1.3,<2`** -> luôn cài `mcp 1.x` còn `FastMCP`.
- Dùng `server.py` bản mới (đã đổi sang `FastMCP(instructions=...)`, hợp lệ với `mcp 1.x`).
- Kèm **installer 1 lệnh** tự copy plugin Ruby vào mọi bản SketchUp + in sẵn cấu hình cho 3 client.
Kết quả: `uv run vn-sketchup-mcp` chạy ổn, kết nối được SketchUp (đã kiểm chứng trên **SketchUp Pro 2018**, Ruby 2.2.4; và các bản mới hơn).
---
## Kiến trúc (How it works)
Gồm 2 phần:
1. **Plugin SketchUp (Ruby)** — chạy 1 TCP server bên trong SketchUp ở cổng **9876**, nhận lệnh và thao tác model.
2. **MCP server (Python)** — client (Claude Code/Codex/Antigravity) chạy qua stdio; nó nối tới cổng 9876 để đẩy lệnh vào SketchUp.
```
Claude Code / Codex / Antigravity <--stdio--> vn-sketchup-mcp (Python) <--TCP:9876--> SketchUp (Ruby plugin)
```
## Yêu cầu
- [**uv**](https://docs.astral.sh/uv/) (tự tải Python 3.12, không cần cài Python riêng)
- **git**
- **SketchUp** (Pro để dùng được đủ Solid Tools; đã test 2018+)
---
## Cài đặt (Install)
### 1. Clone
```bash
git clone https://github.com/andyluu98/vn-sketchup-mcp.git
cd vn-sketchup-mcp
```
### 2. Chạy installer (khuyên dùng)
**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```
**macOS / Linux:**
```bash
bash install.sh
```
Installer sẽ: cài `uv` nếu thiếu -> `uv sync` (ghim `mcp<2`) -> copy plugin Ruby vào **mọi bản SketchUp** phát hiện được -> in sẵn **cấu hình MCP**.
### 3. Bật server trong SketchUp
Mở SketchUp -> menu **Extensions > MCP Server > Start Server**.
Ruby Console hiện `Server created on port 9876` là OK. Giữ SketchUp mở khi dùng.
---
## Đăng ký MCP cho từng client
Cấu hình **cùng một dạng** cho cả 3 (thay `<REPO>` = đường dẫn tuyệt đối bạn đã clone):
```json
{
"mcpServers": {
"sketchup": {
"command": "uv",
"args": ["run", "--directory", "<REPO>", "vn-sketchup-mcp"]
}
}
}
```
- **Claude Code**: thêm vào `~/.claude.json` (mục `mcpServers`) hoặc chạy:
```bash
claude mcp add sketchup -- uv run --directory <REPO> vn-sketchup-mcp
```
- **Codex**: thêm MCP server dạng trên vào cấu hình Codex (`~/.codex/config.toml` phần `[mcp_servers]` hoặc file cấu hình MCP tương ứng).
- **Antigravity**: thêm cùng khối `mcpServers` vào phần cấu hình MCP của Antigravity.
Sau khi thêm, **khởi động lại client**. Nhớ SketchUp đang mở + đã Start Server.
> Nếu `uv` không nằm trong PATH của client, thay `"command": "uv"` bằng đường dẫn tuyệt đối tới `uv` (vd `C:\\Users\\<ban>\\.local\\bin\\uv.exe`).
---
## Công cụ (MCP tools)
| Tool | Mô tả |
|------|-------|
| `create_component` | Tạo khối cơ bản (cube...) theo vị trí/kích thước |
| `delete_component` | Xoá đối tượng |
| `transform_component` | Di chuyển/xoay/scale |
| `get_selection` | Lấy các đối tượng đang chọn |
| `set_material` | Gán vật liệu/màu |
| `export_scene` | Xuất scene |
| `eval_ruby` | **Chạy Ruby tuỳ ý trong SketchUp** (mạnh nhất: dựng mọi hình học qua SketchUp Ruby API) |
| `create_mortise_tenon`, `create_dovetail`, `create_finger_joint` | Mộng ghép gỗ |
`eval_ruby` là công cụ linh hoạt nhất: bạn mô tả, agent sinh Ruby dựng nhà/nội thất trực tiếp trong SketchUp.
---
## Xử lý sự cố (Troubleshooting)
| Triệu chứng | Nguyên nhân / Cách xử lý |
|-------------|--------------------------|
| Client báo `Connection closed` khi khởi động | Thường do `mcp 2.x`. Repo này đã ghim `mcp<2`; chạy lại `uv sync`. |
| `No module named 'mcp.server.fastmcp'` | Đang dùng `mcp 2.x`. `uv sync` trong repo này để về `mcp 1.x`. |
| Không thấy menu **Extensions > MCP Server** | Plugin chưa cài. Chạy lại installer, hoặc `Window > Extension Manager` bật "Sketchup MCP Server". |
| Gọi tool báo lỗi kết nối | Chưa bấm **Start Server** trong SketchUp, hoặc SketchUp đã đóng. |
| Lệnh đầu tiên sau khi kết nối lỗi lạ | Thử lại lần nữa (request đầu ngay sau bắt tay đôi khi chập). |
---
## Ghi công (Credits)
- Fork từ [**mhyrr/sketchup-mcp**](https://github.com/mhyrr/sketchup-mcp) (MIT).
- Việt hoá, vá lỗi phiên bản `mcp`, thêm installer đa client: **andyluu98**.
MIT License.
MCP Store