# 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.