@atropical/stroq-studio-mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# stroq-studio-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+It is a thin relay. The MCP client starts it over stdio; it opens a WebSocket
+on `127.0.0.1` that the Studio tab connects to. The tools come from the tab
+itself, so they always match the Studio you have open.
+
+```
+MCP client  ⇄ stdio ⇄  stroq-studio-mcp  ⇄ ws://127.0.0.1:3021 ⇄  Studio tab
+```
+
+## Set up
+
+### Claude Code
+
+```sh
+claude mcp add stroq-studio -- npx -y @atropical/stroq-studio-mcp
+```
+
+### Codex CLI
+
+```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
+{
+  "mcpServers": {
+    "stroq-studio": {
+      "command": "npx",
+      "args": ["-y", "@atropical/stroq-studio-mcp"]
+    }
+  }
+}
+```
+
+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 (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: **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
+   at the top".
+
+A code is used up once a tab pairs with it. Reloading the same tab reconnects
+by itself; another tab, or a new relay, needs a new code (the relay prints one
+each time a tab disconnects).
+
+Your browser may ask whether the Studio may reach devices on this computer or
+local network: allow it, or the tab cannot reach the relay.
+
+## Options
+
+```
+stroq-studio-mcp [--port <n>] [--origin <url>]...
+
+  --port <n>      Fixed WebSocket port on 127.0.0.1 (fails if busy). Default:
+                  3021, or any free port when that one is taken (said on stderr;
+                  the pairing code always carries the port)
+  --origin <url>  A Studio origin allowed to connect; repeat for more. Replaces
+                  the defaults (https://studio.stroq.club, http://localhost:3020)
+```
+
+No port setting is needed: the pairing code carries it. To fix one, add it to
+the MCP config, e.g.
+`claude mcp add stroq-studio -- npx -y @atropical/stroq-studio-mcp --port 3031`.
+
+## Tools
+
+Until a tab is connected the relay lists one tool, `studio_connection`
+(connection state and the pairing code). Once a tab connects, the tab's
+tools appear (the relay sends `notifications/tools/list_changed`), for example
+`list_routes`, `put_route`, `validate_route`, `scatter`, `apply_landscape`,
+`screenshot` (as an image), and the comment tools `list_comments`,
+`get_comment` (with its screenshot), `ack_comment`, `reply_comment`,
+`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.
+- Accepts a WebSocket only from an allowed `Origin` (the Studio's addresses
+  above, or the ones you pass with `--origin`), so other web pages cannot use
+  it.
+- The pairing token is 26 base32 characters (about 130 bits), far too many to
+  guess offline from the relay's proof. Five wrong proofs replace it with a
+  new one (printed on stderr), at most once a minute.
+- Nothing on the machine can block pairing: once more than 30 handshakes in a
+  minute have failed or been left unfinished, token hellos are answered late
+  (growing, at most 5 seconds, with a `wait` frame first). Successful
+  pairings never count, and resume hellos (a 256-bit key) never wait.
+- Pairing is mutual and bound to the port: the tab and the relay each prove
+  they know the token with an HMAC-SHA256 over two fresh nonces and the port
+  the tab dialled, which the relay checks against the port it listens on. The
+  token never crosses the wire, the tab trusts no other process on the port,
+  and a relay in the middle on another port cannot pass the proofs on.
+- After pairing every frame, both ways, carries an HMAC with the session key
+  derived from the proof and a sequence number per direction; a changed,
+  replayed or out-of-order frame closes the connection.
+- 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 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
+
+JSON text frames over one WebSocket (see `src/protocol.ts`). The key is the
+token (upper case, letters and digits) or the resume key from the last
+pairing; `port` is the port the tab dialled; nonces are 32 random bytes in hex;
+proofs and MACs are hex HMAC-SHA256.
+
+| Direction | Frame |
+| --- | --- |
+| tab → relay | `{ "type": "hello", "protocol": 3, "mode": "token" or "resume", "port": 3021, "nonce": tn }` |
+| relay → tab | `{ "type": "challenge", "nonce": rn, "proof": HMAC(key, "relay\|port\|tn\|rn") }` or `{ "type": "refused", "reason": "…" }`, maybe after `{ "type": "wait", "ms": n }` |
+| tab → relay | `{ "type": "prove", "proof": HMAC(key, "tab\|port\|tn\|rn") }` (only after checking the relay's proof) |
+
+Both then hold `session = HMAC(key, "session|port|tn|rn")` and
+`resume = HMAC(key, "resume|port|tn|rn")`. Every later frame is
+`{ "type": "sealed", "seq": n, "body": "<frame JSON>", "mac": HMAC(session, dir + "|" + n + "|" + body) }`,
+`dir` being `relay` or `tab` and `seq` counting from 0 in each direction.
+Sealed bodies:
+
+| Direction | Body |
+| --- | --- |
+| relay → tab | `{ "type": "welcome", "protocol": 3 }` (the first) |
+| tab → relay | `{ "type": "tools", "tools": [{ "name", "description", "inputSchema" }] }` |
+| relay → tab | `{ "type": "call", "id": 1, "name": "list_routes", "arguments": {} }` |
+| tab → relay | `{ "type": "result", "id": 1, "content": [MCP text/image blocks], "isError": false }` |
+| either | `{ "type": "ping" }` / `{ "type": "pong" }` |
+
+## Develop
+
+```sh
+bun install
+bun test
+npm run build      # dist/
+npm run type-check
+```
+
+## Licence
+
+Copyright (C) 2026 Atropical.
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, version 3 only. It is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See [LICENSE](LICENSE).

package/dist/args.d.ts

@@ -0,0 +1,6 @@
+export declare const HELP: string;
+export declare function parseArgs(argv: string[]): {
+    port?: number;
+    origins: string[];
+    help: boolean;
+};

package/dist/args.js

@@ -0,0 +1,56 @@
+// 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 { DEFAULT_ORIGINS, DEFAULT_PORT } from './relay.js';
+export const HELP = `Usage: stroq-studio-mcp [--port <n>] [--origin <url>]...
+
+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
+  --origin <url>  A Studio origin allowed to connect; repeat for more. Replaces
+                  the defaults (${DEFAULT_ORIGINS.join(', ')})
+  --help          This text
+
+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 = [];
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+        const flag = eq > 0 ? a.slice(0, eq) : a;
+        const inline = eq > 0 ? a.slice(eq + 1) : undefined;
+        const value = () => {
+            const v = inline ?? argv[++i];
+            if (v === undefined)
+                throw new Error(`${flag} needs a value`);
+            return v;
+        };
+        if (flag === '--help' || flag === '-h')
+            help = true;
+        else if (flag === '--port') {
+            const n = Number(value());
+            port = n;
+            if (!Number.isInteger(n) || n < 1024 || n > 65535)
+                throw new Error('--port must be a whole number from 1024 to 65535');
+        }
+        else if (flag === '--origin') {
+            const o = value();
+            let u;
+            try {
+                u = new URL(o);
+            }
+            catch {
+                throw new Error(`--origin "${o}" is not a URL`);
+            }
+            if (u.protocol !== 'https:' && u.protocol !== 'http:')
+                throw new Error(`--origin "${o}" must be http or https`);
+            origins.push(u.origin);
+        }
+        else
+            throw new Error(`Unknown option "${a}" (try --help)`);
+    }
+    return { port, origins: origins.length ? origins : [...DEFAULT_ORIGINS], help };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// 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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { HELP, parseArgs } from './args.js';
+import { createMcpServer, VERSION } from './mcp.js';
+import { Relay } from './relay.js';
+const log = (line) => process.stderr.write(`[stroq-studio] ${line}\n`);
+let opts;
+try {
+    opts = parseArgs(process.argv.slice(2));
+}
+catch (e) {
+    log(e.message);
+    process.exit(2);
+}
+if (opts.help) {
+    process.stderr.write(`stroq-studio-mcp ${VERSION}\n${HELP}\n`);
+    process.exit(0);
+}
+let live = false;
+const relay = new Relay({
+    port: opts.port,
+    origins: opts.origins,
+    log,
+    onToolsChanged: () => {
+        if (live)
+            server.sendToolListChanged().catch(() => undefined);
+    },
+});
+const server = createMcpServer(relay);
+server.oninitialized = () => {
+    live = true;
+};
+try {
+    await relay.start();
+}
+catch (e) {
+    log(`Could not listen on 127.0.0.1:${opts.port ?? relay.port}: ${e.message}.${opts.port ? ' Is another relay running on it? Pick another --port, or leave --port out to use any free port.' : ''}`);
+    process.exit(1);
+}
+await server.connect(new StdioServerTransport());
+const stop = () => {
+    relay.stop().finally(() => process.exit(0));
+};
+process.stdin.on('close', stop);
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);

package/dist/mcp.d.ts

@@ -0,0 +1,45 @@
+/** The MCP side: the tools learnt from the tab, plus studio_connection (always there). */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Relay } from './relay.js';
+export declare const VERSION = "0.1.0";
+export declare const CONNECTION_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+/** 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

@@ -0,0 +1,46 @@
+// 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
+/** 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, Tools → AI agent → Connect…, paste it, switch Connect on. The Studio tools appear once the tab connects.',
+    inputSchema: { type: 'object', properties: {} },
+};
+/** 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) => !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[]>;