@atropical/stroq-studio-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,7 @@
 # stroq-studio-mcp
 
-Connects an AI agent (Claude Code, Claude Desktop or any MCP client) to an open
+Connects your AI agent (any MCP client: Claude Code, Codex, Cursor, Claude
+Desktop and others) to an open
 [Strōq World Studio](https://studio.stroq.club) tab, so the agent can build
 cycling courses with the Studio's own tools: routes, road pieces, land,
 landscapes, scenery, screenshots and your comments.
@@ -21,9 +22,16 @@ MCP client  ⇄ stdio ⇄  stroq-studio-mcp  ⇄ ws://127.0.0.1:3021 ⇄  Studio
 claude mcp add stroq-studio -- npx -y @atropical/stroq-studio-mcp
 ```
 
-### Claude Desktop
+### Codex CLI
 
-Add it to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+```sh
+codex mcp add stroq-studio -- npx -y @atropical/stroq-studio-mcp
+```
+
+### Claude Desktop, Cursor and other MCP clients
+
+Add it to the client's MCP config (Claude Desktop: `claude_desktop_config.json`,
+Settings → Developer → Edit Config; Cursor: `~/.cursor/mcp.json`):
 
 ```json
 {
@@ -36,15 +44,15 @@ Add it to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 }
 ```
 
-Then restart Claude Desktop.
+Then restart the client.
 
 ### Connect the Studio
 
 1. Start your agent. The relay prints one pairing code, `port:TOKEN`, such as
-   `3021:ABCDE-FGHIJ-KLMNO-PQRST-UVW234`, on stderr (Claude Code: `/mcp` shows
-   the server log). Or ask the agent to "connect to the Studio": its
+   `3021:ABCDE-FGHIJ-KLMNO-PQRST-UVW234`, on stderr (most clients show the
+   server log). Or ask the agent to "connect to the Studio": its
    `studio_connection` tool returns it.
-2. In the Studio: **Help → Connect an agent**. Paste the code and switch
+2. In the Studio: **Tools → AI agent → Connect…**. Paste the code and switch
    **Connect** on. The light turns on when it is connected. (A token pasted on
    its own means port 3021.)
 3. Ask the agent for something, e.g. "build a 10 km alpine climb with a village
@@ -84,6 +92,31 @@ tools appear (the relay sends `notifications/tools/list_changed`), for example
 `resolve_comment` and `wait_for_comments`. While connected the agent owns the
 Studio's comments.
 
+`import_model_file` is the one tool the relay handles itself: it reads a model
+from this computer (`path`, absolute; optional `name`, `category`, `tags`) and
+sends it to the tab in 1 MB parts over the sealed connection; the tab imports
+it into the Library the same way as the Library's own file import (optimised,
+scaled, thumbnail) and answers with the new asset id and its thumbnail. It is
+listed only while a connected tab offers it.
+
+## Using it with Blender MCP
+
+With [blender-mcp](https://github.com/ahujasid/blender-mcp) added alongside,
+an agent can model something in Blender and put it straight into the Studio:
+
+```sh
+claude mcp add stroq-studio -- npx -y @atropical/stroq-studio-mcp
+claude mcp add blender -- uvx blender-mcp
+```
+
+Open Blender with the blender-mcp add-on connected, connect the Studio, then
+ask, for example: "Model a small stone well in Blender, export it as GLB to
+/tmp/well.glb and add it to the Studio Library as a building." The agent
+models it through Blender MCP, exports with
+`bpy.ops.export_scene.gltf(filepath='/tmp/well.glb', export_format='GLB')`,
+and calls `import_model_file` with that path. Model in metres, Z up (the glTF
+exporter turns it Y up); the Studio scales it to a real height by category.
+
 ## Security
 
 - Listens on `127.0.0.1` only; nothing on your network can connect.
@@ -108,8 +141,15 @@ Studio's comments.
 - The resume key for reloads is derived from the proof on both sides and is
   never sent.
 - One tab at a time.
-- It stores nothing and reads no files: every tool runs inside the Studio tab,
-  on the content in that browser.
+- It stores nothing, and every tool runs inside the Studio tab, on the content
+  in that browser. The only files it reads are the ones you or your agent name
+  in `import_model_file`: a `.glb`, a `.gltf` or a `.zip`, at most 100 MB in
+  all. A glTF (also inside a zip) may bring only `.bin` buffers whose size
+  matches their `byteLength` and PNG, JPEG, WebP or KTX2 images whose first
+  bytes match their type, from its folder and at most two levels down; a zip
+  holds only those and the model. It refuses relative paths, symlinks, hidden
+  files or folders (a name starting with `.`) and anything whose real path is
+  outside the model's folder.
 
 ## Protocol
 

package/dist/args.js

@@ -4,7 +4,7 @@
 import { DEFAULT_ORIGINS, DEFAULT_PORT } from './relay.js';
 export const HELP = `Usage: stroq-studio-mcp [--port <n>] [--origin <url>]...
 
-Connects an MCP client (Claude Code, Claude Desktop) to an open Strōq World Studio tab.
+Connects any MCP client (Claude Code, Codex, Cursor, Claude Desktop…) to an open Strōq World Studio tab.
 
   --port <n>      Fixed WebSocket port on 127.0.0.1 (fails if busy). Default:
                   ${DEFAULT_PORT}, or any free port when that one is taken
@@ -12,7 +12,7 @@ Connects an MCP client (Claude Code, Claude Desktop) to an open Strōq World Stu
                   the defaults (${DEFAULT_ORIGINS.join(', ')})
   --help          This text
 
-The pairing string (port:TOKEN) is printed on stderr; paste it in the Studio under Help → Connect an agent.`;
+The pairing string (port:TOKEN) is printed on stderr; paste it in the Studio under Tools → AI agent → Connect….`;
 export function parseArgs(argv) {
     let port;
     const origins = [];

package/dist/mcp.d.ts

@@ -10,5 +10,36 @@ export declare const CONNECTION_TOOL: {
         properties: {};
     };
 };
-export declare const INSTRUCTIONS = "Tools of an open Str\u014Dq World Studio tab, relayed. If only studio_connection is listed, no tab is connected yet: call it and tell the person the pairing string (port:TOKEN) to paste under Help \u2192 Connect an agent. While connected this agent owns the Studio comments: ack_comment straight away, get_comment for the picture and thread, do the work, then reply_comment saying what changed.";
+/** Handled here, not passed through: the relay reads the file and sends it to the tab in parts. */
+export declare const IMPORT_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            category: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const INSTRUCTIONS = "Tools of an open Str\u014Dq World Studio tab, relayed. If only studio_connection is listed, no tab is connected yet: call it and tell the person the pairing string (port:TOKEN) to paste under Tools \u2192 AI agent \u2192 Connect\u2026. While connected this agent owns the Studio comments: ack_comment straight away, get_comment for the picture and thread, do the work, then reply_comment saying what changed.";
 export declare function createMcpServer(relay: Relay): Server;

package/dist/mcp.js

@@ -4,20 +4,42 @@
 /** The MCP side: the tools learnt from the tab, plus studio_connection (always there). */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { MAX_MODEL_BYTES } from './modelFile.js';
+import { IMPORT_FILE, IMPORT_PART } from './protocol.js';
 export const VERSION = '0.1.0';
 export const CONNECTION_TOOL = {
     name: 'studio_connection',
-    description: 'Whether a Strōq World Studio tab is connected to this relay. When none is, it gives the pairing string (port:TOKEN) to tell the person: in the Studio, Help → Connect an agent, paste it, switch Connect on. The Studio tools appear once the tab connects.',
+    description: 'Whether a Strōq World Studio tab is connected to this relay. When none is, it gives the pairing string (port:TOKEN) to tell the person: in the Studio, Tools → AI agent → Connect…, paste it, switch Connect on. The Studio tools appear once the tab connects.',
     inputSchema: { type: 'object', properties: {} },
 };
-export const INSTRUCTIONS = 'Tools of an open Strōq World Studio tab, relayed. If only studio_connection is listed, no tab is connected yet: call it and tell the person the pairing string (port:TOKEN) to paste under Help → Connect an agent. While connected this agent owns the Studio comments: ack_comment straight away, get_comment for the picture and thread, do the work, then reply_comment saying what changed.';
+/** Handled here, not passed through: the relay reads the file and sends it to the tab in parts. */
+export const IMPORT_TOOL = {
+    name: IMPORT_FILE,
+    description: `Adds a model file from this computer to the Studio Library (optimised, scaled, with a thumbnail). For a model made in Blender: export it as GLB (File → Export → glTF 2.0, format glb) to an absolute path, then call this. Takes .glb, .gltf (its buffers and textures from the same folder) or .zip, up to ${MAX_MODEL_BYTES / 1048576} MB; no symlinks. Returns the new asset id and its thumbnail.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Absolute path of the .glb, .gltf or .zip' },
+            name: { type: 'string', description: 'Name in the Library (default: from the file name)' },
+            category: { type: 'string', enum: ['prop', 'plant', 'rock', 'tree', 'building', 'vehicle', 'character'], description: 'Library category (default prop)' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Search tags' },
+        },
+        required: ['path'],
+    },
+};
+const HIDDEN = new Set([CONNECTION_TOOL.name, IMPORT_FILE, IMPORT_PART]);
+export const INSTRUCTIONS = 'Tools of an open Strōq World Studio tab, relayed. If only studio_connection is listed, no tab is connected yet: call it and tell the person the pairing string (port:TOKEN) to paste under Tools → AI agent → Connect…. While connected this agent owns the Studio comments: ack_comment straight away, get_comment for the picture and thread, do the work, then reply_comment saying what changed.';
 export function createMcpServer(relay) {
     const server = new Server({ name: 'stroq-studio', version: VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [CONNECTION_TOOL, ...relay.tools.filter((t) => t.name !== CONNECTION_TOOL.name)] }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [CONNECTION_TOOL, ...relay.tools.filter((t) => !HIDDEN.has(t.name)), ...(relay.canImport ? [IMPORT_TOOL] : [])] }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const { name, arguments: args } = req.params;
         if (name === CONNECTION_TOOL.name)
             return { content: [{ type: 'text', text: JSON.stringify(relay.status(), null, 2) }] };
+        if (name === IMPORT_FILE)
+            return relay.importModelFile((args ?? {}));
+        if (name === IMPORT_PART)
+            return { content: [{ type: 'text', text: `Use ${IMPORT_FILE}` }], isError: true };
         return relay.call(name, (args ?? {}));
     });
     return server;

package/dist/modelFile.d.ts

@@ -0,0 +1,33 @@
+export declare const MAX_MODEL_BYTES: number;
+/** Bytes per chunk sent to the tab (base64 makes a frame about 1.4 MB). */
+export declare const CHUNK_BYTES: number;
+export declare const MODEL_EXTENSIONS: string[];
+/** What a .gltf (or a zip) may carry beside the model. */
+export declare const SIBLING_EXTENSIONS: string[];
+/** Folders below the model's own that a sibling may sit in. */
+export declare const MAX_DEPTH = 2;
+export interface ModelFile {
+    /** Path relative to the model's folder, with forward slashes (the main file is its base name). */
+    name: string;
+    data: Uint8Array;
+}
+export interface Sibling {
+    path: string;
+    /** buffers[].byteLength, when the glTF names it as a buffer. */
+    byteLength?: number;
+}
+export declare class ModelFileError extends Error {
+}
+/** The files a .gltf names (buffers and images), checked; data: URIs are inside the file already. */
+export declare function gltfSiblings(json: unknown): Sibling[];
+/** An image's first bytes must match its type (a .env renamed .png is refused). */
+export declare function checkImage(name: string, d: Uint8Array): void;
+/**
+ * A zip's entries, read and checked without trusting it: only .glb/.gltf and
+ * the sibling types, no hidden segments, at most MAX_DEPTH folders down,
+ * stored or deflated, no encryption or zip64, within max. A .gltf inside is
+ * checked like one on disk (its siblings must be in the zip); images by type.
+ */
+export declare function checkZip(zip: Uint8Array, max?: number): void;
+/** Reads a model for import, checked as above. Throws ModelFileError with a message for the agent. */
+export declare function readModelFiles(path: string, max?: number): Promise<ModelFile[]>;

package/dist/modelFile.js

@@ -0,0 +1,255 @@
+// stroq-studio-mcp: the relay between an MCP client and a Strōq World Studio tab.
+// Copyright (C) 2026 Atropical
+// SPDX-License-Identifier: GPL-3.0-only
+/**
+ * import_model_file's local side: the one place the relay reads files. Only a
+ * .glb, a .gltf (with the .bin buffers and PNG/JPEG/WebP/KTX2 images it
+ * names, from its folder and at most two levels down) or a .zip of the same;
+ * no symlinks, no hidden files, nothing outside the model's folder; buffer
+ * sizes must match the glTF and images their type; at most MAX_MODEL_BYTES.
+ */
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+export const MAX_MODEL_BYTES = 100 * 1024 * 1024;
+/** Bytes per chunk sent to the tab (base64 makes a frame about 1.4 MB). */
+export const CHUNK_BYTES = 1024 * 1024;
+export const MODEL_EXTENSIONS = ['.glb', '.gltf', '.zip'];
+/** What a .gltf (or a zip) may carry beside the model. */
+export const SIBLING_EXTENSIONS = ['.bin', '.png', '.jpg', '.jpeg', '.webp', '.ktx2'];
+/** Folders below the model's own that a sibling may sit in. */
+export const MAX_DEPTH = 2;
+const MAX_SIBLINGS = 200;
+export class ModelFileError extends Error {
+}
+const mb = (n) => `${Math.round(n / 1048576)} MB`;
+/** A regular file, not a symlink, whose real path is inside root (a real path). Returns its size. */
+async function plainFileInside(path, root) {
+    let st;
+    try {
+        st = await lstat(path);
+    }
+    catch {
+        throw new ModelFileError(`No file at ${path}`);
+    }
+    if (st.isSymbolicLink())
+        throw new ModelFileError(`${path} is a symlink; give the real file`);
+    if (!st.isFile())
+        throw new ModelFileError(`${path} is not a file`);
+    const rel = relative(root, await realpath(path));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        throw new ModelFileError(`${path} is outside the model's folder`);
+    return st.size;
+}
+/** A relative path's checks: no scheme, absolute, '..' or hidden segment; an allowed type; at most MAX_DEPTH folders down. */
+function checkRelative(p, allowed, what) {
+    const parts = p.replace(/\\/g, '/').split('/');
+    if (!p || /^[a-z][a-z0-9+.-]*:/i.test(p) || /^[\\/]/.test(p) || parts.some((s) => s === '' || s === '..'))
+        throw new ModelFileError(`${what} names a file outside its folder: ${p}`);
+    if (parts.some((s) => s.startsWith('.')))
+        throw new ModelFileError(`${what} names a hidden file: ${p}`);
+    if (parts.length - 1 > MAX_DEPTH)
+        throw new ModelFileError(`${what} names a file more than ${MAX_DEPTH} folders down: ${p}`);
+    if (!allowed.includes(extname(p).toLowerCase()))
+        throw new ModelFileError(`${what} names ${p}: only ${allowed.join(', ')} files may come with a model`);
+    return parts.join('/');
+}
+const IMAGE_EXTENSIONS = SIBLING_EXTENSIONS.filter((e) => e !== '.bin');
+/** The files a .gltf names (buffers and images), checked; data: URIs are inside the file already. */
+export function gltfSiblings(json) {
+    const out = new Map();
+    const doc = (json ?? {});
+    const add = (item, buffer) => {
+        const uri = item?.uri;
+        if (typeof uri !== 'string' || uri.startsWith('data:'))
+            return;
+        let p;
+        try {
+            p = decodeURIComponent(uri);
+        }
+        catch {
+            throw new ModelFileError(`Bad file name in the glTF: ${uri}`);
+        }
+        const path = checkRelative(p, buffer ? ['.bin'] : IMAGE_EXTENSIONS, 'The glTF');
+        const prev = out.get(path) ?? { path };
+        if (buffer) {
+            const len = item?.byteLength;
+            if (typeof len !== 'number' || !Number.isInteger(len) || len < 0)
+                throw new ModelFileError(`The glTF buffer ${uri} has no byteLength`);
+            if (prev.byteLength !== undefined && prev.byteLength !== len)
+                throw new ModelFileError(`The glTF names ${uri} with two sizes`);
+            prev.byteLength = len;
+        }
+        else if (prev.byteLength !== undefined)
+            throw new ModelFileError(`The glTF names ${uri} as a buffer and an image`);
+        out.set(path, prev);
+    };
+    for (const b of Array.isArray(doc.buffers) ? doc.buffers : [])
+        add(b, true);
+    for (const i of Array.isArray(doc.images) ? doc.images : [])
+        add(i, false);
+    if (out.size > MAX_SIBLINGS)
+        throw new ModelFileError(`The glTF names more than ${MAX_SIBLINGS} files`);
+    return [...out.values()];
+}
+const MAGIC = {
+    '.png': [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+    '.jpg': [0xff, 0xd8, 0xff],
+    '.jpeg': [0xff, 0xd8, 0xff],
+    '.ktx2': [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a],
+};
+const GLB = [0x67, 0x6c, 0x54, 0x46]; // "glTF"
+const starts = (d, sig, at = 0) => d.length >= at + sig.length && sig.every((b, i) => d[at + i] === b);
+/** An image's first bytes must match its type (a .env renamed .png is refused). */
+export function checkImage(name, d) {
+    const ext = extname(name).toLowerCase();
+    const sig = MAGIC[ext];
+    const ok = ext === '.webp' ? starts(d, [0x52, 0x49, 0x46, 0x46]) && starts(d, [0x57, 0x45, 0x42, 0x50], 8) : !!sig && starts(d, sig);
+    if (!ok)
+        throw new ModelFileError(`${name} is not a ${ext.slice(1).toUpperCase()} image`);
+}
+function checkSibling(s, d) {
+    if (s.byteLength === undefined)
+        return checkImage(s.path, d);
+    if (d.length !== s.byteLength)
+        throw new ModelFileError(`${s.path} is ${d.length} bytes, the glTF says ${s.byteLength}`);
+}
+function parseGltf(d, name) {
+    try {
+        return JSON.parse(new TextDecoder().decode(d));
+    }
+    catch {
+        throw new ModelFileError(`${name} is not valid JSON`);
+    }
+}
+/**
+ * A zip's entries, read and checked without trusting it: only .glb/.gltf and
+ * the sibling types, no hidden segments, at most MAX_DEPTH folders down,
+ * stored or deflated, no encryption or zip64, within max. A .gltf inside is
+ * checked like one on disk (its siblings must be in the zip); images by type.
+ */
+export function checkZip(zip, max = MAX_MODEL_BYTES) {
+    const dv = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+    let eocd = -1;
+    for (let i = zip.length - 22; i >= Math.max(0, zip.length - 22 - 65535); i--)
+        if (dv.getUint32(i, true) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    if (eocd < 0)
+        throw new ModelFileError('The .zip is not a zip file');
+    const count = dv.getUint16(eocd + 10, true);
+    let at = dv.getUint32(eocd + 16, true);
+    if (count === 0xffff || at === 0xffffffff)
+        throw new ModelFileError('Zip64 files are not supported');
+    if (count > MAX_SIBLINGS + 10)
+        throw new ModelFileError(`The .zip holds more than ${MAX_SIBLINGS + 10} files`);
+    const entries = new Map();
+    let total = 0;
+    let models = 0;
+    const dec = new TextDecoder();
+    for (let n = 0; n < count; n++) {
+        if (at + 46 > zip.length || dv.getUint32(at, true) !== 0x02014b50)
+            throw new ModelFileError('The .zip is damaged');
+        const flags = dv.getUint16(at + 8, true);
+        const method = dv.getUint16(at + 10, true);
+        const csize = dv.getUint32(at + 20, true);
+        const usize = dv.getUint32(at + 24, true);
+        const nlen = dv.getUint16(at + 28, true);
+        const xlen = dv.getUint16(at + 30, true);
+        const clen = dv.getUint16(at + 32, true);
+        const local = dv.getUint32(at + 42, true);
+        const name = dec.decode(zip.subarray(at + 46, at + 46 + nlen));
+        at += 46 + nlen + xlen + clen;
+        if (name.endsWith('/')) {
+            checkRelative(`${name}x.bin`, ['.bin'], 'The .zip'); // folders: same path rules
+            continue;
+        }
+        const path = checkRelative(name, ['.glb', '.gltf', ...SIBLING_EXTENSIONS], 'The .zip');
+        if (flags & 1)
+            throw new ModelFileError('Encrypted zips are not supported');
+        if (method !== 0 && method !== 8)
+            throw new ModelFileError(`${name}: only stored or deflated zip entries`);
+        total += usize;
+        if (total > max)
+            throw new ModelFileError(`The model and its files are over ${mb(max)}`);
+        if (local + 30 > zip.length || dv.getUint32(local, true) !== 0x04034b50)
+            throw new ModelFileError('The .zip is damaged');
+        const start = local + 30 + dv.getUint16(local + 26, true) + dv.getUint16(local + 28, true);
+        const raw = zip.subarray(start, start + csize);
+        let data;
+        try {
+            data = method === 0 ? raw : new Uint8Array(inflateRawSync(raw, { maxOutputLength: Math.max(1, usize) }));
+        }
+        catch {
+            throw new ModelFileError(`${name} in the .zip is damaged`);
+        }
+        if (data.length !== usize)
+            throw new ModelFileError(`${name} in the .zip is damaged`);
+        const ext = extname(path).toLowerCase();
+        if (ext === '.glb' || ext === '.gltf')
+            models++;
+        if (ext === '.glb' && !starts(data, GLB))
+            throw new ModelFileError(`${name} is not a GLB`);
+        if (IMAGE_EXTENSIONS.includes(ext))
+            checkImage(path, data);
+        entries.set(path, data);
+    }
+    if (models === 0)
+        throw new ModelFileError('The .zip holds no .glb or .gltf');
+    for (const [path, data] of entries) {
+        if (extname(path).toLowerCase() !== '.gltf')
+            continue;
+        const dir = path.includes('/') ? path.slice(0, path.lastIndexOf('/') + 1) : '';
+        for (const s of gltfSiblings(parseGltf(data, path))) {
+            const d = entries.get(dir + s.path);
+            if (!d)
+                throw new ModelFileError(`${path} names ${s.path}, which is not in the .zip`);
+            checkSibling(s, d);
+        }
+    }
+}
+/** Reads a model for import, checked as above. Throws ModelFileError with a message for the agent. */
+export async function readModelFiles(path, max = MAX_MODEL_BYTES) {
+    if (typeof path !== 'string' || !isAbsolute(path))
+        throw new ModelFileError('Give the model as an absolute path');
+    const ext = extname(path).toLowerCase();
+    if (!MODEL_EXTENSIONS.includes(ext))
+        throw new ModelFileError(`Only ${MODEL_EXTENSIONS.join(', ')} files (export a GLB from Blender)`);
+    if (basename(path).startsWith('.'))
+        throw new ModelFileError('Hidden files are not models');
+    let root;
+    try {
+        root = await realpath(dirname(path));
+    }
+    catch {
+        throw new ModelFileError(`No folder at ${dirname(path)}`);
+    }
+    const main = join(root, basename(path));
+    let total = await plainFileInside(main, root);
+    if (total > max)
+        throw new ModelFileError(`The file is over ${mb(max)}`);
+    const mainData = new Uint8Array(await readFile(main));
+    if (mainData.length > max)
+        throw new ModelFileError(`The file is over ${mb(max)}`);
+    const files = [{ name: basename(main), data: mainData }];
+    if (ext === '.glb') {
+        if (!starts(mainData, GLB))
+            throw new ModelFileError(`${basename(main)} is not a GLB`);
+        return files;
+    }
+    if (ext === '.zip') {
+        checkZip(mainData, max);
+        return files;
+    }
+    for (const s of gltfSiblings(parseGltf(mainData, basename(main)))) {
+        const p = join(root, ...s.path.split('/'));
+        total += await plainFileInside(p, root);
+        if (total > max)
+            throw new ModelFileError(`The model and its files are over ${mb(max)}`);
+        const data = new Uint8Array(await readFile(p));
+        checkSibling(s, data);
+        files.push({ name: s.path, data });
+    }
+    return files;
+}

package/dist/protocol.d.ts

@@ -105,6 +105,15 @@ export type RelayMessage = {
 } | {
     type: 'pong';
 };
+/**
+ * import_model_file runs in the relay: it reads the file and sends it as
+ * import_model_part calls { upload, file, size, offset, data (base64) }, then
+ * calls the tab's import_model_file { upload, files: [{ name, size }], name?,
+ * category?, tags? }. The relay lists it only when the tab lists both, and
+ * never lists import_model_part.
+ */
+export declare const IMPORT_FILE = "import_model_file";
+export declare const IMPORT_PART = "import_model_part";
 /** Largest frame the relay accepts from the tab (screenshots are big). */
 export declare const MAX_FRAME: number;
 /** A frame from the tab, checked; null when it is not one. */

package/dist/protocol.js

@@ -37,6 +37,15 @@ export const tokenKey = (t) => t.trim().toUpperCase().replace(/[^A-Z0-9]/g, '');
 export const proofText = (who, port, tabNonce, relayNonce) => `${who}|${port}|${tabNonce}|${relayNonce}`;
 export const macText = (dir, seq, body) => `${dir}|${seq}|${body}`;
 const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * import_model_file runs in the relay: it reads the file and sends it as
+ * import_model_part calls { upload, file, size, offset, data (base64) }, then
+ * calls the tab's import_model_file { upload, files: [{ name, size }], name?,
+ * category?, tags? }. The relay lists it only when the tab lists both, and
+ * never lists import_model_part.
+ */
+export const IMPORT_FILE = 'import_model_file';
+export const IMPORT_PART = 'import_model_part';
 /** Largest frame the relay accepts from the tab (screenshots are big). */
 export const MAX_FRAME = 32 * 1024 * 1024;
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);

package/dist/relay.d.ts

@@ -70,6 +70,17 @@ export declare class Relay {
         content: Content[];
         isError: boolean;
     }>;
+    /** Whether the tab takes model files (it lists both import tools). */
+    get canImport(): boolean;
+    /**
+     * import_model_file: reads the model here (modelFile.ts checks), sends it to
+     * the tab in CHUNK_BYTES parts (one import_model_part call each, in order,
+     * each answered before the next), then asks the tab to import it.
+     */
+    importModelFile(args: Record<string, unknown>): Promise<{
+        content: Content[];
+        isError: boolean;
+    }>;
     private allowed;
     private announce;
     private accept;

package/dist/relay.js

@@ -15,7 +15,8 @@
  */
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { MAX_FRAME, macText, PROTOCOL, parseTabMessage, proofText, tokenKey } from './protocol.js';
+import { CHUNK_BYTES, ModelFileError, readModelFiles } from './modelFile.js';
+import { IMPORT_FILE, IMPORT_PART, MAX_FRAME, macText, PROTOCOL, parseTabMessage, proofText, tokenKey } from './protocol.js';
 export const hmac = (key, text) => createHmac('sha256', key).update(text).digest('hex');
 export const DEFAULT_PORT = 3021;
 export const DEFAULT_ORIGINS = ['https://studio.stroq.club', 'http://localhost:3020'];
@@ -144,7 +145,7 @@ export class Relay {
     call(name, args) {
         const tab = this.tab;
         if (!tab)
-            return Promise.resolve(err(`No Studio tab is connected. In the Studio: Help → Connect an agent and paste ${this.pairing}.`));
+            return Promise.resolve(err(`No Studio tab is connected. In the Studio: Tools → AI agent → Connect… and paste ${this.pairing}.`));
         if (!this.toolList.some((t) => t.name === name))
             return Promise.resolve(err(`The Studio has no tool "${name}"`));
         const id = this.nextId++;
@@ -157,6 +158,41 @@ export class Relay {
             this.send(tab.ws, { type: 'call', id, name, arguments: args });
         });
     }
+    /** Whether the tab takes model files (it lists both import tools). */
+    get canImport() {
+        return !!this.tab && this.toolList.some((t) => t.name === IMPORT_FILE) && this.toolList.some((t) => t.name === IMPORT_PART);
+    }
+    /**
+     * import_model_file: reads the model here (modelFile.ts checks), sends it to
+     * the tab in CHUNK_BYTES parts (one import_model_part call each, in order,
+     * each answered before the next), then asks the tab to import it.
+     */
+    async importModelFile(args) {
+        if (!this.tab)
+            return this.call(IMPORT_FILE, {});
+        if (!this.canImport)
+            return err('This Studio tab cannot import model files: reload it, or update the Studio');
+        let files;
+        try {
+            files = await readModelFiles(args.path);
+        }
+        catch (e) {
+            return err(e instanceof ModelFileError ? e.message : `Could not read the model: ${e.message}`);
+        }
+        const upload = randomBytes(12).toString('hex');
+        for (const f of files) {
+            for (let offset = 0; offset < f.data.length || offset === 0; offset += CHUNK_BYTES) {
+                const data = Buffer.from(f.data.subarray(offset, offset + CHUNK_BYTES)).toString('base64');
+                const r = await this.call(IMPORT_PART, { upload, file: f.name, size: f.data.length, offset, data });
+                if (r.isError)
+                    return r;
+                if (f.data.length === 0)
+                    break;
+            }
+        }
+        const pick = (k) => (args[k] === undefined ? {} : { [k]: args[k] });
+        return this.call(IMPORT_FILE, { upload, files: files.map((f) => ({ name: f.name, size: f.data.length })), ...pick('name'), ...pick('category'), ...pick('tags') });
+    }
     allowed(origin, req) {
         // Only from this machine (the bind already ensures it) and only from the Studio's origins.
         const host = req.socket.remoteAddress ?? '';
@@ -169,7 +205,7 @@ export class Relay {
         return true;
     }
     announce() {
-        this.log(`Strōq Studio relay on ws://127.0.0.1:${this.port}. In the Studio: Help → Connect an agent and paste ${this.pairing}`);
+        this.log(`Strōq Studio relay on ws://127.0.0.1:${this.port}. In the Studio: Tools → AI agent → Connect… and paste ${this.pairing}`);
     }
     accept(ws, origin) {
         let paired = false;

package/package.json

@@ -1,19 +1,45 @@
 {
   "name": "@atropical/stroq-studio-mcp",
-  "version": "0.1.0",
-  "description": "Connects an MCP client (Claude Code, Claude Desktop) to an open Strōq World Studio tab, over a local WebSocket.",
+  "version": "0.1.1",
+  "description": "Connects any MCP client (Claude Code, Codex, Cursor, Claude Desktop…) to an open Strōq World Studio tab, over a local WebSocket.",
   "license": "GPL-3.0-only",
   "author": "Atropical",
   "homepage": "https://github.com/atropical/stroq-studio-mcp#readme",
-  "repository": { "type": "git", "url": "git+https://github.com/atropical/stroq-studio-mcp.git" },
-  "bugs": { "url": "https://github.com/atropical/stroq-studio-mcp/issues" },
-  "keywords": ["mcp", "model-context-protocol", "stroq", "world-studio", "claude"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atropical/stroq-studio-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/atropical/stroq-studio-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "stroq",
+    "world-studio",
+    "claude",
+    "codex",
+    "cursor"
+  ],
   "type": "module",
-  "bin": { "stroq-studio-mcp": "dist/cli.js" },
-  "exports": { ".": "./dist/relay.js" },
-  "files": ["dist/*.js", "dist/*.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
-  "publishConfig": { "access": "public" },
+  "bin": {
+    "stroq-studio-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/relay.js"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "type-check": "tsc --noEmit",