OpenSCAD Design MCP

Nhờ AI tạo mô hình 3D, xem trước và xuất tệp để chuẩn bị in.

Hướng dẫn cho Windows 10/11 · Không cần biết lập trình để bắt đầu sử dụng

Bạn mô tả vật muốn tạo bằng lời, chẳng hạn “tạo một hộp không nắp, dài 60 mm, rộng 40 mm, cao 25 mm”. Ứng dụng AI dùng OpenSCAD Design MCP để dựng mô hình, tạo ảnh xem trước và kiểm tra kích thước. Bạn xem ảnh, yêu cầu sửa rồi lấy tệp để mở trong phần mềm in 3D.

Đây là công cụ bổ sung cho ứng dụng AI, không có cửa sổ trò chuyện riêng. MCP là cách để ứng dụng AI gọi các công cụ trên máy của bạn. Bạn chỉ cần kết nối một lần theo hướng dẫn dưới đây.

Bắt đầu từ đâu?

Nếu gặp lỗi, xem cách xử lý. Nếu đã cài dự án ở D:\Code\openscad-design-mcp, mở PowerShell, chạy cd D:\Code\openscad-design-mcp rồi bắt đầu từ bước chạy thử.

1. Cài đặt lần đầu

Cài ba phần mềm sau bằng bộ cài dành cho Windows:

Phần mềm	Dùng để làm gì?	Lưu ý
Python	Chạy công cụ này	Phiên bản 3.11 trở lên; nếu bộ cài có Add Python to PATH, hãy chọn
OpenSCAD	Dựng mô hình và tạo ảnh	Có thể dùng vị trí cài mặc định
Git	Tải dự án từ GitHub	Có thể giữ các lựa chọn mặc định của bộ cài

Bạn cũng cần một ứng dụng AI hỗ trợ MCP, ví dụ Antigravity, Codex, OpenCode hoặc Claude Desktop. Tài khoản và chi phí sử dụng AI tùy ứng dụng; dự án này không cung cấp tài khoản AI.

Nhấn phím Windows, tìm PowerShell và mở nó. Nếu vừa cài phần mềm, đóng cửa sổ PowerShell cũ rồi mở cửa sổ mới.

Cách dùng các khung lệnh: sao chép phần bên trong khung, dán vào PowerShell, nhấn Enter và chờ chạy xong. Không sao chép dấu ba gạch ngược. Khi xuất hiện lại dòng bắt đầu bằng PS ...>, bạn có thể chạy bước tiếp theo. Nếu có lỗi, xử lý lỗi trước khi tiếp tục.

Kiểm tra Python và Git:

python --version
git --version

Tải dự án vào thư mục người dùng Windows:

cd $env:USERPROFILE
git clone https://github.com/tomyrese/openscad-design-mcp.git
cd openscad-design-mcp

Nếu Git báo thư mục đã tồn tại, hãy mở bản đã tải trước đó; không cần xóa thư mục để cài lại.

Tạo môi trường riêng và cài công cụ:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

.venv là thư mục chứa Python và thư viện riêng cho dự án. Các lệnh dưới đây dùng trực tiếp Python trong thư mục này, nên bạn không cần chạy lệnh “activate”. Lần cài đầu cần Internet để tải thư viện.

2. Chạy thử trước khi kết nối AI

Trong PowerShell đang mở tại thư mục dự án, chạy:

.\.venv\Scripts\python.exe examples\cube_workflow.py

Chương trình tự tạo một khối 20 × 20 × 10 mm, tạo ảnh xem trước, xuất STL và chạy kiểm tra. Hãy chờ đến khi lệnh kết thúc. Kết quả thành công có trường "success": true; nhiều dòng dữ liệu trong cửa sổ là bình thường.

Mở thư mục kết quả:

explorer .\workspace\projects

Mở thư mục dự án vừa tạo, rồi mở thư mục previews để xem ảnh PNG. Mỗi lần chạy mẫu sẽ tạo một dự án mới. Nếu bước này lỗi, xem xử lý sự cố trước khi cấu hình AI.

3. Kết nối với ứng dụng AI

Đầu tiên, tạo tệp cấu hình mẫu có đường dẫn đúng trên máy bạn:

.\.venv\Scripts\python.exe examples\client_configs.py
explorer .\workspace\client-configs

Lệnh này chỉ tạo mẫu, chưa thay đổi thiết lập của ứng dụng AI. Mở mẫu bằng Notepad rồi làm theo hướng dẫn tương ứng:

Bạn đang dùng	Mẫu cần mở	Hướng dẫn
Antigravity IDE	`antigravity-claude.json`	Kết nối Antigravity IDE
Antigravity CLI	`antigravity-claude.json`	Kết nối Antigravity CLI
Codex app hoặc CLI	`codex.toml`	Kết nối Codex
OpenCode	`opencode-v1.json` hoặc `opencode-v2.json`	Chọn phiên bản và kết nối
Claude Desktop	`antigravity-claude.json`	Kết nối Claude Desktop

Nếu ứng dụng đã có cấu hình, chỉ thêm mục openscad-design; đừng thay toàn bộ tệp và làm mất thiết lập cũ. Nếu đổi vị trí thư mục dự án hoặc cài lại Python/OpenSCAD, hãy tạo lại mẫu và cập nhật trong ứng dụng.

Khởi động lại ứng dụng AI, mở cuộc trò chuyện mới và gửi:

Dùng công cụ openscad-design gọi get_system_status. Cho tôi biết có tìm thấy OpenSCAD và có tạo được ảnh PNG hay không. Hãy gọi công cụ thật, không chỉ hướng dẫn tôi chạy lệnh.

Ứng dụng AI sẽ tự khởi chạy MCP khi cần. Bạn không cần giữ PowerShell chạy máy chủ mỗi lần sử dụng.

