@ctruhtech/verse-mcp 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +134 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +54 -0
- package/dist/config.d.ts +24 -0
- package/dist/config.js +39 -0
- package/dist/http.d.ts +29 -0
- package/dist/http.js +84 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/server.d.ts +18 -0
- package/dist/server.js +381 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.js +47 -0
- package/package.json +65 -4
- package/server.json +19 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Hosted (Streamable HTTP) servers hand the agent links on their public origin (`publicBaseUrl`, derived from `X-Forwarded-Proto` / `X-Forwarded-Host` by default), never the API loopback.
|
|
6
|
+
- The hosted server's instructions no longer mention local file paths.
|
|
7
|
+
- Messages start with a capital and read as one sentence; a vowel kind gets "an"; upload progress never steps back.
|
|
8
|
+
|
|
9
|
+
## 0.1.0
|
|
10
|
+
|
|
11
|
+
First release.
|
|
12
|
+
|
|
13
|
+
- Tools: `upload_scene` (local path or public URL, resumable above 100 MB, progress notifications, waits for the build), `get_scene_status`, `list_scenes`, `create_share_link`, `revoke_share_link`, `get_embed_code`, `list_camera_paths`, `set_camera_path`, `reset_auto_camera_path`.
|
|
14
|
+
- Transports: stdio (`npx -y @ctruhtech/verse-mcp`) and stateless Streamable HTTP (`--http`, or `createHttpHandler()` to mount at `/mcp`); the hosted endpoint is `https://verse.ctruh.com/mcp`.
|
|
15
|
+
- Credentials: `VERSE_API_KEY` takes a workspace API key (`vk_...`, Account page) or an account token; both ride as `Authorization: Bearer`. `VERSE_UPLOAD_KEY` for self-hosted keyed servers. Keys are never logged or returned.
|
|
16
|
+
- Errors are one plain sentence; a missing key on the remote endpoint is a `401` with `WWW-Authenticate`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ctruh
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,135 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @ctruhtech/verse-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server for [Verse](https://verse.ctruh.com). It lets AI assistants and agents (Claude, ChatGPT, Cursor, VS Code, your own) turn a 3D file into a shareable link that opens in any browser, then embed it, make it private, or give it a guided tour.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
"Upload ~/Models/villa.glb to Verse and give me a link."
|
|
7
|
+
"Make that scene private and give me a link I can send to the client."
|
|
8
|
+
"Give me the embed code for it, 1:1."
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Node 20 or newer. MIT licensed. Documentation: <https://verse.ctruh.com/docs/#/mcp>.
|
|
12
|
+
|
|
13
|
+
## 60-second setup
|
|
14
|
+
|
|
15
|
+
1. Sign up free at <https://verse.ctruh.com/signin>, open your Account page and create a key under **API keys** (it is shown once).
|
|
16
|
+
2. Add the server to your client with that key as `VERSE_API_KEY`:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
claude mcp add verse --env VERSE_API_KEY=paste-your-key -- npx -y @ctruhtech/verse-mcp
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
3. Ask: "Upload ~/Models/villa.glb to Verse and give me a link."
|
|
23
|
+
|
|
24
|
+
Other clients are below. Nothing is installed globally: `npx -y @ctruhtech/verse-mcp` fetches the package on first use.
|
|
25
|
+
|
|
26
|
+
## Tools
|
|
27
|
+
|
|
28
|
+
| Tool | What it does |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `upload_scene` | Local path or public URL, to a Verse link. Resumable for big files, progress notifications, waits for the build. |
|
|
31
|
+
| `get_scene_status` | Build state, progress and ETA; the link once done. |
|
|
32
|
+
| `list_scenes` | Scenes owned by your account. |
|
|
33
|
+
| `create_share_link` | Set visibility (public / unlisted / private); private scenes get a revocable share-token link. Optional autoplay of the camera path. |
|
|
34
|
+
| `revoke_share_link` | Revoke a private share token (or list the active ones). |
|
|
35
|
+
| `get_embed_code` | iframe, `<verse-viewer>` element and plain URL. |
|
|
36
|
+
| `list_camera_paths`, `set_camera_path`, `reset_auto_camera_path` | Guided tours: read, author, or re-plan the automatic fly-through. |
|
|
37
|
+
|
|
38
|
+
Every tool is a thin wrapper over the public REST API ([API reference](https://verse.ctruh.com/docs/#/api)) through [`@ctruhtech/verse-sdk`](https://www.npmjs.com/package/@ctruhtech/verse-sdk). There is no world-generation tool, because the API has no such endpoint. Share links do not expire on their own; the API has no expiry, so revoke a private link to end access. Errors come back as one plain sentence.
|
|
39
|
+
|
|
40
|
+
## Credentials
|
|
41
|
+
|
|
42
|
+
Set `VERSE_API_KEY` to one of:
|
|
43
|
+
|
|
44
|
+
- a **workspace API key** `vk_...` from your Account page (**API keys** card). It acts as a member of that workspace: uploads, scenes, visibility, private links and camera paths;
|
|
45
|
+
- your **account token** (64 hex, from Studio). Same powers, tied to you.
|
|
46
|
+
|
|
47
|
+
Both are sent as `Authorization: Bearer`. Uploading needs a free Verse account; opening a published link never does. `VERSE_BASE_URL` points at another origin (default `https://verse.ctruh.com`). The key is only ever sent to that origin as a header, and is never logged or returned in tool output. `VERSE_UPLOAD_KEY` (optional) is the `X-API-Key` of a self-hosted server running in keyed mode.
|
|
48
|
+
|
|
49
|
+
## Setup (stdio)
|
|
50
|
+
|
|
51
|
+
**Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"verse": {
|
|
57
|
+
"command": "npx",
|
|
58
|
+
"args": ["-y", "@ctruhtech/verse-mcp"],
|
|
59
|
+
"env": { "VERSE_API_KEY": "paste-your-key" }
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Claude Code**:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
claude mcp add verse --env VERSE_API_KEY=paste-your-key -- npx -y @ctruhtech/verse-mcp
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Cursor**: `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), same JSON as Claude Desktop.
|
|
72
|
+
|
|
73
|
+
**VS Code**: `.vscode/mcp.json`:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"inputs": [{ "type": "promptString", "id": "verse-key", "description": "Verse API key", "password": true }],
|
|
78
|
+
"servers": {
|
|
79
|
+
"verse": {
|
|
80
|
+
"command": "npx",
|
|
81
|
+
"args": ["-y", "@ctruhtech/verse-mcp"],
|
|
82
|
+
"env": { "VERSE_API_KEY": "${input:verse-key}" }
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Remote (Streamable HTTP)
|
|
89
|
+
|
|
90
|
+
For clients that connect to a URL (ChatGPT connectors, Claude's custom connectors, hosted agents). Each caller sends their own key; nothing is stored between requests, and local file paths are disabled (pass public URLs). A request without a key is answered `401` with `WWW-Authenticate: Bearer realm="verse-mcp"` and a JSON-RPC error that says what to send.
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"verse": {
|
|
96
|
+
"url": "https://verse.ctruh.com/mcp",
|
|
97
|
+
"headers": { "Authorization": "Bearer paste-your-key" }
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Claude Code: `claude mcp add --transport http verse https://verse.ctruh.com/mcp --header "Authorization: Bearer $VERSE_API_KEY"`.
|
|
104
|
+
|
|
105
|
+
To host it yourself:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
VERSE_BASE_URL=https://verse.ctruh.com npx @ctruhtech/verse-mcp --http --port 8787 # http://127.0.0.1:8787/mcp
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Put TLS in front of it. To mount it inside an existing Node server instead:
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
import { createHttpHandler } from "@ctruhtech/verse-mcp";
|
|
115
|
+
const mcp = createHttpHandler({ baseUrl: "https://verse.ctruh.com" });
|
|
116
|
+
// in your request listener: if (url.pathname === "/mcp") return mcp(req, res);
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Command line
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
verse-mcp stdio server
|
|
123
|
+
verse-mcp --http [--port 8787] [--host 127.0.0.1] [--allow-anonymous]
|
|
124
|
+
verse-mcp --version
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Develop
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
npm install
|
|
131
|
+
npm run typecheck
|
|
132
|
+
npm test # scripted Verse origin, both transports, driven by the official MCP client
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Issues and source: <https://github.com/dev-vinayagastya/verse-mcp>. Licence: MIT, see [LICENSE](LICENSE).
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { createServer } from "node:http";
|
|
3
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
4
|
+
import { VERSION, baseUrlFromEnv, credentialsFromEnv } from "./config.js";
|
|
5
|
+
import { createVerseServer } from "./server.js";
|
|
6
|
+
import { createHttpHandler } from "./http.js";
|
|
7
|
+
const args = process.argv.slice(2);
|
|
8
|
+
const flag = (n) => args.includes(n);
|
|
9
|
+
const val = (n, d) => {
|
|
10
|
+
const i = args.indexOf(n);
|
|
11
|
+
return i >= 0 && args[i + 1] ? args[i + 1] : d;
|
|
12
|
+
};
|
|
13
|
+
if (flag("--help") || flag("-h")) {
|
|
14
|
+
process.stdout.write(`verse-mcp ${VERSION}: MCP server for Verse (turn 3D files into shareable links)
|
|
15
|
+
|
|
16
|
+
verse-mcp stdio server (Claude Desktop, Claude Code, Cursor, VS Code)
|
|
17
|
+
verse-mcp --http [--port 8787] [--host 127.0.0.1] [--allow-anonymous]
|
|
18
|
+
Streamable HTTP server at /mcp; callers send their own
|
|
19
|
+
'Authorization: Bearer <key>'. Local file paths are disabled.
|
|
20
|
+
|
|
21
|
+
Environment:
|
|
22
|
+
VERSE_API_KEY your Verse API key (Account page, "API keys") or account token
|
|
23
|
+
VERSE_BASE_URL Verse origin (default https://verse.ctruh.com)
|
|
24
|
+
VERSE_UPLOAD_KEY X-API-Key for a self-hosted server in keyed mode (optional)
|
|
25
|
+
`);
|
|
26
|
+
process.exit(0);
|
|
27
|
+
}
|
|
28
|
+
if (flag("--version")) {
|
|
29
|
+
process.stdout.write(`${VERSION}\n`);
|
|
30
|
+
process.exit(0);
|
|
31
|
+
}
|
|
32
|
+
const baseUrl = baseUrlFromEnv();
|
|
33
|
+
if (flag("--http")) {
|
|
34
|
+
const port = Number(val("--port", process.env.PORT || "8787"));
|
|
35
|
+
const host = val("--host", "127.0.0.1");
|
|
36
|
+
const handler = createHttpHandler({ baseUrl, requireAuth: !flag("--allow-anonymous") });
|
|
37
|
+
const srv = createServer((req, res) => {
|
|
38
|
+
const path = (req.url ?? "").split("?")[0];
|
|
39
|
+
if (path === "/healthz") {
|
|
40
|
+
res.writeHead(200, { "Content-Type": "text/plain" });
|
|
41
|
+
return void res.end("ok");
|
|
42
|
+
}
|
|
43
|
+
if (path === "/mcp")
|
|
44
|
+
return void handler(req, res);
|
|
45
|
+
res.writeHead(404, { "Content-Type": "application/json" });
|
|
46
|
+
res.end('{"error":"not found; the MCP endpoint is /mcp"}');
|
|
47
|
+
});
|
|
48
|
+
srv.listen(port, host, () => process.stderr.write(`verse-mcp ${VERSION} listening on http://${host}:${port}/mcp (Verse origin ${baseUrl})\n`));
|
|
49
|
+
}
|
|
50
|
+
else {
|
|
51
|
+
const server = createVerseServer({ baseUrl, credentials: credentialsFromEnv(), allowLocalFiles: true });
|
|
52
|
+
await server.connect(new StdioServerTransport());
|
|
53
|
+
process.stderr.write(`verse-mcp ${VERSION} ready on stdio (Verse origin ${baseUrl})\n`);
|
|
54
|
+
}
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { VerseClient } from "@ctruhtech/verse-sdk";
|
|
2
|
+
export declare const VERSION = "0.1.1";
|
|
3
|
+
export declare const DEFAULT_BASE_URL = "https://verse.ctruh.com";
|
|
4
|
+
export interface Credentials {
|
|
5
|
+
/**
|
|
6
|
+
* What goes in `Authorization: Bearer`: a workspace API key `vk_...`
|
|
7
|
+
* (Account page, "API keys" card; acts as a member of that workspace) or
|
|
8
|
+
* an account token (64 hex, Studio). Either owns what it uploads and
|
|
9
|
+
* unlocks list / visibility / share / paths.
|
|
10
|
+
*/
|
|
11
|
+
token?: string | null;
|
|
12
|
+
/** `X-API-Key` for a self-hosted server in keyed mode (`VERSE_UPLOAD_KEY`); never needed on verse.ctruh.com. */
|
|
13
|
+
apiKey?: string | null;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* VERSE_API_KEY holds the Bearer credential: a workspace API key (`vk_...`)
|
|
17
|
+
* or an account token. Both ride as `Authorization: Bearer`, which is how
|
|
18
|
+
* the hosted service recognises a signed-in caller. The value is never
|
|
19
|
+
* logged or echoed.
|
|
20
|
+
*/
|
|
21
|
+
export declare function classifyKey(value: string | undefined | null): Credentials;
|
|
22
|
+
export declare function credentialsFromEnv(env?: NodeJS.ProcessEnv): Credentials;
|
|
23
|
+
export declare function baseUrlFromEnv(env?: NodeJS.ProcessEnv): string;
|
|
24
|
+
export declare function makeClient(baseUrl: string, creds: Credentials, fetchImpl?: typeof fetch): VerseClient;
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { VerseClient } from "@ctruhtech/verse-sdk";
|
|
2
|
+
export const VERSION = "0.1.1";
|
|
3
|
+
export const DEFAULT_BASE_URL = "https://verse.ctruh.com";
|
|
4
|
+
/**
|
|
5
|
+
* VERSE_API_KEY holds the Bearer credential: a workspace API key (`vk_...`)
|
|
6
|
+
* or an account token. Both ride as `Authorization: Bearer`, which is how
|
|
7
|
+
* the hosted service recognises a signed-in caller. The value is never
|
|
8
|
+
* logged or echoed.
|
|
9
|
+
*/
|
|
10
|
+
export function classifyKey(value) {
|
|
11
|
+
const v = (value ?? "").trim();
|
|
12
|
+
if (!v)
|
|
13
|
+
return {};
|
|
14
|
+
return { token: v };
|
|
15
|
+
}
|
|
16
|
+
export function credentialsFromEnv(env = process.env) {
|
|
17
|
+
const c = classifyKey(env.VERSE_API_KEY);
|
|
18
|
+
const tok = (env.VERSE_ACCOUNT_TOKEN ?? "").trim();
|
|
19
|
+
if (tok)
|
|
20
|
+
c.token = tok;
|
|
21
|
+
const up = (env.VERSE_UPLOAD_KEY ?? "").trim();
|
|
22
|
+
if (up)
|
|
23
|
+
c.apiKey = up;
|
|
24
|
+
return c;
|
|
25
|
+
}
|
|
26
|
+
export function baseUrlFromEnv(env = process.env) {
|
|
27
|
+
return (env.VERSE_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
28
|
+
}
|
|
29
|
+
export function makeClient(baseUrl, creds, fetchImpl) {
|
|
30
|
+
return new VerseClient({
|
|
31
|
+
baseUrl,
|
|
32
|
+
token: creds.token ?? null,
|
|
33
|
+
apiKey: creds.apiKey ?? null,
|
|
34
|
+
source: `verse-mcp/${VERSION}`,
|
|
35
|
+
telemetry: false,
|
|
36
|
+
pollIntervalMs: 2500,
|
|
37
|
+
...(fetchImpl ? { fetch: fetchImpl } : {}),
|
|
38
|
+
});
|
|
39
|
+
}
|
package/dist/http.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from "node:http";
|
|
2
|
+
import { type Credentials } from "./config.js";
|
|
3
|
+
export interface HttpHandlerOptions {
|
|
4
|
+
baseUrl: string;
|
|
5
|
+
/** Require an Authorization: Bearer <key> (or X-API-Key) header. Default true. */
|
|
6
|
+
requireAuth?: boolean;
|
|
7
|
+
fetch?: typeof fetch;
|
|
8
|
+
pollIntervalMs?: number;
|
|
9
|
+
/** Called once per JSON-RPC `tools/call` with the tool name (a short label), for adoption counters. Never receives arguments. */
|
|
10
|
+
onToolCall?: (tool: string) => void;
|
|
11
|
+
/**
|
|
12
|
+
* The origin written into links handed to the agent. A string, or a
|
|
13
|
+
* function of the request (default: the request's own public origin from
|
|
14
|
+
* X-Forwarded-Proto / X-Forwarded-Host / Host, so a server reached through
|
|
15
|
+
* an edge still writes links on its public address).
|
|
16
|
+
*/
|
|
17
|
+
publicBaseUrl?: string | ((req: IncomingMessage) => string | undefined);
|
|
18
|
+
}
|
|
19
|
+
/** The public origin a request arrived on, as the edge reports it. */
|
|
20
|
+
export declare function requestOrigin(req: IncomingMessage): string | undefined;
|
|
21
|
+
/** Credentials from the request headers; the caller's own key, never stored or logged. */
|
|
22
|
+
export declare function credentialsFromRequest(req: IncomingMessage): Credentials;
|
|
23
|
+
/**
|
|
24
|
+
* A Node (req, res) handler for the Streamable HTTP transport, stateless:
|
|
25
|
+
* every POST gets its own server bound to the caller's credentials, so one
|
|
26
|
+
* deployment serves many users and nothing is kept between requests.
|
|
27
|
+
* Mount at /mcp: `if (url.pathname === "/mcp") return handler(req, res)`.
|
|
28
|
+
*/
|
|
29
|
+
export declare function createHttpHandler(o: HttpHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
|
package/dist/http.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
2
|
+
import { classifyKey } from "./config.js";
|
|
3
|
+
import { createVerseServer } from "./server.js";
|
|
4
|
+
/** The public origin a request arrived on, as the edge reports it. */
|
|
5
|
+
export function requestOrigin(req) {
|
|
6
|
+
const first = (v) => String(v ?? "").split(",")[0].trim();
|
|
7
|
+
const host = first(req.headers["x-forwarded-host"]) || first(req.headers["host"]);
|
|
8
|
+
if (!host)
|
|
9
|
+
return undefined;
|
|
10
|
+
const proto = first(req.headers["x-forwarded-proto"]) || "http";
|
|
11
|
+
return `${proto}://${host}`;
|
|
12
|
+
}
|
|
13
|
+
const send = (res, status, body, headers = {}) => {
|
|
14
|
+
res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
|
|
15
|
+
res.end(JSON.stringify(body));
|
|
16
|
+
};
|
|
17
|
+
/** Credentials from the request headers; the caller's own key, never stored or logged. */
|
|
18
|
+
export function credentialsFromRequest(req) {
|
|
19
|
+
const auth = String(req.headers["authorization"] ?? "");
|
|
20
|
+
const m = /^Bearer\s+(\S+)$/i.exec(auth);
|
|
21
|
+
const c = classifyKey(m ? m[1] : "");
|
|
22
|
+
const xk = String(req.headers["x-api-key"] ?? "").trim();
|
|
23
|
+
if (xk)
|
|
24
|
+
c.apiKey = xk;
|
|
25
|
+
return c;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* A Node (req, res) handler for the Streamable HTTP transport, stateless:
|
|
29
|
+
* every POST gets its own server bound to the caller's credentials, so one
|
|
30
|
+
* deployment serves many users and nothing is kept between requests.
|
|
31
|
+
* Mount at /mcp: `if (url.pathname === "/mcp") return handler(req, res)`.
|
|
32
|
+
*/
|
|
33
|
+
export function createHttpHandler(o) {
|
|
34
|
+
return async (req, res) => {
|
|
35
|
+
if (req.method !== "POST") {
|
|
36
|
+
return send(res, 405, { jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed; POST JSON-RPC to this endpoint." }, id: null }, { Allow: "POST" });
|
|
37
|
+
}
|
|
38
|
+
const creds = credentialsFromRequest(req);
|
|
39
|
+
if ((o.requireAuth ?? true) && !creds.token && !creds.apiKey) {
|
|
40
|
+
return send(res, 401, { jsonrpc: "2.0", error: { code: -32001, message: "Send your Verse key as 'Authorization: Bearer <key>'." }, id: null }, { "WWW-Authenticate": 'Bearer realm="verse-mcp"' });
|
|
41
|
+
}
|
|
42
|
+
let parsed;
|
|
43
|
+
try {
|
|
44
|
+
const chunks = [];
|
|
45
|
+
let n = 0;
|
|
46
|
+
for await (const c of req) {
|
|
47
|
+
n += c.length;
|
|
48
|
+
if (n > 4_194_304)
|
|
49
|
+
return send(res, 413, { jsonrpc: "2.0", error: { code: -32600, message: "Request too large." }, id: null });
|
|
50
|
+
chunks.push(c);
|
|
51
|
+
}
|
|
52
|
+
parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return send(res, 400, { jsonrpc: "2.0", error: { code: -32700, message: "Parse error." }, id: null });
|
|
56
|
+
}
|
|
57
|
+
if (o.onToolCall) {
|
|
58
|
+
for (const m of Array.isArray(parsed) ? parsed : [parsed]) {
|
|
59
|
+
const r = m;
|
|
60
|
+
if (r?.method === "tools/call") {
|
|
61
|
+
try {
|
|
62
|
+
o.onToolCall(typeof r.params?.name === "string" ? r.params.name : "call");
|
|
63
|
+
}
|
|
64
|
+
catch { /* counters never break a call */ }
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
const publicBaseUrl = (typeof o.publicBaseUrl === "function" ? o.publicBaseUrl(req) : o.publicBaseUrl) || requestOrigin(req) || o.baseUrl;
|
|
69
|
+
const server = createVerseServer({ baseUrl: o.baseUrl, credentials: creds, allowLocalFiles: false, fetch: o.fetch, pollIntervalMs: o.pollIntervalMs, publicBaseUrl });
|
|
70
|
+
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: false });
|
|
71
|
+
res.on("close", () => {
|
|
72
|
+
void transport.close();
|
|
73
|
+
void server.close();
|
|
74
|
+
});
|
|
75
|
+
try {
|
|
76
|
+
await server.connect(transport);
|
|
77
|
+
await transport.handleRequest(req, res, parsed);
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
if (!res.headersSent)
|
|
81
|
+
send(res, 500, { jsonrpc: "2.0", error: { code: -32603, message: "Internal error." }, id: null });
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { type Credentials } from "./config.js";
|
|
3
|
+
export interface ServerOptions {
|
|
4
|
+
baseUrl: string;
|
|
5
|
+
credentials: Credentials;
|
|
6
|
+
/** stdio: true (the agent runs on the user's machine). HTTP: false (a remote server must not read its own disk). */
|
|
7
|
+
allowLocalFiles: boolean;
|
|
8
|
+
fetch?: typeof fetch;
|
|
9
|
+
/** Poll interval override (tests). */
|
|
10
|
+
pollIntervalMs?: number;
|
|
11
|
+
/**
|
|
12
|
+
* The origin links are written with, when it differs from `baseUrl`: a
|
|
13
|
+
* hosted server talks to its own API over loopback but must hand the
|
|
14
|
+
* agent links on its public address. Default `baseUrl`.
|
|
15
|
+
*/
|
|
16
|
+
publicBaseUrl?: string;
|
|
17
|
+
}
|
|
18
|
+
export declare function createVerseServer(opts: ServerOptions): McpServer;
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { openAsBlob } from "node:fs";
|
|
4
|
+
import { stat } from "node:fs/promises";
|
|
5
|
+
import { homedir } from "node:os";
|
|
6
|
+
import { basename, resolve } from "node:path";
|
|
7
|
+
import { VerseError } from "@ctruhtech/verse-sdk";
|
|
8
|
+
import { VERSION, makeClient } from "./config.js";
|
|
9
|
+
import { ToolError, plainError, sceneIdOf } from "./util.js";
|
|
10
|
+
const instructionsFor = (localFiles) => "Verse turns 3D files (GLB, glTF, FBX, OBJ, IFC, USD/USDZ, PLY, SPLAT, SPZ-class captures, point clouds) into a shareable link that opens in any browser, with no app and no plugin. " +
|
|
11
|
+
(localFiles
|
|
12
|
+
? "Use upload_scene with a local file path or a public URL, then share the returned link or call get_embed_code for an iframe. "
|
|
13
|
+
: "Use upload_scene with a public http(s) URL (this hosted server cannot read local files), then share the returned link or call get_embed_code for an iframe. ") +
|
|
14
|
+
"Owner actions (list_scenes, visibility, private share links, camera paths) need the user's Verse account token in VERSE_API_KEY. " +
|
|
15
|
+
"Builds can take a minute or more for large files; if upload_scene returns before the build is done, poll get_scene_status.";
|
|
16
|
+
const sceneArg = z.string().min(3).max(600).describe("Scene id (e.g. palm-villa-0a1b2c3d4e5f), the job id returned by upload_scene, or a Verse share link.");
|
|
17
|
+
const KINDS = ["splat", "cloud", "ifc", "usd", "fbx", "obj"];
|
|
18
|
+
const okRaw = (text, data) => ({ content: [{ type: "text", text }], ...(data ? { structuredContent: data } : {}) });
|
|
19
|
+
export function createVerseServer(opts) {
|
|
20
|
+
const client = makeClient(opts.baseUrl, opts.credentials, opts.fetch);
|
|
21
|
+
if (opts.pollIntervalMs)
|
|
22
|
+
client.pollIntervalMs = opts.pollIntervalMs;
|
|
23
|
+
const hasAccount = !!opts.credentials.token;
|
|
24
|
+
const server = new McpServer({ name: "verse", version: VERSION }, { instructions: instructionsFor(opts.allowLocalFiles) });
|
|
25
|
+
const apiBase = opts.baseUrl.replace(/\/+$/, "");
|
|
26
|
+
const linkBase = (opts.publicBaseUrl || apiBase).replace(/\/+$/, "");
|
|
27
|
+
/** Rewrite the API origin to the public one in anything handed to the agent. */
|
|
28
|
+
const pub = (v) => {
|
|
29
|
+
if (linkBase === apiBase || v == null)
|
|
30
|
+
return v;
|
|
31
|
+
if (typeof v === "string")
|
|
32
|
+
return v.split(apiBase).join(linkBase);
|
|
33
|
+
if (Array.isArray(v))
|
|
34
|
+
return v.map(pub);
|
|
35
|
+
if (typeof v === "object")
|
|
36
|
+
return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, pub(x)]));
|
|
37
|
+
return v;
|
|
38
|
+
};
|
|
39
|
+
const ok = (text, data) => okRaw(pub(text), data ? pub(data) : undefined);
|
|
40
|
+
const needAccount = (what) => {
|
|
41
|
+
if (!hasAccount)
|
|
42
|
+
throw new ToolError(`${what} needs a Verse key; set VERSE_API_KEY to an API key from your Account page (${linkBase}/account, "API keys") or your account token.`);
|
|
43
|
+
};
|
|
44
|
+
/** Wrap a handler: any failure becomes one plain sentence with isError. */
|
|
45
|
+
const guard = (fn) => async (args, extra) => {
|
|
46
|
+
try {
|
|
47
|
+
return await fn(args, extra);
|
|
48
|
+
}
|
|
49
|
+
catch (e) {
|
|
50
|
+
return { content: [{ type: "text", text: plainError(e, hasAccount) }], isError: true };
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
/** Best record for a scene: the live job record (2 h), else the owner's scene list entry, else just the id. */
|
|
54
|
+
async function resolveScene(id) {
|
|
55
|
+
try {
|
|
56
|
+
const rec = await client.job(id);
|
|
57
|
+
if (rec.status === "done")
|
|
58
|
+
return rec;
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
/* fall through */
|
|
62
|
+
}
|
|
63
|
+
if (hasAccount) {
|
|
64
|
+
try {
|
|
65
|
+
return await client.scenes.get(id);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
/* fall through */
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return id;
|
|
72
|
+
}
|
|
73
|
+
function progressNotifier(extra) {
|
|
74
|
+
const token = extra?._meta?.progressToken;
|
|
75
|
+
let last = -1;
|
|
76
|
+
return async (progress, total, message) => {
|
|
77
|
+
if (token === undefined || token === null)
|
|
78
|
+
return;
|
|
79
|
+
if (progress <= last)
|
|
80
|
+
return; // never report a step backwards
|
|
81
|
+
last = progress;
|
|
82
|
+
try {
|
|
83
|
+
await extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress, total, message } });
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
/* the client went away; the upload carries on */
|
|
87
|
+
}
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
const linkOf = (rec) => client.shareLink(rec);
|
|
91
|
+
// ── upload_scene ──────────────────────────────────────────────────────
|
|
92
|
+
server.registerTool("upload_scene", {
|
|
93
|
+
title: "Upload a 3D file and get a Verse link",
|
|
94
|
+
description: "Upload a 3D file and turn it into a shareable Verse link that opens in any browser. `source` is a local file path (stdio only) or a public http(s) URL the Verse server will fetch itself " +
|
|
95
|
+
"(Dropbox needs dl=1, Google Drive needs 'anyone with the link', S3/R2/GCS need a presigned URL). Accepts GLB, glTF, FBX, OBJ, IFC, USD/USDZ, PLY, SPLAT and point clouds (LAS/LAZ/E57). " +
|
|
96
|
+
"Large local files upload in resumable parts and survive dropped connections; progress is reported as notifications. " +
|
|
97
|
+
"By default the call waits for the build to finish and returns the link; if the build outlasts `wait_seconds` it returns the job id so you can poll get_scene_status. " +
|
|
98
|
+
"Result: `link` (open in a browser), `scene` (id), `status`.",
|
|
99
|
+
inputSchema: {
|
|
100
|
+
source: z.string().min(1).max(4096).describe("Local file path (e.g. ~/Models/villa.glb) or a public http(s) URL to a 3D file."),
|
|
101
|
+
name: z.string().regex(/^[a-z0-9_-]{1,48}$/).optional().describe("Optional slug used as the scene id prefix, lowercase letters, digits, - and _."),
|
|
102
|
+
kind: z.enum(KINDS).optional().describe("Force the file kind when the extension is ambiguous (e.g. 'splat' for a Gaussian-splat .ply). Normally detected from the bytes."),
|
|
103
|
+
as: z.enum(["product", "interior", "building", "exterior"]).optional().describe("Say what the file is: a 'product' (a single object) or a walkable 'interior'/'building'/'exterior'. Local uploads only; otherwise detected."),
|
|
104
|
+
path: z.enum(["fidelity", "streamed"]).optional().describe("'fidelity' publishes the model as-is (best for single products); 'streamed' builds a streamed scene (best for big walkable scenes). Normally decided automatically."),
|
|
105
|
+
bake: z.enum(["preview", "final"]).optional().describe("Bake lighting on the server before building (for live-lit GLBs). Slower."),
|
|
106
|
+
visibility: z.enum(["public", "unlisted", "private"]).optional().describe("Set after the build finishes. Needs an account token. 'private' scenes only open with a share link from create_share_link."),
|
|
107
|
+
resumable: z.boolean().optional().describe("Force resumable multi-part upload (default: automatic above 100 MB). Use on flaky connections."),
|
|
108
|
+
wait_seconds: z.number().int().min(0).max(3000).default(600).describe("How long to wait for the build before returning the job id (0 = return right after upload)."),
|
|
109
|
+
},
|
|
110
|
+
annotations: { title: "Upload a 3D file", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
|
|
111
|
+
}, guard(async (a, extra) => {
|
|
112
|
+
const notify = progressNotifier(extra);
|
|
113
|
+
const wait = a.wait_seconds ?? 600;
|
|
114
|
+
const src = String(a.source).trim();
|
|
115
|
+
const isUrl = /^https?:\/\//i.test(src);
|
|
116
|
+
let job;
|
|
117
|
+
let origin;
|
|
118
|
+
if (isUrl) {
|
|
119
|
+
await notify(0, 1, "Asking Verse to fetch the file");
|
|
120
|
+
const r = await client.uploadFromUrl(src, { name: a.name, kind: a.kind, bake: a.bake, path: a.path, signal: extra?.signal });
|
|
121
|
+
job = r.job;
|
|
122
|
+
origin = `${r.source} (${(r.sizeBytes / 1048576).toFixed(1)} MB)`;
|
|
123
|
+
}
|
|
124
|
+
else {
|
|
125
|
+
if (!opts.allowLocalFiles)
|
|
126
|
+
throw new ToolError("This remote server cannot read local files; pass a public http(s) URL as the source, or run the stdio server (npx @ctruhtech/verse-mcp) on your machine.");
|
|
127
|
+
const p = resolve(src.startsWith("file://") ? new URL(src).pathname : src.replace(/^~(?=$|\/)/, homedir()));
|
|
128
|
+
let st;
|
|
129
|
+
try {
|
|
130
|
+
st = await stat(p);
|
|
131
|
+
}
|
|
132
|
+
catch {
|
|
133
|
+
throw new ToolError(`No file exists at ${p}.`);
|
|
134
|
+
}
|
|
135
|
+
if (!st.isFile())
|
|
136
|
+
throw new ToolError(`${p} is not a file; zip a folder (e.g. an OBJ with textures) first.`);
|
|
137
|
+
if (st.size === 0)
|
|
138
|
+
throw new ToolError(`${basename(p)} is empty.`);
|
|
139
|
+
const blob = await openAsBlob(p); // file-backed, sliced lazily: a 5 GB file is never held in memory
|
|
140
|
+
origin = `${basename(p)} (${(st.size / 1048576).toFixed(1)} MB)`;
|
|
141
|
+
const r = await client.upload(blob, {
|
|
142
|
+
name: a.name,
|
|
143
|
+
kind: a.kind,
|
|
144
|
+
bake: a.bake,
|
|
145
|
+
path: a.path,
|
|
146
|
+
resumable: a.resumable,
|
|
147
|
+
signal: extra?.signal,
|
|
148
|
+
headers: a.as ? { "X-Verse-As": a.as } : undefined,
|
|
149
|
+
onProgress: (pr) => void notify(pr.fraction * 0.5, 1, `Uploading ${origin}: ${Math.round(pr.fraction * 100)}%`),
|
|
150
|
+
});
|
|
151
|
+
job = r.job;
|
|
152
|
+
}
|
|
153
|
+
await notify(0.5, 1, "Uploaded; Verse is building the scene");
|
|
154
|
+
if (wait === 0)
|
|
155
|
+
return ok(`Uploaded ${origin}. The build is running; check it with get_scene_status (scene "${job}").`, { scene: job, status: "compiling" });
|
|
156
|
+
let rec;
|
|
157
|
+
try {
|
|
158
|
+
rec = await client.waitForJob(job, {
|
|
159
|
+
timeoutMs: wait * 1000,
|
|
160
|
+
signal: extra?.signal,
|
|
161
|
+
onProgress: (r) => void notify(0.5 + 0.5 * (r.progress ?? 0), 1, `Building: ${r.stage ?? r.status}${r.etaText ? `, ${r.etaText}` : ""}`),
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
catch (e) {
|
|
165
|
+
if (e instanceof VerseError && e.code === "timeout") {
|
|
166
|
+
return ok(`Uploaded ${origin}. The build is still running after ${wait}s; check it with get_scene_status (scene "${job}").`, { scene: job, status: "compiling" });
|
|
167
|
+
}
|
|
168
|
+
throw e;
|
|
169
|
+
}
|
|
170
|
+
let visibility;
|
|
171
|
+
if (a.visibility) {
|
|
172
|
+
needAccount("Setting visibility");
|
|
173
|
+
visibility = (await client.scenes.setVisibility(job, a.visibility)).visibility;
|
|
174
|
+
}
|
|
175
|
+
const link = linkOf(rec);
|
|
176
|
+
const note = visibility === "private" ? " The scene is private: call create_share_link to get a link that opens it." : "";
|
|
177
|
+
return ok(`Done. Open the scene: ${link}${note}`, {
|
|
178
|
+
scene: job,
|
|
179
|
+
status: "done",
|
|
180
|
+
link,
|
|
181
|
+
kind: rec.path ?? rec.stats?.mode ?? "streamed",
|
|
182
|
+
...(visibility ? { visibility } : {}),
|
|
183
|
+
...(rec.arUrl ? { arUrl: rec.arUrl } : {}),
|
|
184
|
+
...(rec.fixes ? { fixes: rec.fixes } : {}),
|
|
185
|
+
});
|
|
186
|
+
}));
|
|
187
|
+
// ── get_scene_status ──────────────────────────────────────────────────
|
|
188
|
+
server.registerTool("get_scene_status", {
|
|
189
|
+
title: "Check a scene's build status",
|
|
190
|
+
description: "Check whether an uploaded scene has finished building. Returns `status` (compiling | done | error), the stage, progress 0..1, an ETA while building, and the `link` once done. " +
|
|
191
|
+
"Job records are kept for 2 hours after upload; older scenes are looked up in your account (needs VERSE_API_KEY).",
|
|
192
|
+
inputSchema: { scene: sceneArg },
|
|
193
|
+
annotations: { title: "Scene build status", readOnlyHint: true, openWorldHint: true },
|
|
194
|
+
}, guard(async (a) => {
|
|
195
|
+
const id = sceneIdOf(a.scene);
|
|
196
|
+
let rec = null;
|
|
197
|
+
try {
|
|
198
|
+
rec = await client.job(id);
|
|
199
|
+
}
|
|
200
|
+
catch (e) {
|
|
201
|
+
if (!(e instanceof VerseError && e.code === "unknown_job"))
|
|
202
|
+
throw e;
|
|
203
|
+
}
|
|
204
|
+
if (rec) {
|
|
205
|
+
if (rec.status === "done") {
|
|
206
|
+
const link = linkOf(rec);
|
|
207
|
+
return ok(`Done. Open the scene: ${link}`, { scene: id, status: "done", link, ...(rec.arUrl ? { arUrl: rec.arUrl } : {}) });
|
|
208
|
+
}
|
|
209
|
+
if (rec.status === "error") {
|
|
210
|
+
const msg = rec.errorInfo?.message || rec.error || "The build failed.";
|
|
211
|
+
return ok(`The build failed: ${msg}${rec.errorInfo?.fix ? ` ${rec.errorInfo.fix}` : ""}`, { scene: id, status: "error", error: rec.errorInfo?.code ?? "job_failed", message: msg });
|
|
212
|
+
}
|
|
213
|
+
const bits = [rec.stage, rec.progress != null ? `${Math.round(rec.progress * 100)}%` : null, rec.etaText].filter(Boolean).join(", ");
|
|
214
|
+
return ok(`Still building (${bits || "compiling"}).`, { scene: id, status: "compiling", stage: rec.stage, progress: rec.progress, eta: rec.etaText });
|
|
215
|
+
}
|
|
216
|
+
if (hasAccount) {
|
|
217
|
+
const s = await client.scenes.get(id);
|
|
218
|
+
const link = linkOf(s);
|
|
219
|
+
return ok(`Done. Open the scene: ${link}`, { scene: id, status: "done", link, visibility: s.visibility });
|
|
220
|
+
}
|
|
221
|
+
throw new ToolError("That job is unknown or its record expired after 2 hours; set VERSE_API_KEY to your account token to look up older scenes.");
|
|
222
|
+
}));
|
|
223
|
+
// ── list_scenes ───────────────────────────────────────────────────────
|
|
224
|
+
server.registerTool("list_scenes", {
|
|
225
|
+
title: "List your scenes",
|
|
226
|
+
description: "List the scenes owned by your Verse account, newest first: id, link, visibility, size, views and open review comments. Needs VERSE_API_KEY set to your account token.",
|
|
227
|
+
inputSchema: { limit: z.number().int().min(1).max(100).default(20).describe("Maximum number of scenes to return.") },
|
|
228
|
+
annotations: { title: "List scenes", readOnlyHint: true, openWorldHint: true },
|
|
229
|
+
}, guard(async (a) => {
|
|
230
|
+
needAccount("Listing scenes");
|
|
231
|
+
const all = await client.scenes.list();
|
|
232
|
+
const scenes = all.slice(0, a.limit ?? 20).map((s) => ({
|
|
233
|
+
id: s.id,
|
|
234
|
+
link: linkOf(s),
|
|
235
|
+
visibility: s.visibility,
|
|
236
|
+
kind: s.path ?? s.kind,
|
|
237
|
+
sizeMB: Math.round((s.sizeBytes / 1048576) * 10) / 10,
|
|
238
|
+
created: new Date(s.created).toISOString(),
|
|
239
|
+
opens: s.stats?.opens ?? 0,
|
|
240
|
+
openReviews: s.reviews?.open ?? 0,
|
|
241
|
+
}));
|
|
242
|
+
const text = scenes.length ? scenes.map((s) => `${s.id} ${s.visibility} ${s.sizeMB} MB ${s.link}`).join("\n") : "No scenes yet; upload one with upload_scene.";
|
|
243
|
+
return ok(`${scenes.length} of ${all.length} scenes.\n${text}`, { total: all.length, scenes });
|
|
244
|
+
}));
|
|
245
|
+
// ── create_share_link ─────────────────────────────────────────────────
|
|
246
|
+
server.registerTool("create_share_link", {
|
|
247
|
+
title: "Create a share link (set visibility)",
|
|
248
|
+
description: "Get a link to a scene you own, optionally changing who can open it. `visibility`: 'unlisted' (default; anyone with the link), 'public', or 'private' (opens only with a secret share token). " +
|
|
249
|
+
"For a private scene this mints a share token and returns a link that includes it (the token is shown once; keep the returned `shareId` to revoke it with revoke_share_link). " +
|
|
250
|
+
"Share links do not expire on their own; revoke them to cut access. Needs VERSE_API_KEY set to your account token.",
|
|
251
|
+
inputSchema: {
|
|
252
|
+
scene: sceneArg,
|
|
253
|
+
visibility: z.enum(["public", "unlisted", "private"]).optional().describe("Set the scene's visibility first. Omit to keep it as is."),
|
|
254
|
+
new_token: z.boolean().optional().describe("Mint a fresh private share token even if the scene is not private (e.g. to hand out revocable links)."),
|
|
255
|
+
autoplay_tour: z.boolean().default(false).describe("Open the link playing the scene's camera path (see list_camera_paths)."),
|
|
256
|
+
},
|
|
257
|
+
annotations: { title: "Create share link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
|
|
258
|
+
}, guard(async (a) => {
|
|
259
|
+
needAccount("Creating a share link");
|
|
260
|
+
const id = sceneIdOf(a.scene);
|
|
261
|
+
let visibility;
|
|
262
|
+
if (a.visibility)
|
|
263
|
+
visibility = (await client.scenes.setVisibility(id, a.visibility)).visibility;
|
|
264
|
+
else
|
|
265
|
+
visibility = (await client.scenes.get(id)).visibility;
|
|
266
|
+
const rec = await resolveScene(id);
|
|
267
|
+
let link;
|
|
268
|
+
let shareId;
|
|
269
|
+
if (visibility === "private" || a.new_token) {
|
|
270
|
+
const t = await client.scenes.shares.create(id);
|
|
271
|
+
link = client.shareLink(rec, { share: t.shareToken });
|
|
272
|
+
shareId = t.id;
|
|
273
|
+
}
|
|
274
|
+
else {
|
|
275
|
+
link = linkOf(rec);
|
|
276
|
+
}
|
|
277
|
+
if (a.autoplay_tour)
|
|
278
|
+
link += `${link.includes("?") ? "&" : "?"}autoplay=path`;
|
|
279
|
+
return ok(`${visibility === "private" ? "Private link (works for anyone who has it until revoked)" : "Link"}: ${link}`, { scene: id, visibility, link, ...(shareId ? { shareId } : {}) });
|
|
280
|
+
}));
|
|
281
|
+
server.registerTool("revoke_share_link", {
|
|
282
|
+
title: "Revoke a private share link",
|
|
283
|
+
description: "Revoke one private share token so its link stops working. Use the `shareId` returned by create_share_link, or call with only `scene` to list the active share ids. Needs an account token.",
|
|
284
|
+
inputSchema: { scene: sceneArg, share_id: z.string().min(1).max(64).optional().describe("The shareId to revoke. Omit to list active ones.") },
|
|
285
|
+
annotations: { title: "Revoke share link", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
|
|
286
|
+
}, guard(async (a) => {
|
|
287
|
+
needAccount("Revoking a share link");
|
|
288
|
+
const id = sceneIdOf(a.scene);
|
|
289
|
+
if (!a.share_id) {
|
|
290
|
+
const list = await client.scenes.shares.list(id);
|
|
291
|
+
return ok(list.length ? `Active share links: ${list.map((s) => `${s.id} (…${s.suffix})`).join(", ")}.` : "There are no active share links.", { scene: id, shares: list });
|
|
292
|
+
}
|
|
293
|
+
await client.scenes.shares.revoke(id, a.share_id);
|
|
294
|
+
return ok(`Revoked share link ${a.share_id}.`, { scene: id, revoked: a.share_id });
|
|
295
|
+
}));
|
|
296
|
+
// ── get_embed_code ────────────────────────────────────────────────────
|
|
297
|
+
server.registerTool("get_embed_code", {
|
|
298
|
+
title: "Get embed code for a scene",
|
|
299
|
+
description: "Get copy-paste code to embed a scene in a web page: an `iframe` (works anywhere), the `<verse-viewer>` element plus its `script`, and the plain `url`. " +
|
|
300
|
+
"For a private scene pass the share token from create_share_link as `share_token`.",
|
|
301
|
+
inputSchema: {
|
|
302
|
+
scene: sceneArg,
|
|
303
|
+
share_token: z.string().regex(/^[0-9a-f]{32}$/).optional().describe("Share token of a private scene."),
|
|
304
|
+
aspect: z.enum(["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "fill"]).optional().describe("Frame shape. Default 16:9."),
|
|
305
|
+
load: z.enum(["lazy", "eager", "tap"]).optional().describe("'lazy' (default) loads when scrolled into view, 'tap' only on tap, 'eager' immediately."),
|
|
306
|
+
background: z.string().max(40).optional().describe("'rrggbb', 'transparent' or 'studio:warm'."),
|
|
307
|
+
title: z.string().max(120).optional().describe("Accessible title for the iframe."),
|
|
308
|
+
},
|
|
309
|
+
annotations: { title: "Embed code", readOnlyHint: true, openWorldHint: true },
|
|
310
|
+
}, guard(async (a) => {
|
|
311
|
+
const id = sceneIdOf(a.scene);
|
|
312
|
+
const rec = await resolveScene(id);
|
|
313
|
+
const e = client.embedCode(rec, { share: a.share_token, aspect: a.aspect, load: a.load, background: a.background, title: a.title });
|
|
314
|
+
return ok(`Embed with:\n${e.iframe}\n\nOr the web component:\n${e.script}\n${e.element}`, { scene: id, iframe: e.iframe, element: e.element, script: e.script, url: e.url });
|
|
315
|
+
}));
|
|
316
|
+
// ── camera paths ──────────────────────────────────────────────────────
|
|
317
|
+
const key = z.object({
|
|
318
|
+
p: z.tuple([z.number(), z.number(), z.number()]).describe("Eye position [x,y,z] in metres (y up)."),
|
|
319
|
+
f: z.tuple([z.number(), z.number(), z.number()]).describe("Forward direction [x,y,z]."),
|
|
320
|
+
fov: z.number().min(5).max(150).optional(),
|
|
321
|
+
dur: z.number().positive().max(600).optional().describe("Seconds to the next key (auto if omitted)."),
|
|
322
|
+
hold: z.number().min(0).max(600).optional().describe("Seconds to dwell here."),
|
|
323
|
+
ease: z.enum(["smooth", "stop", "linear"]).optional(),
|
|
324
|
+
look: z.tuple([z.number(), z.number(), z.number()]).optional().describe("Look-at target."),
|
|
325
|
+
label: z.string().max(80).optional().describe("Chapter name."),
|
|
326
|
+
});
|
|
327
|
+
server.registerTool("list_camera_paths", {
|
|
328
|
+
title: "List a scene's camera paths",
|
|
329
|
+
description: "List the guided-tour camera paths of a scene (every scene gets an automatic default path after it builds) and the default one. Returns ids, names, modes (walk/fly), key counts and chapter labels, plus a ready-to-open `tourLink` that autoplays the default path.",
|
|
330
|
+
inputSchema: { scene: sceneArg },
|
|
331
|
+
annotations: { title: "List camera paths", readOnlyHint: true, openWorldHint: true },
|
|
332
|
+
}, guard(async (a) => {
|
|
333
|
+
const id = sceneIdOf(a.scene);
|
|
334
|
+
const r = await client.request(`/v1/scenes/${encodeURIComponent(id)}/paths`);
|
|
335
|
+
const base = linkOf(await resolveScene(id));
|
|
336
|
+
const tourLink = `${base}${base.includes("?") ? "&" : "?"}autoplay=path`;
|
|
337
|
+
const text = r.paths.length ? r.paths.map((p) => `${p.id}${p.id === r.default ? " (default)" : ""} ${p.name} ${p.mode} ${p.keys} keys${p.auto ? " auto" : ""}`).join("\n") : "No camera paths yet.";
|
|
338
|
+
return ok(`${text}\nTour link: ${tourLink}`, { scene: id, default: r.default, paths: r.paths, tourLink });
|
|
339
|
+
}));
|
|
340
|
+
server.registerTool("set_camera_path", {
|
|
341
|
+
title: "Create a camera path (guided tour)",
|
|
342
|
+
description: "Create a camera path: a guided walk or fly-through the share link can play. Give 2 to 256 keyframes, each with an eye position `p`, forward direction `f` and optional fov, dwell `hold`, `ease`, look-at target and chapter `label`. " +
|
|
343
|
+
"The first path becomes the scene's default; set `make_default` to promote later ones. If you only want a good default tour, use reset_auto_camera_path instead. Owner only; needs an account token.",
|
|
344
|
+
inputSchema: {
|
|
345
|
+
scene: sceneArg,
|
|
346
|
+
name: z.string().min(1).max(80).default("Walkthrough"),
|
|
347
|
+
mode: z.enum(["walk", "fly"]).default("walk").describe("'walk' keeps eye height over the floor and avoids walls; 'fly' goes anywhere."),
|
|
348
|
+
keys: z.array(key).min(2).max(256),
|
|
349
|
+
speed: z.number().positive().max(100).optional().describe("Metres per second for keys without `dur`."),
|
|
350
|
+
make_default: z.boolean().default(false),
|
|
351
|
+
},
|
|
352
|
+
annotations: { title: "Create camera path", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
|
|
353
|
+
}, guard(async (a) => {
|
|
354
|
+
needAccount("Creating a camera path");
|
|
355
|
+
const id = sceneIdOf(a.scene);
|
|
356
|
+
const body = { name: a.name, mode: a.mode, keys: a.keys };
|
|
357
|
+
if (a.speed)
|
|
358
|
+
body.speed = a.speed;
|
|
359
|
+
const r = await client.request(`/v1/scenes/${encodeURIComponent(id)}/paths`, { method: "POST", body, retries: 0 });
|
|
360
|
+
if (a.make_default && !r.default)
|
|
361
|
+
await client.request(`/v1/scenes/${encodeURIComponent(id)}/paths`, { method: "PUT", body: { default: r.id } });
|
|
362
|
+
const base = linkOf(await resolveScene(id));
|
|
363
|
+
const tourLink = `${base}${base.includes("?") ? "&" : "?"}autoplay=path&path=${r.id}`;
|
|
364
|
+
return ok(`Created path ${r.id} with ${r.keys} keys. Tour link: ${tourLink}`, { scene: id, pathId: r.id, keys: r.keys, default: r.default || !!a.make_default, tourLink });
|
|
365
|
+
}));
|
|
366
|
+
server.registerTool("reset_auto_camera_path", {
|
|
367
|
+
title: "Plan the automatic tour",
|
|
368
|
+
description: "Re-plan the scene's automatic camera path (an eye-height walkthrough for interiors, a drone fly-through for exteriors, a 360 orbit for products) and make it the default. Returns a link that autoplays it. Owner only; needs an account token.",
|
|
369
|
+
inputSchema: { scene: sceneArg },
|
|
370
|
+
annotations: { title: "Plan automatic tour", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
|
|
371
|
+
}, guard(async (a) => {
|
|
372
|
+
needAccount("Planning a tour");
|
|
373
|
+
const id = sceneIdOf(a.scene);
|
|
374
|
+
const r = await client.request(`/v1/scenes/${encodeURIComponent(id)}/paths/auto`, { method: "POST", retries: 0 });
|
|
375
|
+
const base = linkOf(await resolveScene(id));
|
|
376
|
+
const tourLink = `${base}${base.includes("?") ? "&" : "?"}autoplay=path`;
|
|
377
|
+
const article = /^[aeiou]/i.test(String(r.kind)) ? "an" : "a";
|
|
378
|
+
return ok(`Planned ${article} ${r.kind} tour "${r.name}" (${r.keys.length} keys). Tour link: ${tourLink}`, { scene: id, pathId: r.id, kind: r.kind, tourLink });
|
|
379
|
+
}));
|
|
380
|
+
return server;
|
|
381
|
+
}
|
package/dist/util.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** Pull a scene id out of an id, a share link, an ingest URL or a /v1 path. */
|
|
2
|
+
export declare function sceneIdOf(input: string): string;
|
|
3
|
+
/** A failure whose message is already the one plain sentence for the model. */
|
|
4
|
+
export declare class ToolError extends Error {
|
|
5
|
+
}
|
|
6
|
+
/** One plain sentence for any failure; never includes credentials. */
|
|
7
|
+
export declare function plainError(e: unknown, hasAccount: boolean): string;
|
|
8
|
+
/** Defensive: strip anything shaped like a credential from a message. */
|
|
9
|
+
export declare function scrub(s: string): string;
|
package/dist/util.js
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { VerseError } from "@ctruhtech/verse-sdk";
|
|
2
|
+
/** Pull a scene id out of an id, a share link, an ingest URL or a /v1 path. */
|
|
3
|
+
export function sceneIdOf(input) {
|
|
4
|
+
const s = input.trim();
|
|
5
|
+
const m = /[?&](?:vpk|vsp|vpc|glb|model|scene)=(?:[^&]*?ingest\/|)([A-Za-z0-9_-]+?)(?:\.fidelity)?(?:\.(?:vpk|vsp|vpc|glb|stage|usdz)|(?=&|$))/.exec(s) ||
|
|
6
|
+
/\/ingest\/([A-Za-z0-9_-]+?)(?:\.[a-z.]+)?(?:[?#]|$)/.exec(s) ||
|
|
7
|
+
/\/v1\/(?:ingest|scenes)\/([A-Za-z0-9_-]+)/.exec(s);
|
|
8
|
+
const id = m ? m[1] : s;
|
|
9
|
+
if (!/^[A-Za-z0-9_-]{3,160}$/.test(id))
|
|
10
|
+
throw new ToolError("That does not look like a Verse scene id or link.");
|
|
11
|
+
return id;
|
|
12
|
+
}
|
|
13
|
+
/** A failure whose message is already the one plain sentence for the model. */
|
|
14
|
+
export class ToolError extends Error {
|
|
15
|
+
}
|
|
16
|
+
const sentence = (s) => {
|
|
17
|
+
const t = s.replace(/\s+/g, " ").trim();
|
|
18
|
+
const cap = t.charAt(0).toUpperCase() + t.slice(1);
|
|
19
|
+
return /[.!?]$/.test(cap) ? cap : `${cap}.`;
|
|
20
|
+
};
|
|
21
|
+
/** One plain sentence for any failure; never includes credentials. */
|
|
22
|
+
export function plainError(e, hasAccount) {
|
|
23
|
+
if (e instanceof ToolError)
|
|
24
|
+
return sentence(e.message);
|
|
25
|
+
if (e instanceof VerseError) {
|
|
26
|
+
if (e.status === 401 && !hasAccount)
|
|
27
|
+
return "Uploading needs a free Verse account: sign up at verse.ctruh.com/signin, create an API key on your Account page and set it as VERSE_API_KEY.";
|
|
28
|
+
if (e.status === 401)
|
|
29
|
+
return "The server rejected the Verse credential; check VERSE_API_KEY.";
|
|
30
|
+
if (e.status === 404 && e.code !== "unknown_job" && !hasAccount)
|
|
31
|
+
return "Not found, and no account token is set; owner-only actions need VERSE_API_KEY set to your account token.";
|
|
32
|
+
if (e.code === "unknown_job")
|
|
33
|
+
return "That job is unknown or its record expired after 2 hours; use list_scenes to find the scene.";
|
|
34
|
+
if (e.code === "timeout")
|
|
35
|
+
return "Timed out waiting for the build; it is probably still running, so check it with get_scene_status.";
|
|
36
|
+
const info = e.errorInfo;
|
|
37
|
+
const msg = info?.message || e.message;
|
|
38
|
+
const fix = info?.fix && !msg.includes(info.fix) ? ` ${info.fix}` : "";
|
|
39
|
+
return sentence(scrub(`${msg}${fix}`).slice(0, 400));
|
|
40
|
+
}
|
|
41
|
+
const m = e?.message ?? String(e);
|
|
42
|
+
return sentence(scrub(m).slice(0, 300));
|
|
43
|
+
}
|
|
44
|
+
/** Defensive: strip anything shaped like a credential from a message. */
|
|
45
|
+
export function scrub(s) {
|
|
46
|
+
return s.replace(/\bvk_[A-Za-z0-9]{6,}\b/g, "vk_***").replace(/\b[0-9a-f]{32,64}\b/gi, "***");
|
|
47
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,67 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ctruhtech/verse-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "MCP server for Verse: let Claude, ChatGPT, Cursor and other AI agents turn 3D files into shareable, embeddable Verse links. stdio and Streamable HTTP.",
|
|
5
|
+
"homepage": "https://verse.ctruh.com/docs/#/mcp",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/dev-vinayagastya/verse-mcp.git"
|
|
9
|
+
},
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://github.com/dev-vinayagastya/verse-mcp/issues"
|
|
12
|
+
},
|
|
13
|
+
"author": "Ctruh <hello@ctruh.com>",
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"type": "module",
|
|
16
|
+
"main": "./dist/index.js",
|
|
17
|
+
"types": "./dist/index.d.ts",
|
|
18
|
+
"bin": {
|
|
19
|
+
"verse-mcp": "./dist/cli.js"
|
|
20
|
+
},
|
|
21
|
+
"exports": {
|
|
22
|
+
".": {
|
|
23
|
+
"types": "./dist/index.d.ts",
|
|
24
|
+
"default": "./dist/index.js"
|
|
25
|
+
},
|
|
26
|
+
"./package.json": "./package.json"
|
|
27
|
+
},
|
|
28
|
+
"files": [
|
|
29
|
+
"dist",
|
|
30
|
+
"README.md",
|
|
31
|
+
"CHANGELOG.md",
|
|
32
|
+
"LICENSE",
|
|
33
|
+
"server.json"
|
|
34
|
+
],
|
|
35
|
+
"engines": {
|
|
36
|
+
"node": ">=20"
|
|
37
|
+
},
|
|
38
|
+
"mcpName": "io.github.dev-vinayagastya/verse-mcp",
|
|
39
|
+
"scripts": {
|
|
40
|
+
"build": "tsc -p tsconfig.json",
|
|
41
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
42
|
+
"test": "npm run build && node --test test/mock.test.mjs",
|
|
43
|
+
"prepublishOnly": "npm run typecheck && npm test"
|
|
44
|
+
},
|
|
45
|
+
"dependencies": {
|
|
46
|
+
"@ctruhtech/verse-sdk": "^4.0.0",
|
|
47
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
48
|
+
"zod": "3.25.76"
|
|
49
|
+
},
|
|
50
|
+
"devDependencies": {
|
|
51
|
+
"@types/node": "^22.10.0",
|
|
52
|
+
"typescript": "^5.6.3"
|
|
53
|
+
},
|
|
54
|
+
"keywords": [
|
|
55
|
+
"mcp",
|
|
56
|
+
"model-context-protocol",
|
|
57
|
+
"3d",
|
|
58
|
+
"gltf",
|
|
59
|
+
"glb",
|
|
60
|
+
"verse",
|
|
61
|
+
"ctruh",
|
|
62
|
+
"ai-agents"
|
|
63
|
+
],
|
|
64
|
+
"publishConfig": {
|
|
65
|
+
"access": "public"
|
|
66
|
+
}
|
|
67
|
+
}
|
package/server.json
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.dev-vinayagastya/verse-mcp",
|
|
4
|
+
"title": "Verse",
|
|
5
|
+
"description": "Turn 3D files into shareable, embeddable Verse links from any AI assistant.",
|
|
6
|
+
"version": "0.1.1",
|
|
7
|
+
"repository": { "url": "https://github.com/dev-vinayagastya/verse-mcp", "source": "github" },
|
|
8
|
+
"packages": [
|
|
9
|
+
{
|
|
10
|
+
"registryType": "npm",
|
|
11
|
+
"identifier": "@ctruhtech/verse-mcp",
|
|
12
|
+
"version": "0.1.1",
|
|
13
|
+
"transport": { "type": "stdio" },
|
|
14
|
+
"environmentVariables": [
|
|
15
|
+
{ "name": "VERSE_API_KEY", "description": "Your Verse API key (Account page, API keys card) or account token. Sent as Authorization: Bearer.", "isRequired": true, "isSecret": true }
|
|
16
|
+
]
|
|
17
|
+
}
|
|
18
|
+
]
|
|
19
|
+
}
|