@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/roblox-mcp/mcp/mcp-stdio-client.ts

@@ -0,0 +1,270 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'child_process';
+import { repairListResult } from './repair-list-result.js';
+
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const STDERR_TAIL_BYTES = 4096;
+const CLOSE_TIMEOUT_MS = 2000;
+
+export class McpTimeoutError extends Error {}
+
+export interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface McpContent {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+export interface McpToolResult {
+  isError: boolean;
+  content: McpContent[];
+  text: string;
+}
+
+export type SpawnMcpProcess = (
+  command: string,
+  args: string[]
+) => ChildProcessWithoutNullStreams;
+
+export interface McpStdioClientOptions {
+  args?: string[];
+  env?: Record<string, string>;
+  spawnProcess?: SpawnMcpProcess;
+  requestTimeoutMs?: number;
+  clientInfo?: { name: string; version: string };
+}
+
+interface PendingRequest {
+  method: string;
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout;
+}
+
+export class McpStdioClient {
+  private _child: ChildProcessWithoutNullStreams;
+  private _pending = new Map<number, PendingRequest>();
+  private _nextId = 1;
+  private _buffer = '';
+  private _stderrTail = '';
+  private _exitError: Error | undefined;
+  private _exited = false;
+  private _requestTimeoutMs: number;
+  private _protocolVersion: string | undefined;
+  private _serverInfo: { name?: string; version?: string } | undefined;
+
+  private constructor(
+    child: ChildProcessWithoutNullStreams,
+    requestTimeoutMs: number
+  ) {
+    this._child = child;
+    this._requestTimeoutMs = requestTimeoutMs;
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => this._onStdout(chunk));
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      this._stderrTail = (this._stderrTail + chunk).slice(-STDERR_TAIL_BYTES);
+    });
+    child.stdin.on('error', () => {});
+    child.unref?.();
+    for (const stream of [child.stdin, child.stdout, child.stderr]) {
+      (stream as { unref?: () => void }).unref?.();
+    }
+    child.on('error', (err) => this._fail(err));
+    child.on('close', (code) => {
+      this._exited = true;
+      this._fail(
+        new Error(
+          `Studio's MCP server exited (code ${code ?? 'none'})${
+            this._stderrTail.trim() ? `: ${this._stderrTail.trim()}` : ''
+          }`
+        )
+      );
+    });
+  }
+
+  static async startAsync(
+    command: string,
+    options: McpStdioClientOptions = {}
+  ): Promise<McpStdioClient> {
+    const spawnProcess: SpawnMcpProcess =
+      options.spawnProcess ??
+      ((cmd, args) =>
+        spawn(cmd, args, {
+          stdio: 'pipe',
+          windowsHide: true,
+          ...(options.env ? { env: options.env } : {}),
+        }));
+    const client = new McpStdioClient(
+      spawnProcess(command, options.args ?? []),
+      options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+    );
+
+    try {
+      const result = (await client.requestAsync('initialize', {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: options.clientInfo ?? {
+          name: 'studio-bridge',
+          version: '0.0.0',
+        },
+      })) as {
+        protocolVersion?: string;
+        serverInfo?: { name?: string; version?: string };
+      };
+      client._protocolVersion = result?.protocolVersion;
+      client._serverInfo = result?.serverInfo;
+      client._notify('notifications/initialized');
+    } catch (err) {
+      await client.closeAsync();
+      throw err;
+    }
+    return client;
+  }
+
+  get protocolVersion(): string | undefined {
+    return this._protocolVersion;
+  }
+
+  get serverInfo(): { name?: string; version?: string } | undefined {
+    return this._serverInfo;
+  }
+
+  async listToolsAsync(): Promise<McpTool[]> {
+    const result = (await this.requestAsync('tools/list', {})) as {
+      tools?: McpTool[];
+    };
+    return Array.isArray(result?.tools) ? result.tools : [];
+  }
+
+  async callToolAsync(
+    name: string,
+    args: Record<string, unknown> = {},
+    timeoutMs?: number
+  ): Promise<McpToolResult> {
+    const result = (await this.requestAsync(
+      'tools/call',
+      { name, arguments: args },
+      timeoutMs
+    )) as { isError?: boolean; content?: McpContent[] };
+    const content = Array.isArray(result?.content) ? result.content : [];
+    return {
+      isError: result?.isError === true,
+      content,
+      text: content
+        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('\n'),
+    };
+  }
+
+  requestAsync(
+    method: string,
+    params: unknown,
+    timeoutMs = this._requestTimeoutMs
+  ): Promise<unknown> {
+    if (this._exitError) {
+      return Promise.reject(this._exitError);
+    }
+    const id = this._nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new McpTimeoutError(`${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this._pending.set(id, { method, resolve, reject, timer });
+      this._write({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  get isRunning(): boolean {
+    return !this._exited;
+  }
+
+  async closeAsync(): Promise<void> {
+    this._fail(new Error("Studio's MCP client was closed"));
+    if (this._exited) {
+      return;
+    }
+    let timer: NodeJS.Timeout | undefined;
+    const exited = new Promise<void>((resolve) => {
+      this._child.once('close', () => resolve());
+      timer = setTimeout(resolve, CLOSE_TIMEOUT_MS);
+    });
+    this._child.stdin.end();
+    this._child.kill();
+    await exited;
+    clearTimeout(timer);
+  }
+
+  private _notify(method: string, params?: unknown) {
+    this._write({ jsonrpc: '2.0', method, ...(params ? { params } : {}) });
+  }
+
+  private _write(message: unknown) {
+    this._child.stdin.write(JSON.stringify(message) + '\n');
+  }
+
+  private _onStdout(chunk: string) {
+    this._buffer += chunk;
+    let newline: number;
+    while ((newline = this._buffer.indexOf('\n')) >= 0) {
+      const line = this._buffer.slice(0, newline).trim();
+      this._buffer = this._buffer.slice(newline + 1);
+      if (line) {
+        this._onLine(line);
+      }
+    }
+  }
+
+  private _onLine(line: string) {
+    let message: {
+      id?: unknown;
+      method?: unknown;
+      result?: unknown;
+      error?: { message?: string; code?: number };
+    };
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (typeof message?.id !== 'number' || message.method !== undefined) {
+      return;
+    }
+    const pending = this._pending.get(message.id);
+    if (!pending) {
+      return;
+    }
+    this._pending.delete(message.id);
+    clearTimeout(pending.timer);
+
+    if (message.error) {
+      pending.reject(
+        new Error(
+          `${pending.method} failed: ${
+            message.error.message ?? `error ${message.error.code ?? ''}`
+          }`.trim()
+        )
+      );
+    } else {
+      pending.resolve(repairListResult(message.result));
+    }
+  }
+
+  private _fail(err: Error) {
+    this._exitError ??= err;
+    for (const pending of this._pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(this._exitError);
+    }
+    this._pending.clear();
+  }
+}

package/src/roblox-mcp/mcp/repair-list-result.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { repairListResult } from './repair-list-result.js';
+
+describe('repairListResult', () => {
+  it('fills in the caching hints a 2026-07-28 list result left out', () => {
+    expect(repairListResult({ resultType: 'complete', tools: [] })).toEqual({
+      resultType: 'complete',
+      tools: [],
+      ttlMs: 0,
+      cacheScope: 'private',
+    });
+  });
+
+  it('keeps hints the server sent', () => {
+    const result = {
+      resultType: 'complete',
+      tools: [],
+      ttlMs: 500,
+      cacheScope: 'shared',
+    };
+
+    expect(repairListResult(result)).toBe(result);
+  });
+
+  it('fills only the hint that is missing', () => {
+    expect(
+      repairListResult({ resultType: 'complete', prompts: [], ttlMs: 10 })
+    ).toEqual({
+      resultType: 'complete',
+      prompts: [],
+      ttlMs: 10,
+      cacheScope: 'private',
+    });
+  });
+
+  it('leaves an older protocol result alone', () => {
+    const result = { tools: [] };
+
+    expect(repairListResult(result)).toBe(result);
+  });
+
+  it('leaves a result that is not a list alone', () => {
+    const result = { resultType: 'complete', content: [] };
+
+    expect(repairListResult(result)).toBe(result);
+  });
+
+  it('passes non-objects through', () => {
+    expect(repairListResult(undefined)).toBeUndefined();
+    expect(repairListResult('text')).toBe('text');
+  });
+});

package/src/roblox-mcp/mcp/repair-list-result.ts

@@ -0,0 +1,23 @@
+const LIST_KEYS = ['tools', 'prompts', 'resources', 'resourceTemplates'];
+
+export function repairListResult<T>(result: T): T {
+  if (!result || typeof result !== 'object') {
+    return result;
+  }
+  const record = result as Record<string, unknown>;
+  if (record.resultType === undefined) {
+    return result;
+  }
+  if (!LIST_KEYS.some((key) => Array.isArray(record[key]))) {
+    return result;
+  }
+  if (record.ttlMs !== undefined && record.cacheScope !== undefined) {
+    return result;
+  }
+
+  return {
+    ...record,
+    ttlMs: record.ttlMs ?? 0,
+    cacheScope: record.cacheScope ?? 'private',
+  } as T;
+}

package/src/roblox-mcp/roblox-studio-mcp.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  closeStudioMcpAsync,
+  tryCallStudioToolAsync,
+  tryExecuteLuauAsync,
+  tryListStudiosAsync,
+} from './roblox-studio-mcp.js';
+import {
+  createFakeMcpServer,
+  toolText,
+  type FakeHandler,
+} from './test/fake-mcp-server.js';
+
+const STUDIOS = [
+  { id: 'mcp-1', name: 'Place1' },
+  { id: 'mcp-2', name: 'Hub' },
+];
+
+function fake(handler: FakeHandler = () => undefined, studios = STUDIOS) {
+  const server = createFakeMcpServer((method, params) => {
+    if (method === 'initialize') {
+      return { result: { protocolVersion: '2025-06-18', capabilities: {} } };
+    }
+    if (params?.name === 'list_roblox_studios') {
+      return toolText(JSON.stringify({ studios }));
+    }
+    if (
+      params?.name === 'execute_luau' &&
+      params.arguments.code.includes('os.clock')
+    ) {
+      return toolText('0,0,0');
+    }
+    return handler(method, params);
+  });
+  return {
+    server,
+    options: {
+      executablePath: 'StudioMCP.exe',
+      spawnProcess: () => server.child,
+      listWindowsAsync: async () => [],
+    },
+  };
+}
+
+afterEach(async () => {
+  vi.useRealTimers();
+  await closeStudioMcpAsync();
+});
+
+describe('tryExecuteLuauAsync', () => {
+  it('runs Luau in the targeted Studio and returns its result', async () => {
+    const { server, options } = fake((_method, params) =>
+      params?.name === 'execute_luau' ? toolText('42') : undefined
+    );
+
+    const result = await tryExecuteLuauAsync('return 42', {
+      ...options,
+      target: 'hub',
+    });
+
+    expect(result).toMatchObject({ success: true, value: '42' });
+    expect(server.requests.at(-1)?.params.arguments).toEqual({
+      code: 'return 42',
+      studio_id: 'mcp-2',
+      datamodel_type: 'Edit',
+    });
+  });
+
+  it('sends the context as the data model', async () => {
+    const { server, options } = fake(() => toolText('ok'));
+
+    await tryExecuteLuauAsync('return 1', {
+      ...options,
+      target: 'hub',
+      context: 'server',
+    });
+
+    expect(server.requests.at(-1)?.params.arguments.datamodel_type).toBe(
+      'Server'
+    );
+  });
+
+  it('fails with the script error, naming the Studio', async () => {
+    const { options } = fake(() => toolText('boom', true));
+
+    const result = await tryExecuteLuauAsync('error("boom")', {
+      ...options,
+      target: 'hub',
+    });
+
+    expect(result).toMatchObject({
+      success: false,
+      reason: 'failed',
+      message: 'boom',
+      studio: { studioId: 'mcp-2' },
+    });
+  });
+
+  it('fails with no-studio when the target is ambiguous', async () => {
+    const { options } = fake();
+
+    const result = await tryExecuteLuauAsync('return 1', options);
+
+    expect(result).toMatchObject({ success: false, reason: 'no-studio' });
+  });
+
+  it('fails with unavailable when the server exits before answering', async () => {
+    const server = createFakeMcpServer(() => undefined);
+    server.exit(1, 'no Studio');
+
+    const result = await tryExecuteLuauAsync('return 1', {
+      executablePath: 'StudioMCP.exe',
+      spawnProcess: () => server.child,
+      listWindowsAsync: async () => [],
+    });
+
+    expect(result).toMatchObject({ success: false, reason: 'unavailable' });
+    expect(result.success || result.message).toContain('no Studio');
+  });
+
+  it('fails with timeout when the whole call outlives its deadline', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    const { server, options } = fake(() => undefined);
+
+    const pending = tryExecuteLuauAsync('return 1', {
+      ...options,
+      target: 'hub',
+    });
+    await vi.advanceTimersByTimeAsync(15_000);
+
+    expect(await pending).toMatchObject({ success: false, reason: 'timeout' });
+    expect(server.child.killed).toBe(true);
+  });
+});
+
+describe('tryCallStudioToolAsync', () => {
+  it('fills in the studio id and leaves other tools without a data model', async () => {
+    const { server, options } = fake(() => toolText('Edit'));
+
+    const result = await tryCallStudioToolAsync(
+      'get_studio_state',
+      {},
+      {
+        ...options,
+        target: 'place1',
+      }
+    );
+
+    expect(result).toMatchObject({ success: true, value: 'Edit' });
+    expect(server.requests.at(-1)?.params).toEqual({
+      name: 'get_studio_state',
+      arguments: { studio_id: 'mcp-1' },
+    });
+  });
+});
+
+describe('tryListStudiosAsync', () => {
+  it('lists the open Studios', async () => {
+    const { options } = fake();
+
+    const result = await tryListStudiosAsync(options);
+
+    expect(result.success && result.value.map((s) => s.placeName)).toEqual([
+      'Place1',
+      'Hub',
+    ]);
+  });
+});