Verse
chính thứcXuất bản cảnh 3D, chuyến tham quan và thế giới, từ một sản phẩm đơn lẻ đến cả thành phố, dưới dạng liên kết mở được trong mọi trình duyệt. Trợ lý của bạn sẽ nhận lại một liên kết, mã nhúng, liên kết chia sẻ riêng tư và chuyến tham quan có hướng dẫn. Đăng nhập bằng Verse, không cần khóa API.
Bạn có thể làm gì với Verse MCP?
- Xuất bản cảnh — Yêu cầu trợ lý tải lên một tệp cục bộ hoặc URL công khai và trả về liên kết Verse, mã nhúng hoặc liên kết chia sẻ.
- Quản lý chế độ hiển thị — Đặt cảnh ở chế độ công khai, không công khai hoặc riêng tư, đồng thời nhận liên kết mã thông báo chia sẻ có thể thu hồi cho các cảnh riêng tư.
- Kiểm tra trạng thái dựng — Yêu cầu trạng thái dựng, tiến độ và thời gian dự kiến hoàn tất của một cảnh, rồi nhận liên kết khi hoàn tất.
- Lấy mã nhúng — Yêu cầu các tùy chọn nhúng bằng iframe, phần tử
<verse-viewer>hoặc URL thuần cho một cảnh đã xuất bản. - Tạo chuyến tham quan bằng camera — Đọc, thiết lập, lập kế hoạch lại hoặc xóa các đường đi camera có hướng dẫn cho chuyến bay xuyên cảnh.
- Tạo liên kết tải lên — Tạo liên kết dùng một lần có hiệu lực trong 30 phút cho tệp bạn không thể bàn giao trực tiếp, rồi kiểm tra trạng thái của liên kết.
Máy chủ MCP được lưu trữ
npx add-mcp 'https://verse.ctruh.com/mcp'Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác
Tài liệu
@ctruhtech/verse-mcp
Máy chủ MCP dành cho Verse Engine, giúp xuất bản cảnh 3D, chuyến tham quan và thế giới — từ một sản phẩm đơn lẻ đến cả thành phố — dưới dạng liên kết mở được trong mọi trình duyệt trên các thiết bị thông dụng. Kết nối máy chủ với Claude, ChatGPT, Cursor, VS Code hoặc tác nhân của riêng bạn, rồi trợ lý có thể xuất bản tệp hoặc URL công khai và gửi lại cho bạn liên kết Verse, mã nhúng, liên kết chia sẻ riêng tư hoặc chuyến tham quan bằng camera có hướng dẫn.
"Put https://example.com/villa.glb on Verse and give me a link I can share."
"Make that scene private and give me a link I can send to the client."
"I have a big file on my phone. Give me a Verse upload link for it."
"Give me the embed code for it, 1:1."
Được cấp phép theo MIT. Tài liệu: https://verse.ctruh.com/docs/#/mcp. Trang cài đặt có các nút cài đặt bằng một cú nhấp: https://verse.ctruh.com/mcp.
Kết nối chỉ với một bước: đăng nhập bằng Verse
Thêm https://verse.ctruh.com/mcp vào trợ lý của bạn rồi đăng nhập bằng tài khoản Verse trong trình duyệt. Không cần sao chép khóa API hay cài đặt gì.
- Claude (web và máy tính): Settings → Connectors → Add custom connector → URL
https://verse.ctruh.com/mcp→ Add, sau đó Connect. - Claude Code:
claude mcp add --transport http --scope user verse https://verse.ctruh.com/mcp, sau đó chạy/mcpvà chọn Authenticate. - ChatGPT: Settings → Connectors → Create (developer mode) → URL
https://verse.ctruh.com/mcp, authentication OAuth → Create, sau đó đăng nhập. - Cursor: Thêm vào Cursor, hoặc
{ "mcpServers": { "verse": { "url": "https://verse.ctruh.com/mcp" } } }trong~/.cursor/mcp.json, sau đó chọn Connect trong Settings → MCP. - VS Code: Cài đặt trong VS Code, hoặc
{ "servers": { "verse": { "type": "http", "url": "https://verse.ctruh.com/mcp" } } }trong.vscode/mcp.json, sau đó chọn Start.
Trong lần đầu tiên, một trang Verse sẽ yêu cầu bạn đăng nhập (bằng mã qua email hoặc WhatsApp) rồi nhấn Allow. Ứng dụng sẽ nhận được khóa có tên "MCP · " trên trang Tài khoản; khóa có hiệu lực trong 30 ngày, được gia hạn khi sử dụng và bạn có thể thu hồi tại đó.
Muốn chạy cục bộ bằng khóa API? Xem Thiết lập (stdio) bên dưới: npx -y @ctruhtech/verse-mcp, Node 20 trở lên.
Công cụ
| Công cụ | Chức năng |
|---|---|
upload_scene | Chuyển đường dẫn cục bộ hoặc URL công khai thành liên kết Verse. Có thể tiếp tục tải lên các tệp lớn, gửi thông báo tiến độ và chờ quá trình dựng hoàn tất. |
get_scene_status | Trạng thái dựng, tiến độ và thời gian dự kiến; trả về liên kết khi hoàn tất. |
list_scenes | Các cảnh thuộc tài khoản của bạn. |
create_share_link | Đặt chế độ hiển thị (công khai / không công khai / riêng tư); cảnh riêng tư sẽ có liên kết chia sẻ bằng mã thông báo có thể thu hồi. Có thể bật tự động phát đường đi của camera. |
revoke_share_link | Thu hồi mã thông báo chia sẻ riêng tư (hoặc liệt kê các mã đang hoạt động). |
get_embed_code | iframe, phần tử <verse-viewer> và URL thuần. |
list_camera_paths, set_camera_path, reset_auto_camera_path, delete_camera_path | Chuyến tham quan có hướng dẫn: xem, tạo, lập kế hoạch lại cho hành trình bay tự động hoặc xóa chuyến tham quan. |
create_upload_link | Dành cho tệp người dùng có nhưng không thể gửi trực tiếp (tệp đính kèm trong cuộc trò chuyện, tệp trên điện thoại): tạo liên kết dùng một lần trong 30 phút để họ tải tệp lên; tệp sẽ được lưu vào tài khoản của họ. |
get_upload_link_status | Trạng thái của liên kết tải lên: đang chờ, đang tải lên, đang dựng, hoàn tất (cảnh và liên kết), thất bại hoặc hết hạn. |
Mỗi công cụ chỉ là lớp bao mỏng quanh REST API công khai (tài liệu tham khảo API) thông qua @ctruhtech/verse-sdk. Không có công cụ tạo thế giới vì API không có điểm cuối như vậy. Liên kết chia sẻ không tự hết hạn; API không hỗ trợ thời hạn, vì vậy hãy thu hồi liên kết riêng tư để chấm dứt quyền truy cập. Lỗi được trả về dưới dạng một câu thuần.
Thông tin xác thực
Đặt VERSE_API_KEY thành một trong các giá trị sau:
- khóa API workspace
vk_...trên trang Tài khoản (thẻ API keys). Khóa hoạt động với quyền của một thành viên trong workspace đó: tải lên, cảnh, chế độ hiển thị, liên kết riêng tư và đường đi camera; - mã thông báo tài khoản (64 ký tự hex, từ Studio). Có cùng quyền nhưng gắn với bạn.
Cả hai đều được gửi dưới dạng Authorization: Bearer. Cần có tài khoản Verse miễn phí để tải lên; không cần tài khoản để mở liên kết đã xuất bản. VERSE_BASE_URL trỏ đến một nguồn gốc khác (mặc định là https://verse.ctruh.com). Khóa chỉ được gửi đến nguồn gốc đó dưới dạng tiêu đề, không bao giờ được ghi nhật ký hoặc trả về trong đầu ra của công cụ. VERSE_UPLOAD_KEY (không bắt buộc) là X-API-Key của máy chủ tự lưu trữ chạy ở chế độ dùng khóa.
Thiết lập (stdio)
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hoặc %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"verse": {
"command": "npx",
"args": ["-y", "@ctruhtech/verse-mcp"],
"env": { "VERSE_API_KEY": "paste-your-key" }
}
}
}
Claude Code:
claude mcp add verse --env VERSE_API_KEY=paste-your-key -- npx -y @ctruhtech/verse-mcp
Cursor: ~/.cursor/mcp.json (hoặc .cursor/mcp.json trong dự án), dùng cùng JSON như Claude Desktop.
VS Code: .vscode/mcp.json:
{
"inputs": [{ "type": "promptString", "id": "verse-key", "description": "Verse API key", "password": true }],
"servers": {
"verse": {
"command": "npx",
"args": ["-y", "@ctruhtech/verse-mcp"],
"env": { "VERSE_API_KEY": "${input:verse-key}" }
}
}
}
Từ xa (Streamable HTTP)
Hướng dẫn đăng nhập nằm ở đầu trang này. Khóa API vẫn hoạt động: gửi Authorization: Bearer <key> (khóa trên trang Tài khoản hoặc mã thông báo tài khoản) và sẽ không cần đăng nhập.
Dành cho các ứng dụng chỉ chấp nhận tiêu đề cố định (tác nhân được lưu trữ, tập lệnh):
{
"mcpServers": {
"verse": {
"url": "https://verse.ctruh.com/mcp",
"headers": { "Authorization": "Bearer paste-your-key" }
}
}
}
Claude Code dùng khóa thay vì đăng nhập: claude mcp add --transport http verse https://verse.ctruh.com/mcp --header "Authorization: Bearer $VERSE_API_KEY". Không có dữ liệu nào được lưu giữa các yêu cầu và máy chủ từ xa không hỗ trợ đường dẫn tệp cục bộ (hãy truyền URL công khai). Yêu cầu không có khóa hoặc phiên đăng nhập sẽ nhận phản hồi 401 cùng với WWW-Authenticate: Bearer realm="verse-mcp", resource_metadata="…" và lỗi JSON-RPC cho biết cần gửi thông tin gì.
Để tự lưu trữ:
VERSE_BASE_URL=https://verse.ctruh.com npx @ctruhtech/verse-mcp --http --port 8787 # http://127.0.0.1:8787/mcp
Đặt TLS phía trước máy chủ. Để gắn máy chủ vào một máy chủ Node hiện có:
import { createHttpHandler } from "@ctruhtech/verse-mcp";
const mcp = createHttpHandler({ baseUrl: "https://verse.ctruh.com" });
// in your request listener: if (url.pathname === "/mcp") return mcp(req, res);
Dòng lệnh
verse-mcp stdio server
verse-mcp --http [--port 8787] [--host 127.0.0.1] [--allow-anonymous]
verse-mcp --version
Phát triển
npm install
npm run typecheck
npm test # scripted Verse origin, both transports, driven by the official MCP client
Báo lỗi và mã nguồn: https://github.com/dev-vinayagastya/verse-mcp. Giấy phép: MIT, xem LICENSE.