Khắc phục sự cố kết nối Cocos MCP: Cursor không hiển thị cocos-creator

Đầu tiên: lớp nào đã thất bại?

Nếu bạn nói “Cursor hỏng / không kết nối”, hãy bắt đầu từ triệu chứng phía Cursor: Cursor hỏng sau Cocos Creator MCP.

Nếu vẫn chưa rõ MCP làm được gì và khác “Cocos Creator AI” thế nào, hãy đọc trước Cocos Creator MCP là gì.

Đường dẫn MCP có bốn lớp. Sự cố ở bất kỳ lớp nào cũng trông giống như “không thể kết nối”:

1. Extension được cài đặt và bật
        ↓
2. Panel được kích hoạt (tài khoản / mã license)
        ↓
3. MCP Server hiển thị Running (localhost)
        ↓
4. Cấu hình AI IDE được ghi và danh sách MCP hiển thị kết nối

Điều bạn thấy	Kiểm tra đầu tiên
Không có menu Extension → Cocos MCP Server / MCP Server	Lớp 1: phiên bản package, đường dẫn import, khởi động lại
Panel mở nhưng không thể bắt đầu / vẫn chưa kích hoạt	Lớp 2: tài khoản và license
Đã bấm Start nhưng không bao giờ Running	Lớp 3: cổng, tường lửa, kích hoạt
Creator hiển thị Running, Cursor không có cocos-creator	Lớp 4: cấu hình nhanh, tải lại MCP, tệp cấu hình
Cursor hiển thị kết nối nhưng không thể liệt kê node scene	Xác minh bằng prompt, bật công cụ, mở đúng dự án

Triệu chứng A: Không có extension MCP trong menu

Nguyên nhân có thể

1. Trộn lẫn package 2.x / 3.x
2. 3.x: chưa import trong Extension Manager, hoặc vẫn bị vô hiệu hóa
3. 2.x: không nằm trong packages/<plugin-name>/, hoặc có thêm một cấp giải nén
4. 2.x: đã đặt tệp nhưng Creator không được khởi động lại hoàn toàn

Cách khắc phục

Creator 3.x:

1. Tải từ Cocos MCP 3.x—không phải gói 2.x
2. Mở dự án → Extension → Extension Manager → Import → chọn zip 3.x
3. Xác nhận cocos-mcp-server được bật; bật nếu đang tắt
4. Nếu menu vẫn thiếu: thoát Creator và mở lại cùng dự án

Creator 2.x:

1. Tải từ Cocos MCP 2.x
2. Sau khi giải nén, cây thư mục sẽ trông như thế này:

thư-mục-gốc-dự-án/
  packages/
    <plugin-name>/          ← tệp plugin trực tiếp ở đây
      package.json          ← nên tồn tại ở đường dẫn này (tên theo package)

3. Sai cấp độ ví dụ:

packages/
  xxx-mcp-unzip/
    <plugin-name>/
      package.json

4. Sửa đường dẫn, sau đó thoát và khởi động lại Creator (không chỉ làm mới scene). Kiểm tra Extension → MCP Server.

Triệu chứng B: Panel mở, nhưng kích hoạt thất bại hoặc dịch vụ không khởi động

Nguyên nhân có thể

• Tài khoản thiếu quyền Pro tương ứng
• Mã license hết hạn hoặc email không khớp
• Đã bấm Start trước khi kích hoạt

Cách khắc phục

1. Mở panel MCP (3.x: Extension → Cocos MCP Server → Open Mcp Panel; 2.x: Extension → MCP Server)
2. Kích hoạt bằng một trong hai cách:
   • Tài khoản VberAI + mật khẩu
   • Email + mã license
3. Xác nhận gói / mã trên trung tâm tài khoản chính thức, sau đó thử lại trong panel
4. Chỉ sau khi kích hoạt mở cài đặt MCP Server và bấm Start

Nếu không kích hoạt, server thường không bao giờ đạt trạng thái Running. Sửa phía editor trước khi đổ lỗi cho Cursor.

Triệu chứng C: Đã bấm Start, nhưng không bao giờ Running

Nguyên nhân có thể

1. Vẫn chưa kích hoạt (xem triệu chứng B)
2. Cổng đang được sử dụng (3.x thường mặc định 3000; 2.x theo panel)
3. Tường lửa / phần mềm bảo mật chặn lắng nghe localhost

Cách khắc phục

1. Ghi chú cổng trên trang cài đặt MCP Server (ví dụ dưới đây dùng 3000—thay bằng giá trị panel của bạn)
2. Kiểm tra xem có gì đang lắng nghe:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. Nếu tiến trình khác giữ cổng:
   • dừng tiến trình đó, hoặc
   • chọn cổng trống trong panel MCP, sau đó Start lại
4. Đảm bảo tường lửa cho phép 127.0.0.1 (không bao giờ phơi MCP ra internet công cộng)
5. Khi panel hiển thị Running, cấu hình AI IDE

