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

package/README.md

@@ -1,3 +1,158 @@
-# 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 an AI agent (Claude Code, Claude Desktop or any MCP client) 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
+```
+
+### Claude Desktop
+
+Add it to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "stroq-studio": {
+      "command": "npx",
+      "args": ["-y", "@atropical/stroq-studio-mcp"]
+    }
+  }
+}
+```
+
+Then restart Claude Desktop.
+
+### 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
+   `studio_connection` tool returns it.
+2. In the Studio: **Help → Connect an agent**. 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.
+
+## 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 reads no files: every tool runs inside the Studio tab,
+  on the content in that browser.
+
+## 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 an MCP client (Claude Code, 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 Help → Connect an agent.`;
+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,14 @@
+/** 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: {};
+    };
+};
+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.";
+export declare function createMcpServer(relay: Relay): Server;

package/dist/mcp.js

@@ -0,0 +1,24 @@
+// 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';
+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.',
+    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.';
+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(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) }] };
+        return relay.call(name, (args ?? {}));
+    });
+    return server;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The wire protocol between the relay and the Studio tab: JSON text frames
+ * over one WebSocket.
+ *
+ * Pairing is mutual and the secret never crosses the wire. The key is the
+ * pairing token (26 base32 characters, ~130 bits; dashes and case ignored)
+ * or, to reconnect after a reload, the resume key both sides derived when
+ * they last paired. Every proof names the port the tab dialled, so a relay in
+ * the middle on another port cannot pass them on.
+ *
+ *   tab → relay   hello     { type, protocol, mode, port, nonce }   mode 'token' | 'resume'; nonce: 32 random bytes, hex
+ *   relay → tab   challenge { type, nonce, proof }    proof = HMAC-SHA256(key, "relay|" + port + "|" + tabNonce + "|" + relayNonce), hex
+ *   tab → relay   prove     { type, proof }           after checking the relay's proof: HMAC(key, "tab|" + port + "|" + …)
+ *   relay → tab   wait      { type, ms }              the challenge comes late (many failed handshakes lately)
+ *   relay → tab   refused   { type, reason }          then the relay closes the socket
+ *
+ * Then both hold session = HMAC(key, "session|…") and resume = HMAC(key,
+ * "resume|…"), never sent. Every later frame, both ways, is sealed:
+ *
+ *   { type: "sealed", seq, body, mac }   body: the frame's JSON; seq counts from 0 per direction;
+ *                                        mac = HMAC(session, dir + "|" + seq + "|" + body), dir "relay" or "tab"
+ *
+ * A bad MAC or a sequence number out of order closes the socket. Sealed bodies:
+ *
+ *   relay → tab   welcome { type, protocol }          first sealed frame: paired
+ *   tab → relay   tools   { type, tools: ToolInfo[] } any time; the relay tells the MCP client the list changed
+ *   relay → tab   call    { type, id, name, arguments }
+ *   tab → relay   result  { type, id, content, isError? }  content is MCP content (text and image blocks)
+ *   either        ping / pong { type }                keep-alive
+ */
+export declare const PROTOCOL = 3;
+/** The pairing token as a key: upper case, letters and digits only. */
+export declare const tokenKey: (t: string) => string;
+export type ProofKind = 'relay' | 'tab' | 'resume' | 'session';
+export declare const proofText: (who: ProofKind, port: number, tabNonce: string, relayNonce: string) => string;
+export declare const macText: (dir: "relay" | "tab", seq: number, body: string) => string;
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        [k: string]: unknown;
+    };
+}
+export type Content = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+export type TabMessage = {
+    type: 'hello';
+    protocol: number;
+    mode: 'token' | 'resume';
+    port: number;
+    nonce: string;
+} | {
+    type: 'sealed';
+    seq: number;
+    body: string;
+    mac: string;
+} | {
+    type: 'prove';
+    proof: string;
+} | {
+    type: 'tools';
+    tools: ToolInfo[];
+} | {
+    type: 'result';
+    id: number;
+    content: Content[];
+    isError?: boolean;
+} | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+export type RelayMessage = {
+    type: 'challenge';
+    nonce: string;
+    proof: string;
+} | {
+    type: 'welcome';
+    protocol: number;
+} | {
+    type: 'sealed';
+    seq: number;
+    body: string;
+    mac: string;
+} | {
+    type: 'wait';
+    ms: number;
+} | {
+    type: 'refused';
+    reason: string;
+} | {
+    type: 'call';
+    id: number;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+/** 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. */
+export declare function parseTabMessage(raw: string): TabMessage | null;

package/dist/protocol.js

@@ -0,0 +1,99 @@
+// 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 wire protocol between the relay and the Studio tab: JSON text frames
+ * over one WebSocket.
+ *
+ * Pairing is mutual and the secret never crosses the wire. The key is the
+ * pairing token (26 base32 characters, ~130 bits; dashes and case ignored)
+ * or, to reconnect after a reload, the resume key both sides derived when
+ * they last paired. Every proof names the port the tab dialled, so a relay in
+ * the middle on another port cannot pass them on.
+ *
+ *   tab → relay   hello     { type, protocol, mode, port, nonce }   mode 'token' | 'resume'; nonce: 32 random bytes, hex
+ *   relay → tab   challenge { type, nonce, proof }    proof = HMAC-SHA256(key, "relay|" + port + "|" + tabNonce + "|" + relayNonce), hex
+ *   tab → relay   prove     { type, proof }           after checking the relay's proof: HMAC(key, "tab|" + port + "|" + …)
+ *   relay → tab   wait      { type, ms }              the challenge comes late (many failed handshakes lately)
+ *   relay → tab   refused   { type, reason }          then the relay closes the socket
+ *
+ * Then both hold session = HMAC(key, "session|…") and resume = HMAC(key,
+ * "resume|…"), never sent. Every later frame, both ways, is sealed:
+ *
+ *   { type: "sealed", seq, body, mac }   body: the frame's JSON; seq counts from 0 per direction;
+ *                                        mac = HMAC(session, dir + "|" + seq + "|" + body), dir "relay" or "tab"
+ *
+ * A bad MAC or a sequence number out of order closes the socket. Sealed bodies:
+ *
+ *   relay → tab   welcome { type, protocol }          first sealed frame: paired
+ *   tab → relay   tools   { type, tools: ToolInfo[] } any time; the relay tells the MCP client the list changed
+ *   relay → tab   call    { type, id, name, arguments }
+ *   tab → relay   result  { type, id, content, isError? }  content is MCP content (text and image blocks)
+ *   either        ping / pong { type }                keep-alive
+ */
+export const PROTOCOL = 3;
+/** The pairing token as a key: upper case, letters and digits only. */
+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}$/;
+/** 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);
+function isContent(v) {
+    if (!isObj(v))
+        return false;
+    if (v.type === 'text')
+        return typeof v.text === 'string';
+    if (v.type === 'image')
+        return typeof v.data === 'string' && typeof v.mimeType === 'string' && /^image\/(png|jpeg|webp|gif)$/.test(v.mimeType);
+    return false;
+}
+function isTool(v) {
+    return (isObj(v) &&
+        typeof v.name === 'string' &&
+        /^[A-Za-z0-9_-]{1,64}$/.test(v.name) &&
+        (v.description === undefined || typeof v.description === 'string') &&
+        isObj(v.inputSchema) &&
+        v.inputSchema.type === 'object');
+}
+/** A frame from the tab, checked; null when it is not one. */
+export function parseTabMessage(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isObj(v))
+        return null;
+    switch (v.type) {
+        case 'hello':
+            if (typeof v.protocol !== 'number')
+                return null;
+            // Another protocol version gets a clear refusal, whatever else it sent.
+            if (v.protocol !== PROTOCOL)
+                return { type: 'hello', protocol: v.protocol, mode: 'token', port: 0, nonce: '' };
+            return (v.mode === 'token' || v.mode === 'resume') && Number.isInteger(v.port) && typeof v.nonce === 'string' && HEX64.test(v.nonce)
+                ? { type: 'hello', protocol: v.protocol, mode: v.mode, port: v.port, nonce: v.nonce }
+                : null;
+        case 'sealed':
+            return Number.isInteger(v.seq) && v.seq >= 0 && typeof v.body === 'string' && typeof v.mac === 'string' && HEX64.test(v.mac)
+                ? { type: 'sealed', seq: v.seq, body: v.body, mac: v.mac }
+                : null;
+        case 'prove':
+            return typeof v.proof === 'string' && HEX64.test(v.proof) ? { type: 'prove', proof: v.proof } : null;
+        case 'tools':
+            return Array.isArray(v.tools) && v.tools.length <= 500 && v.tools.every(isTool) ? { type: 'tools', tools: v.tools } : null;
+        case 'result':
+            return Number.isInteger(v.id) && Array.isArray(v.content) && v.content.every(isContent)
+                ? { type: 'result', id: v.id, content: v.content, isError: v.isError === true }
+                : null;
+        case 'ping':
+        case 'pong':
+            return { type: v.type };
+        default:
+            return null;
+    }
+}

