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

package/dist/relay.js

@@ -0,0 +1,325 @@
+// 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 WebSocket side: one Studio tab at a time, on 127.0.0.1 only, from an
+ * allowed Origin only, after a mutual HMAC proof of the pairing token (or of
+ * the resume key both derived when they paired) bound to this port; then
+ * every frame is MACed with the session key and a sequence number (see
+ * protocol.ts). The token never crosses the wire and has ~130 bits, so a
+ * relay proof is no use for guessing it offline. Five wrong proofs replace it
+ * (at most once a minute). Token hellos after more than 30 failed or
+ * unfinished handshakes in a minute are answered late (growing, up to 5 s);
+ * successful pairings and resume hellos never count or wait, so nothing on
+ * the machine can block pairing.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { 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'];
+/** A handshake must finish within this time. */
+export const HANDSHAKE_MS = 30_000;
+/** Longest a tool call may take (wait_for_comments waits up to 10 min). */
+export const CALL_TIMEOUT_MS = 11 * 60_000;
+/** Wrong proofs before the token is replaced; replaced at most once per ROTATE_MS. */
+export const MAX_WRONG = 5;
+export const ROTATE_MS = 60_000;
+/** Failed or unfinished handshakes a minute before token hellos are slowed down. */
+export const FREE_STRIKES_PER_MIN = 30;
+/** Delay per strike past the free ones, and its cap. */
+export const STRIKE_DELAY_MS = 250;
+export const MAX_DELAY_MS = 5_000;
+/** The one string the person pastes into the Studio: port and token. */
+export const pairingString = (port, token) => `${port}:${token}`;
+const BASE32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/** A 26-character base32 token (130 random bits), grouped for pasting: XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX. */
+export function newToken() {
+    const bytes = randomBytes(17);
+    let bits = 0;
+    let acc = 0;
+    let s = '';
+    for (const b of bytes) {
+        acc = (acc << 8) | b;
+        bits += 8;
+        while (bits >= 5 && s.length < 26) {
+            s += BASE32[(acc >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+        acc &= (1 << bits) - 1;
+    }
+    return s.match(/.{1,5}/g).join('-').replace(/-(\w)$/, '$1');
+}
+function sameSecret(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export class Relay {
+    fixedPort;
+    /** The port it listens on (known once started). */
+    port;
+    origins;
+    wss = null;
+    token = newToken();
+    resume = null;
+    tab = null;
+    wrong = 0;
+    lastRotate = 0;
+    /** When failed or unfinished token handshakes ended (last minute). */
+    strikes = [];
+    toolList = [];
+    nextId = 1;
+    pending = new Map();
+    log;
+    onToolsChanged;
+    constructor(opts = {}) {
+        this.fixedPort = opts.port ?? null;
+        this.port = opts.port ?? DEFAULT_PORT;
+        this.origins = opts.origins ?? DEFAULT_ORIGINS;
+        this.log = opts.log ?? (() => undefined);
+        this.onToolsChanged = opts.onToolsChanged ?? (() => undefined);
+    }
+    get pairingToken() {
+        return this.token;
+    }
+    /** What the person pastes: "port:TOKEN". */
+    get pairing() {
+        return pairingString(this.port, this.token);
+    }
+    get tools() {
+        return this.tab ? this.toolList : [];
+    }
+    status() {
+        return this.tab ? { state: 'connected', origin: this.tab.origin, tools: this.toolList.length, port: this.port } : { state: 'waiting', pairing: this.pairing, token: this.token, port: this.port };
+    }
+    /** Starts listening on 127.0.0.1: the fixed port, else DEFAULT_PORT, else any free port (said on the log). */
+    async start() {
+        if (this.fixedPort !== null)
+            return this.listen(this.fixedPort);
+        try {
+            await this.listen(DEFAULT_PORT);
+        }
+        catch (e) {
+            if (e.code !== 'EADDRINUSE')
+                throw e;
+            await this.listen(0);
+            this.log(`Port ${DEFAULT_PORT} is taken, so the relay uses port ${this.port}.`);
+            this.announce();
+        }
+    }
+    listen(port) {
+        return new Promise((resolve, reject) => {
+            const wss = new WebSocketServer({ host: '127.0.0.1', port, maxPayload: MAX_FRAME, verifyClient: (info) => this.allowed(info.origin, info.req) });
+            wss.once('error', (e) => {
+                wss.close();
+                reject(e);
+            });
+            wss.once('listening', () => {
+                wss.removeAllListeners('error');
+                wss.on('error', (e) => this.log(`WebSocket error: ${e.message}`));
+                this.wss = wss;
+                this.port = wss.address().port;
+                if (port !== 0)
+                    this.announce();
+                resolve();
+            });
+            wss.on('connection', (ws, req) => this.accept(ws, req.headers.origin ?? ''));
+        });
+    }
+    async stop() {
+        this.failAll('The relay stopped');
+        this.tab?.ws.close(1001, 'relay stopping');
+        this.tab = null;
+        const wss = this.wss;
+        this.wss = null;
+        if (wss) {
+            for (const c of wss.clients)
+                c.terminate();
+            await new Promise((r) => wss.close(() => r()));
+        }
+    }
+    /** Runs a tool in the tab. Never throws: errors come back as isError content. */
+    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}.`));
+        if (!this.toolList.some((t) => t.name === name))
+            return Promise.resolve(err(`The Studio has no tool "${name}"`));
+        const id = this.nextId++;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                resolve(err(`"${name}" took longer than ${CALL_TIMEOUT_MS / 60_000} minutes`));
+            }, CALL_TIMEOUT_MS);
+            this.pending.set(id, { resolve, timer });
+            this.send(tab.ws, { type: 'call', id, name, arguments: args });
+        });
+    }
+    allowed(origin, req) {
+        // Only from this machine (the bind already ensures it) and only from the Studio's origins.
+        const host = req.socket.remoteAddress ?? '';
+        if (host !== '127.0.0.1' && host !== '::ffff:127.0.0.1')
+            return false;
+        if (!this.origins.includes(origin)) {
+            this.log(`Refused a connection from origin "${origin || '(none)'}" (allowed: ${this.origins.join(', ')})`);
+            return false;
+        }
+        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}`);
+    }
+    accept(ws, origin) {
+        let paired = false;
+        /** After hello: the nonces and the key this attempt uses. */
+        let attempt = null;
+        let session = '';
+        let seqIn = 0;
+        const timer = setTimeout(() => {
+            if (!paired)
+                ws.close(4000, 'not paired in time');
+        }, HANDSHAKE_MS);
+        const refuse = (why) => {
+            this.sendPlain(ws, { type: 'refused', reason: why });
+            ws.close(4003, 'refused');
+        };
+        ws.on('message', (data, isBinary) => {
+            if (isBinary)
+                return ws.close(4002, 'text frames only');
+            const msg = parseTabMessage(data.toString());
+            if (!msg)
+                return ws.close(4001, 'bad frame');
+            if (!paired) {
+                if (!attempt) {
+                    if (msg.type !== 'hello')
+                        return ws.close(4001, 'hello first');
+                    if (msg.protocol !== PROTOCOL)
+                        return refuse(`This relay speaks protocol ${PROTOCOL}, the Studio ${msg.protocol}: update @atropical/stroq-studio-mcp, or reload the Studio`);
+                    if (this.tab)
+                        return refuse('Another Studio tab is connected. Disconnect it first.');
+                    if (msg.port !== this.port)
+                        return refuse(`This relay listens on port ${this.port}, not ${msg.port}.`);
+                    const key = msg.mode === 'resume' ? this.resume : tokenKey(this.token);
+                    if (!key)
+                        return refuse('Nothing to resume: connect with the pairing token.');
+                    const relayNonce = randomBytes(32).toString('hex');
+                    const a = { tabNonce: msg.nonce, relayNonce, key, mode: msg.mode };
+                    attempt = a;
+                    const challenge = () => this.sendPlain(ws, { type: 'challenge', nonce: relayNonce, proof: hmac(key, proofText('relay', this.port, a.tabNonce, relayNonce)) });
+                    // Resume hellos (a 256-bit key) never wait; token hellos wait while failed handshakes pile up.
+                    const wait = msg.mode === 'token' ? this.delay() : 0;
+                    if (!wait)
+                        return challenge();
+                    this.sendPlain(ws, { type: 'wait', ms: wait });
+                    setTimeout(challenge, wait);
+                    return;
+                }
+                if (msg.type !== 'prove')
+                    return ws.close(4001, 'prove next');
+                const p = attempt;
+                if (!sameSecret(msg.proof, hmac(p.key, proofText('tab', this.port, p.tabNonce, p.relayNonce))))
+                    return refuse(p.mode === 'resume' ? 'The resume key no longer matches: connect with the pairing token.' : this.wrongProof());
+                if (this.tab)
+                    return refuse('Another Studio tab is connected. Disconnect it first.');
+                clearTimeout(timer);
+                paired = true;
+                this.wrong = 0;
+                if (p.mode === 'token')
+                    this.token = newToken(); // one-time: used up once it pairs
+                // Bound to this proof: only the tab that proved it can derive them.
+                this.resume = hmac(p.key, proofText('resume', this.port, p.tabNonce, p.relayNonce));
+                session = hmac(p.key, proofText('session', this.port, p.tabNonce, p.relayNonce));
+                this.tab = { ws, origin, session, seqOut: 0 };
+                this.send(ws, { type: 'welcome', protocol: PROTOCOL });
+                this.log(`Studio tab connected (${origin})`);
+                return;
+            }
+            // Paired: only sealed frames, in order, with a good MAC.
+            if (msg.type !== 'sealed' || msg.seq !== seqIn || !sameSecret(msg.mac, hmac(session, macText('tab', msg.seq, msg.body))))
+                return ws.close(4004, 'bad or replayed frame');
+            seqIn++;
+            const inner = parseTabMessage(msg.body);
+            if (!inner)
+                return ws.close(4001, 'bad frame');
+            switch (inner.type) {
+                case 'tools':
+                    this.toolList = inner.tools;
+                    this.onToolsChanged();
+                    break;
+                case 'result': {
+                    const r = this.pending.get(inner.id);
+                    if (!r)
+                        break;
+                    clearTimeout(r.timer);
+                    this.pending.delete(inner.id);
+                    r.resolve({ content: inner.content, isError: !!inner.isError });
+                    break;
+                }
+                case 'ping':
+                    this.send(ws, { type: 'pong' });
+                    break;
+                case 'pong':
+                    break;
+                default:
+                    return ws.close(4001, 'bad frame');
+            }
+        });
+        ws.on('close', () => {
+            clearTimeout(timer);
+            // A token handshake that failed or was never finished counts; a successful one never does.
+            if (!paired && attempt?.mode === 'token')
+                this.strikes.push(Date.now());
+            if (!paired || this.tab?.ws !== ws)
+                return;
+            this.tab = null;
+            this.toolList = [];
+            this.failAll('The Studio tab disconnected');
+            this.onToolsChanged();
+            this.token = newToken();
+            this.log('Studio tab disconnected (reloading the same tab reconnects by itself).');
+            this.announce();
+        });
+    }
+    /** How long a token hello waits: 0 up to FREE_STRIKES_PER_MIN strikes in the last minute, then growing to MAX_DELAY_MS. */
+    delay(now = Date.now()) {
+        this.strikes = this.strikes.filter((t) => now - t < 60_000);
+        const over = this.strikes.length - FREE_STRIKES_PER_MIN;
+        return over <= 0 ? 0 : Math.min(MAX_DELAY_MS, over * STRIKE_DELAY_MS);
+    }
+    /** A wrong token proof: counted; MAX_WRONG of them replace the token, at most once per ROTATE_MS. */
+    wrongProof(now = Date.now()) {
+        this.wrong++;
+        if (this.wrong >= MAX_WRONG && now - this.lastRotate >= ROTATE_MS) {
+            this.wrong = 0;
+            this.lastRotate = now;
+            this.token = newToken();
+            this.log(`${MAX_WRONG} wrong tokens: the pairing token changed.`);
+            this.announce();
+        }
+        return 'Wrong pairing token. Copy the one the relay printed.';
+    }
+    failAll(why) {
+        for (const [id, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.resolve(err(why));
+            this.pending.delete(id);
+        }
+    }
+    /** Before pairing: challenge and refused only. */
+    sendPlain(ws, m) {
+        if (ws.readyState === ws.OPEN)
+            ws.send(JSON.stringify(m));
+    }
+    /** To the paired tab: sealed with the session key and the next sequence number. */
+    send(ws, m) {
+        const tab = this.tab;
+        if (!tab || tab.ws !== ws || ws.readyState !== ws.OPEN)
+            return;
+        const body = JSON.stringify(m);
+        const seq = tab.seqOut++;
+        ws.send(JSON.stringify({ type: 'sealed', seq, body, mac: hmac(tab.session, macText('relay', seq, body)) }));
+    }
+}
+const err = (text) => ({ content: [{ type: 'text', text }], isError: true });

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@atropical/stroq-studio-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "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"],
+  "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" },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run build && npm run type-check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "ws": "^8.22.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.2"
+  }
+}