Triệu chứng D: Creator đang Running, Cursor không có cocos-creator

Hầu hết các báo cáo “kết nối thất bại” nằm ở đây: editor OK, client không bao giờ nhận cấu hình.

Cách khắc phục (theo thứ tự)

1. Trong Creator, xác nhận panel MCP vẫn Running (thay đổi cổng hoặc khởi động lại editor có thể dừng nó)
2. Mở Tool Manager và bật các công cụ bạn cần
3. Mở Quick Config → chọn Cursor → Auto Config cho đến khi UI hiển thị Configured
4. Trong Cursor → danh sách MCP / công cụ:
   • Bạn sẽ thấy cocos-creator (hoặc tên hiển thị trong panel)
   • Nếu thiếu: Reload MCP (hoặc khởi động lại Cursor) và kiểm tra lại
5. Vẫn thiếu: xác minh cấu hình MCP của Cursor chứa bridge cục bộ (127.0.0.1 + cổng panel)

Đầu ra Auto Config thay đổi theo phiên bản Cursor. Khi kiểm tra thủ công:

• Tên dịch vụ khớp với Cocos MCP (ví dụ cocos-creator)
• Host là 127.0.0.1 hoặc localhost, cổng khớp với Creator
• Không phải IP LAN hoặc IP công cộng do nhầm lẫn

Sau bất kỳ chỉnh sửa cấu hình nào, tải lại MCP lần nữa hoặc UI giữ trạng thái cũ.

Các AI IDE khác

Trong Quick Config, chọn Claude Code, Codex, Windsurf, Cline, v.v., sau đó Auto Config → tải lại MCP trong client đó. Cấu hình Cursor không kết nối mọi IDE.

Triệu chứng E: Hiển thị kết nối, nhưng không thể liệt kê scene / chỉnh sửa node

Nguyên nhân có thể

1. Dự án / scene đang mở trong Creator không khớp với điều bạn hỏi
2. Các công cụ cần thiết chưa được chọn trong Tool Manager
3. Bạn chỉ xác minh “tệp trên đĩa”, không phải ngữ cảnh editor

Xác minh

Gửi prompt chỉ đọc trong Cursor:

Liệt kê tên các node gốc của scene hiện đang mở trong Cocos Creator.

Kết quả	Ý nghĩa
Khớp với Hierarchy	Bridge OK; thử một thao tác ghi nhỏ tiếp theo
Lỗi rõ ràng / không có công cụ	Quay lại triệu chứng C/D
Tên node bịa đặt	MCP có thể không được sử dụng; kiểm tra kết nối và bật công cụ

Sau đó thử một thao tác ghi nhỏ (tạo node tạm thời và xóa nó). Cam kết trước khi chỉnh sửa lớn.

Bảng so sánh nhanh 2.x vs 3.x

Mục	Creator 3.x	Creator 2.x
Trang sản phẩm	cocos (3.x)	cocos2x
Cài đặt	Extension Manager → Import	Giải nén vào packages/ của dự án
Sau khi cài đặt	Bật trong danh sách	Phải khởi động lại Creator
Package	Chỉ 3.x	Chỉ 2.x
Các bước đầy đủ	Cài đặt 3.x	Cài đặt 2.x

Trộn lẫn package thường hiển thị “không có menu” hoặc “import thất bại”—dùng bảng này trước.

Thứ tự khuyến nghị (checklist 5 phút)

Đánh dấu theo thứ tự; hầu hết lỗi nằm ở bốn mục đầu:

1. Phiên bản chính của Creator khớp với zip MCP (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Extension được bật / đường dẫn packages đúng; 2.x đã khởi động lại
3. Panel kích hoạt thành công
4. Panel hiển thị Running; cổng trống
5. Quick Config → Auto Config cho IDE hiện tại
6. Đã tải lại MCP trong AI IDE; cocos-creator được liệt kê
7. Prompt chỉ đọc liệt kê root của scene đang mở

Nếu vẫn thất bại, hãy ghi lại điều này

Khi yêu cầu hỗ trợ hoặc nhờ đồng nghiệp, hãy bao gồm:

• Phiên bản Creator chính xác (ví dụ 3.8.x / 2.4.x)
• Loại gói MCP (2.x hoặc 3.x Pro)
• Panel có Running hay không, và cổng
• Tên/phiên bản AI IDE và ảnh chụp màn hình danh sách MCP
• Prompt chỉ đọc chính xác và phản hồi

Giữ bridge chỉ trên localhost; không công bố cổng MCP.

Tài liệu liên quan

• Cài đặt Cocos Creator 3.x MCP
• Cài đặt Cocos Creator 2.x MCP
• Hướng dẫn video Cocos Creator MCP
• Hướng dẫn chọn engine: Godot MCP vs Unity MCP vs Cocos MCP