package/dist/relay.d.ts

@@ -0,0 +1,85 @@
+import { type Content, type ToolInfo } from './protocol.js';
+export declare const hmac: (key: string, text: string) => string;
+export declare const DEFAULT_PORT = 3021;
+export declare const DEFAULT_ORIGINS: string[];
+/** A handshake must finish within this time. */
+export declare const HANDSHAKE_MS = 30000;
+/** Longest a tool call may take (wait_for_comments waits up to 10 min). */
+export declare const CALL_TIMEOUT_MS: number;
+/** Wrong proofs before the token is replaced; replaced at most once per ROTATE_MS. */
+export declare const MAX_WRONG = 5;
+export declare const ROTATE_MS = 60000;
+/** Failed or unfinished handshakes a minute before token hellos are slowed down. */
+export declare const FREE_STRIKES_PER_MIN = 30;
+/** Delay per strike past the free ones, and its cap. */
+export declare const STRIKE_DELAY_MS = 250;
+export declare const MAX_DELAY_MS = 5000;
+/** The one string the person pastes into the Studio: port and token. */
+export declare const pairingString: (port: number, token: string) => string;
+/** A 26-character base32 token (130 random bits), grouped for pasting: XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX. */
+export declare function newToken(): string;
+export type RelayStatus = {
+    state: 'waiting';
+    pairing: string;
+    token: string;
+    port: number;
+} | {
+    state: 'connected';
+    origin: string;
+    tools: number;
+    port: number;
+};
+export interface RelayOptions {
+    /** A fixed port (fails when busy). Without it: DEFAULT_PORT, else any free port. */
+    port?: number;
+    origins?: string[];
+    /** Where messages for the person go (stderr in the CLI; stdout belongs to MCP). */
+    log?: (line: string) => void;
+    onToolsChanged?: () => void;
+}
+export declare class Relay {
+    private fixedPort;
+    /** The port it listens on (known once started). */
+    port: number;
+    readonly origins: string[];
+    private wss;
+    private token;
+    private resume;
+    private tab;
+    private wrong;
+    private lastRotate;
+    /** When failed or unfinished token handshakes ended (last minute). */
+    private strikes;
+    private toolList;
+    private nextId;
+    private pending;
+    private log;
+    private onToolsChanged;
+    constructor(opts?: RelayOptions);
+    get pairingToken(): string;
+    /** What the person pastes: "port:TOKEN". */
+    get pairing(): string;
+    get tools(): ToolInfo[];
+    status(): RelayStatus;
+    /** Starts listening on 127.0.0.1: the fixed port, else DEFAULT_PORT, else any free port (said on the log). */
+    start(): Promise<void>;
+    private listen;
+    stop(): Promise<void>;
+    /** Runs a tool in the tab. Never throws: errors come back as isError content. */
+    call(name: string, args: Record<string, unknown>): Promise<{
+        content: Content[];
+        isError: boolean;
+    }>;
+    private allowed;
+    private announce;
+    private accept;
+    /** 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?: number): number;
+    /** A wrong token proof: counted; MAX_WRONG of them replace the token, at most once per ROTATE_MS. */
+    private wrongProof;
+    private failAll;
+    /** Before pairing: challenge and refused only. */
+    private sendPlain;
+    /** To the paired tab: sealed with the session key and the next sequence number. */
+    private send;
+}