4. Tạo mô hình đầu tiên

Thử gửi yêu cầu này trong ứng dụng AI đã kết nối:

Tạo một hộp chữ nhật không nắp, kích thước bên ngoài 60 × 40 × 25 mm, thành và đáy dày 2 mm. Dùng openscad-design, tạo ảnh từ 6 góc để tôi xem. Kiểm tra kích thước bên ngoài và độ kín của mô hình trước khi xuất STL. Cho tôi đường dẫn ảnh, tệp STL và kết quả kiểm tra.

Xem ảnh rồi yêu cầu chỉnh sửa, ví dụ:

Giữ chiều dài và chiều rộng, tăng chiều cao lên 30 mm. Lưu thành phiên bản mới, tạo lại ảnh và kiểm tra lại kích thước.

Để kết quả sát nhu cầu, nêu rõ đơn vị, kích thước bên ngoài hay bên trong, độ dày, lỗ bắt vít và những phần cần lắp với nhau. Nếu chưa biết kích thước, hãy yêu cầu AI hỏi bạn trước khi thiết kế.

Với khung drone, hãy phân biệt đường kính động cơ với đường kính cánh quạt, và khoảng cách chéo giữa tâm động cơ với kích thước bao ngoài. Những con số này không thể dùng thay cho nhau.

5. Ảnh và tệp nằm ở đâu?

Mặc định, các mẫu cấu hình lưu dữ liệu tại workspace bên trong thư mục dự án. Mỗi thiết kế có thư mục riêng trong workspace\projects.

Thư mục hoặc tệp	Nội dung	Cách sử dụng
`previews`	Ảnh PNG của mô hình	Nhấp đúp để xem
`exports`	Tệp mô hình đã xuất, như STL hoặc 3MF	Mở bằng phần mềm chuẩn bị in của bạn
`reports`	Kết quả kiểm tra dạng JSON	Có thể yêu cầu AI giải thích bằng lời
`versions`	Các phiên bản đã lưu	Yêu cầu AI khôi phục một phiên bản cũ

Bạn có thể hỏi AI: “Cho tôi đường dẫn đầy đủ của ảnh và STL mới nhất”. Sao lưu cả thư mục workspace nếu muốn giữ thiết kế và lịch sử. Khi xóa dự án bằng công cụ, dữ liệu được chuyển sang workspace\trash.

STL/3MF chưa phải lệnh chạy máy in. Bạn cần mở tệp trong phần mềm slicer của máy in, chọn vật liệu và thông số in, xem trước các lớp rồi mới gửi sang máy in.

Khi gặp lỗi

Hiện tượng	Cách xử lý
Không nhận lệnh `python` hoặc `git`	Kiểm tra đã cài phần mềm, mở PowerShell mới rồi thử lại
Không tìm thấy `.venv\Scripts\python.exe`	Mở đúng thư mục dự án; nếu chưa có `.venv`, làm lại bước tạo môi trường
`No module named openscad_design_mcp`	Chạy lại `.\.venv\Scripts\python.exe -m pip install -e .` tại thư mục dự án
`OpenSCAD not found`	Cài OpenSCAD hoặc chỉ rõ đường dẫn như ví dụ bên dưới
Chạy máy chủ nhưng không thấy cửa sổ nào	Bình thường: MCP chờ ứng dụng AI gửi yêu cầu; nhấn Ctrl+C để dừng nếu đã mở thủ công
AI không thấy công cụ	Kiểm tra đúng tệp cấu hình của ứng dụng, lưu tệp, khởi động lại và thử `get_system_status`
Báo lỗi JSON hoặc TOML	Dùng mẫu được tạo sẵn; kiểm tra dấu phẩy, ngoặc và mục bị trùng khi ghép vào cấu hình cũ
Xuất được STL nhưng ảnh PNG lỗi	Gọi `get_system_status` để xem lỗi tạo ảnh; kiểm tra OpenSCAD và trình điều khiển đồ họa
`version_conflict`	Yêu cầu AI đọc lại dự án và cập nhật dựa trên phiên bản hiện tại
`timeout`	Thử mô hình đơn giản trước; giảm độ chi tiết và số góc ảnh, rồi xem tài liệu kỹ thuật

Nếu OpenSCAD ở vị trí khác, thay đường dẫn trong lệnh sau bằng vị trí openscad.exe thật trên máy:

$env:OPENSCAD_PATH = 'C:\Program Files\OpenSCAD\openscad.exe'
.\.venv\Scripts\python.exe examples\cube_workflow.py
.\.venv\Scripts\python.exe examples\client_configs.py

Biến trên có hiệu lực trong cửa sổ PowerShell hiện tại. Mẫu cấu hình mới sẽ ghi lại đường dẫn để ứng dụng AI dùng được sau này; nhớ cập nhật mẫu đó vào thiết lập ứng dụng.

Hiểu đúng kết quả kiểm tra

“Hoàn thiện” nghĩa là mô hình đã vượt qua các bước kiểm tra được yêu cầu, không bảo đảm mọi máy in đều in được. Kiểm tra hiện tại không chứng nhận đầy đủ độ dày thành, vùng cần chống đỡ, độ bền hay dung sai lắp ghép. Hãy xem ảnh, kiểm tra kích thước và xem trước trong slicer trước khi in.

OpenSCAD chạy trên máy bạn. Công cụ có giới hạn đường dẫn và chặn một số thao tác đọc tệp trong mã mô hình, nhưng không phải môi trường cách ly ở cấp hệ điều hành: chỉ chạy mã từ nguồn bạn tin cậy. Ứng dụng AI có thể gửi nội dung hoặc kết quả công cụ đến nhà cung cấp AI tùy thiết lập của ứng dụng.