dominus-cli 0.1.0

package/dist/mcp.js

@@ -0,0 +1,907 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { WebSocket, WebSocketServer } from 'ws';
+import { EventEmitter } from 'events';
+import { nanoid } from 'nanoid';
+import fs from 'fs';
+import initSqlJs from 'sql.js';
+import path from 'path';
+import os from 'os';
+
+var StudioMsg = {
+  CONNECTED: "studio:connected",
+  DISCONNECTED: "studio:disconnected",
+  EXPLORER: "studio:explorer",
+  OUTPUT: "studio:output",
+  ERROR: "studio:error",
+  SELECTION: "studio:selection",
+  SCRIPT_CONTENT: "studio:script:content",
+  SCRIPT_CHANGED: "studio:script:changed",
+  RESPONSE: "studio:response",
+  REFLECTION: "studio:reflection",
+  TEST_RESULTS: "studio:test:results"
+};
+var CliMsg = {
+  GET_EXPLORER: "cli:get:explorer",
+  GET_SCRIPT: "cli:get:script",
+  SET_SCRIPT: "cli:set:script",
+  RUN_CODE: "cli:run",
+  GET_PROPERTIES: "cli:get:properties",
+  SET_PROPERTIES: "cli:set:properties",
+  INSERT_INSTANCE: "cli:insert",
+  DELETE_INSTANCE: "cli:delete",
+  GET_SELECTION: "cli:get:selection",
+  SEARCH_SCRIPTS: "cli:search:scripts",
+  GET_OUTPUT: "cli:get:output",
+  RUN_TESTS: "cli:run:tests",
+  EXECUTE_RUN_TEST: "cli:test:run",
+  EXECUTE_PLAY_TEST: "cli:test:play",
+  BUILD_UI: "cli:build:ui",
+  GET_REFLECTION: "cli:get:reflection"};
+function createMessage(type, payload) {
+  return { id: nanoid(), type, payload, ts: Date.now() };
+}
+function parseMessage(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`Failed to parse WebSocket message: ${raw.slice(0, 100)}`);
+  }
+}
+function serializeMessage(msg) {
+  return JSON.stringify(msg);
+}
+
+// src/transport/ws-server.ts
+var DominusServer = class extends EventEmitter {
+  wss = null;
+  studioClient = null;
+  controllers = /* @__PURE__ */ new Set();
+  pendingRequests = /* @__PURE__ */ new Map();
+  relayRequests = /* @__PURE__ */ new Map();
+  port;
+  constructor(port = 18088) {
+    super();
+    this.port = port;
+  }
+  start(maxRetries = 0) {
+    return new Promise((resolve, reject) => {
+      const tryPort = (port, attempt) => {
+        const wss = new WebSocketServer({ port });
+        wss.on("listening", () => {
+          this.wss = wss;
+          this.port = port;
+          this.wss.on("connection", (ws) => this.handleConnection(ws));
+          this.emit("server:started", { port });
+          resolve();
+        });
+        wss.on("error", (err) => {
+          if (err.code === "EADDRINUSE" && attempt < maxRetries) {
+            wss.close();
+            tryPort(port + 1, attempt + 1);
+          } else {
+            this.emit("server:error", err);
+            reject(err);
+          }
+        });
+      };
+      tryPort(this.port, 0);
+    });
+  }
+  handleConnection(ws) {
+    let identified = false;
+    ws.on("message", (raw) => {
+      try {
+        const msg = parseMessage(raw.toString());
+        if (!identified) {
+          if (msg.type === StudioMsg.CONNECTED) {
+            identified = true;
+            this.setStudioClient(ws, msg);
+            return;
+          }
+          if (msg.type === "controller:connect") {
+            identified = true;
+            this.addController(ws);
+            ws.send(serializeMessage(createMessage("controller:welcome", {
+              studioConnected: this.isConnected(),
+              port: this.port
+            })));
+            return;
+          }
+        }
+        if (this.controllers.has(ws)) {
+          this.handleControllerMessage(ws, msg);
+        } else {
+          this.handleStudioMessage(msg);
+        }
+      } catch (err) {
+        this.emit("server:error", err);
+      }
+    });
+    ws.on("close", () => {
+      if (this.controllers.has(ws)) {
+        this.controllers.delete(ws);
+        for (const [id, controllerWs] of this.relayRequests) {
+          if (controllerWs === ws) this.relayRequests.delete(id);
+        }
+      } else if (this.studioClient?.ws === ws) {
+        this.studioClient = null;
+        this.emit("studio:disconnected");
+        this.broadcastToControllers("studio:disconnected", {});
+        for (const [id, pending] of this.pendingRequests) {
+          clearTimeout(pending.timer);
+          pending.reject(new Error("Studio disconnected"));
+          this.pendingRequests.delete(id);
+        }
+      }
+    });
+    ws.on("error", (err) => {
+      this.emit("server:error", err);
+    });
+  }
+  setStudioClient(ws, msg) {
+    if (this.studioClient) {
+      this.studioClient.ws.close();
+    }
+    const payload = msg.payload;
+    this.studioClient = {
+      ws,
+      connectedAt: Date.now(),
+      studioVersion: payload.studioVersion,
+      placeId: payload.placeId,
+      placeName: payload.placeName
+    };
+    this.emit("studio:connected", payload);
+    this.broadcastToControllers("studio:connected", payload);
+  }
+  addController(ws) {
+    this.controllers.add(ws);
+    this.emit("controller:connected");
+  }
+  broadcastToControllers(type, payload) {
+    const msg = serializeMessage(createMessage(type, payload));
+    for (const ws of this.controllers) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(msg);
+      }
+    }
+  }
+  handleControllerMessage(controllerWs, msg) {
+    if (!this.studioClient || this.studioClient.ws.readyState !== WebSocket.OPEN) {
+      controllerWs.send(serializeMessage({
+        id: msg.id,
+        type: StudioMsg.RESPONSE,
+        payload: { error: "Studio not connected" },
+        ts: Date.now()
+      }));
+      return;
+    }
+    this.relayRequests.set(msg.id, controllerWs);
+    this.studioClient.ws.send(serializeMessage(msg));
+  }
+  handleStudioMessage(msg) {
+    if (msg.type === StudioMsg.CONNECTED) {
+      const payload = msg.payload;
+      if (this.studioClient) {
+        this.studioClient.studioVersion = payload.studioVersion;
+        this.studioClient.placeId = payload.placeId;
+        this.studioClient.placeName = payload.placeName;
+      }
+      this.emit("studio:connected", payload);
+      this.broadcastToControllers("studio:connected", payload);
+      return;
+    }
+    if (msg.type === StudioMsg.RESPONSE) {
+      const controllerWs = this.relayRequests.get(msg.id);
+      if (controllerWs && controllerWs.readyState === WebSocket.OPEN) {
+        controllerWs.send(serializeMessage(msg));
+        this.relayRequests.delete(msg.id);
+        return;
+      }
+      const pending = this.pendingRequests.get(msg.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        pending.resolve(msg);
+        this.pendingRequests.delete(msg.id);
+      }
+      return;
+    }
+    this.emit(msg.type, msg.payload);
+    this.emit("message", msg);
+    this.broadcastToControllers(msg.type, msg.payload);
+  }
+  sendRequest(type, payload, timeoutMs = 1e4) {
+    return new Promise((resolve, reject) => {
+      if (!this.studioClient || this.studioClient.ws.readyState !== WebSocket.OPEN) {
+        reject(new Error("No Studio connection"));
+        return;
+      }
+      const msg = createMessage(type, payload);
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(msg.id);
+        reject(new Error(`Request timed out: ${type}`));
+      }, timeoutMs);
+      this.pendingRequests.set(msg.id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.studioClient.ws.send(serializeMessage(msg));
+    });
+  }
+  sendNotification(type, payload) {
+    if (!this.studioClient || this.studioClient.ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const msg = createMessage(type, payload);
+    this.studioClient.ws.send(serializeMessage(msg));
+  }
+  isConnected() {
+    return this.studioClient !== null && this.studioClient.ws.readyState === WebSocket.OPEN;
+  }
+  getConnectionInfo() {
+    return this.studioClient;
+  }
+  getPort() {
+    return this.port;
+  }
+  stop() {
+    return new Promise((resolve) => {
+      if (this.studioClient) {
+        this.studioClient.ws.close();
+        this.studioClient = null;
+      }
+      for (const ws of this.controllers) {
+        ws.close();
+      }
+      this.controllers.clear();
+      for (const [, pending] of this.pendingRequests) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error("Server shutting down"));
+      }
+      this.pendingRequests.clear();
+      this.relayRequests.clear();
+      if (this.wss) {
+        this.wss.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+};
+var DOMINUS_DIR = path.join(os.homedir(), ".dominus");
+var CONFIG_PATH = path.join(DOMINUS_DIR, "config.json");
+var DB_PATH = path.join(DOMINUS_DIR, "dominus.db");
+path.join(DOMINUS_DIR, "rules.json");
+var DEFAULTS = {
+  provider: "openai",
+  apiBaseUrl: "",
+  model: "",
+  port: 18088,
+  maxToolIterations: 25,
+  maxVerifyRetries: 3,
+  tokenBudget: 128e3,
+  autoIndex: true,
+  autoLearn: true,
+  userName: "Developer"
+};
+function ensureDir() {
+  if (!fs.existsSync(DOMINUS_DIR)) {
+    fs.mkdirSync(DOMINUS_DIR, { recursive: true });
+  }
+}
+function readJson(filePath, defaults) {
+  try {
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, "utf-8");
+      return { ...defaults, ...JSON.parse(raw) };
+    }
+  } catch {
+  }
+  return { ...defaults };
+}
+function loadConfig() {
+  ensureDir();
+  return readJson(CONFIG_PATH, DEFAULTS);
+}
+function getDbPath() {
+  ensureDir();
+  return DB_PATH;
+}
+
+// src/memory/store.ts
+var db = null;
+var dbPath;
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS facts (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id  TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  category    TEXT NOT NULL,
+  source      TEXT,
+  relevance   REAL DEFAULT 1.0,
+  created_at  INTEGER NOT NULL,
+  accessed_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS summaries (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id  TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  summary     TEXT NOT NULL,
+  created_at  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id  TEXT NOT NULL,
+  role        TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  tool_name   TEXT,
+  created_at  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS script_index (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id  TEXT NOT NULL,
+  path        TEXT NOT NULL,
+  class_name  TEXT NOT NULL,
+  summary     TEXT,
+  line_count  INTEGER,
+  last_hash   TEXT,
+  updated_at  INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_facts_project ON facts(project_id);
+CREATE INDEX IF NOT EXISTS idx_facts_category ON facts(project_id, category);
+CREATE INDEX IF NOT EXISTS idx_scripts_project ON script_index(project_id);
+CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id);
+CREATE INDEX IF NOT EXISTS idx_summaries_project ON summaries(project_id);
+`;
+function persist() {
+  if (!db) return;
+  const data = db.export();
+  fs.writeFileSync(dbPath, Buffer.from(data));
+}
+async function initMemoryStore() {
+  if (db) return;
+  dbPath = getDbPath();
+  const SQL = await initSqlJs();
+  if (fs.existsSync(dbPath)) {
+    const buffer = fs.readFileSync(dbPath);
+    db = new SQL.Database(buffer);
+  } else {
+    db = new SQL.Database();
+  }
+  db.run(SCHEMA);
+  persist();
+}
+function getDb() {
+  if (!db) throw new Error("Memory store not initialized. Call initMemoryStore() first.");
+  return db;
+}
+function storeFact(fact) {
+  const d = getDb();
+  d.run(
+    `INSERT INTO facts (project_id, content, category, source, relevance, created_at, accessed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [
+      fact.projectId,
+      fact.content,
+      fact.category,
+      fact.source ?? null,
+      fact.relevance,
+      fact.createdAt,
+      fact.accessedAt
+    ]
+  );
+  persist();
+  const stmt = d.prepare("SELECT last_insert_rowid()");
+  stmt.step();
+  const row = stmt.get();
+  stmt.free();
+  return row?.[0] ?? 0;
+}
+function recallFacts(projectId, query, limit = 10) {
+  const d = getDb();
+  const keywords = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (keywords.length === 0) {
+    const result2 = d.exec(
+      `SELECT * FROM facts WHERE project_id = ? ORDER BY relevance DESC, accessed_at DESC LIMIT ?`,
+      [projectId, limit]
+    );
+    return rowsToFacts(result2);
+  }
+  const likeClauses = keywords.map(() => `LOWER(content) LIKE ?`).join(" OR ");
+  const likeParams = keywords.map((k) => `%${k}%`);
+  const result = d.exec(
+    `SELECT * FROM facts WHERE project_id = ? AND (${likeClauses})
+     ORDER BY relevance DESC, accessed_at DESC LIMIT ?`,
+    [projectId, ...likeParams, limit]
+  );
+  const facts = rowsToFacts(result);
+  for (const fact of facts) {
+    if (fact.id) {
+      d.run(`UPDATE facts SET accessed_at = ? WHERE id = ?`, [Date.now(), fact.id]);
+    }
+  }
+  if (facts.length > 0) persist();
+  return facts;
+}
+function rowsToFacts(result) {
+  if (!result[0]) return [];
+  return result[0].values.map((row) => ({
+    id: row[0],
+    projectId: row[1],
+    content: row[2],
+    category: row[3],
+    source: row[4],
+    relevance: row[5],
+    createdAt: row[6],
+    accessedAt: row[7]
+  }));
+}
+function getScriptIndex(projectId) {
+  const d = getDb();
+  const result = d.exec(
+    `SELECT path, summary, class_name FROM script_index WHERE project_id = ? ORDER BY path`,
+    [projectId]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((row) => ({
+    path: row[0],
+    summary: row[1] || void 0,
+    className: row[2]
+  }));
+}
+
+// src/mcp/server.ts
+var wsServer;
+async function startMcpServer() {
+  const config = loadConfig();
+  await initMemoryStore();
+  wsServer = new DominusServer(config.port);
+  await wsServer.start();
+  const mcp = new McpServer({
+    name: "dominus",
+    version: "0.1.0"
+  });
+  mcp.tool(
+    "read_script",
+    "Read the source code of a script in Roblox Studio",
+    { path: z.string().describe('Full instance path, e.g. "ServerScriptService.GameManager"') },
+    async ({ path: path2 }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_SCRIPT, { path: path2 });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "edit_script",
+    "Replace the entire source code of a script in Roblox Studio",
+    {
+      path: z.string().describe("Full instance path"),
+      source: z.string().describe("New complete source code")
+    },
+    async ({ path: path2, source }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.SET_SCRIPT, { path: path2, source });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    }
+  );
+  mcp.tool(
+    "run_code",
+    "Execute Luau code in Roblox Studio and return output",
+    { code: z.string().describe("Luau code to execute") },
+    async ({ code }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.RUN_CODE, { code });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "get_explorer",
+    "Get the DataModel explorer tree from Roblox Studio",
+    {
+      rootPath: z.string().optional().describe("Root path to start from. Omit for entire tree."),
+      maxDepth: z.number().optional().default(3).describe("Maximum tree depth")
+    },
+    async ({ rootPath, maxDepth }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_EXPLORER, {
+        rootPath: rootPath ?? null,
+        maxDepth
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "get_properties",
+    "Get all properties of an instance in Roblox Studio",
+    { path: z.string().describe("Full instance path") },
+    async ({ path: path2 }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_PROPERTIES, { path: path2 });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "set_properties",
+    "Set properties on an instance in Roblox Studio",
+    {
+      path: z.string().describe("Full instance path"),
+      properties: z.record(z.unknown()).describe("Key-value pairs of properties to set")
+    },
+    async ({ path: path2, properties }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.SET_PROPERTIES, { path: path2, properties });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    }
+  );
+  mcp.tool(
+    "insert_instance",
+    "Create a new instance in the Roblox Studio DataModel",
+    {
+      className: z.string().describe('Class name (e.g. "Part", "Script")'),
+      parentPath: z.string().describe("Parent instance path"),
+      name: z.string().describe("Name for the new instance"),
+      properties: z.record(z.unknown()).optional().describe("Optional properties to set")
+    },
+    async ({ className, parentPath, name, properties }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.INSERT_INSTANCE, {
+        className,
+        parentPath,
+        name,
+        properties: properties ?? {}
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    }
+  );
+  mcp.tool(
+    "delete_instance",
+    "Delete an instance from the Roblox Studio DataModel",
+    { path: z.string().describe("Full instance path to delete") },
+    async ({ path: path2 }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.DELETE_INSTANCE, { path: path2 });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload) }] };
+    }
+  );
+  mcp.tool(
+    "get_selection",
+    "Get the currently selected instances in Roblox Studio",
+    {},
+    async () => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_SELECTION, {});
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "search_scripts",
+    "Search all scripts in Roblox Studio for a text pattern",
+    {
+      query: z.string().describe("Text to search for"),
+      maxResults: z.number().optional().default(20).describe("Max results")
+    },
+    async ({ query, maxResults }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.SEARCH_SCRIPTS, { query, maxResults });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "get_output",
+    "Get recent output log from Roblox Studio",
+    {
+      limit: z.number().optional().default(50).describe("Max entries"),
+      level: z.enum(["info", "warn", "error"]).optional().describe("Filter by level")
+    },
+    async ({ limit, level }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_OUTPUT, {
+        limit,
+        level: level ?? null
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "get_class_info",
+    "Look up the schema of any Roblox class using ReflectionService. Returns all properties (with types), methods (with parameters), and events. ALWAYS use this before creating or modifying GUI elements to know correct property names and types.",
+    { className: z.string().describe('Roblox class name, e.g. "Frame", "TextLabel", "Part", "MeshPart"') },
+    async ({ className }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.GET_REFLECTION, { className });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "create_ui",
+    'Create an entire UI tree in one call. Pass a declarative JSON tree \u2014 ClassName, Name, properties, Children. All types auto-coerced in Luau (UDim2, Color3, Font, enums). 10x faster than run_code. UDim2: [xScale, xOffset, yScale, yOffset]. Color3: "#hex" or "rgb(r,g,b)". Font: "GothamBold". Enums: string names.',
+    {
+      parent: z.string().optional().describe('Parent: "StarterGui", "PlayerGui", or path. Default: StarterGui'),
+      tree: z.record(z.unknown()).describe(
+        'Root UI node: {ClassName, Name, properties..., Children: [{...}, ...]}. UDim2 as [xScale, xOffset, yScale, yOffset], Color3 as "#hex", Font as "GothamBold"'
+      )
+    },
+    async ({ parent, tree }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(
+        CliMsg.BUILD_UI,
+        { parent: parent ?? "StarterGui", tree }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "run_tests",
+    "Run tests by requiring ModuleScripts matching test naming conventions (*.test, *.spec, *Test, *Spec). Lightweight \u2014 does not enter Run/Play mode.",
+    { testName: z.string().optional().describe("Specific test name, or omit to run all") },
+    async ({ testName }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.RUN_TESTS, {
+        testName: testName ?? null
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "execute_run_test",
+    "Start a Run mode test session using StudioTestService:ExecuteRunModeAsync(). This actually enters Run mode in Studio. Pass args that server scripts can retrieve via GetTestArgs(). Yields until EndTest() is called or the session stops. Returns the value from EndTest(). Use for headless automated tests \u2014 no player, just server scripts.",
+    { args: z.unknown().optional().describe("Arguments passed to the test session. Server scripts get this via StudioTestService:GetTestArgs()") },
+    async ({ args }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.EXECUTE_RUN_TEST, { args: args ?? null }, 12e4);
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "execute_play_test",
+    "Start a solo Play mode test session using StudioTestService:ExecutePlayModeAsync(). This enters Play mode with a player character. Pass args that server scripts can retrieve via GetTestArgs(). Yields until EndTest() is called or the session stops. Returns the value from EndTest(). Use for tests needing a player character and full client-server simulation.",
+    { args: z.unknown().optional().describe("Arguments passed to the test session. Server scripts get this via StudioTestService:GetTestArgs()") },
+    async ({ args }) => {
+      assertConnected();
+      const res = await wsServer.sendRequest(CliMsg.EXECUTE_PLAY_TEST, { args: args ?? null }, 12e4);
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "create_part",
+    "Create a Part with position, size, color, material \u2014 all in one call. Faster than insert_instance + set_properties.",
+    {
+      name: z.string().describe("Name for the part"),
+      parent: z.string().optional().describe("Parent path (default: Workspace)"),
+      shape: z.enum(["Block", "Ball", "Cylinder", "Wedge", "CornerWedge"]).optional().describe("Part shape"),
+      position: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("World position"),
+      size: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("Size in studs"),
+      color: z.string().optional().describe('Hex "#00FF00", BrickColor name, or "rgb(0,255,0)"'),
+      material: z.string().optional().describe("Plastic, Wood, Grass, Neon, Metal, etc."),
+      transparency: z.number().optional().describe("0=opaque, 1=invisible"),
+      anchored: z.boolean().optional().describe("Anchored (default: true)"),
+      canCollide: z.boolean().optional().describe("Has collision")
+    },
+    async (params) => {
+      assertConnected();
+      const properties = {};
+      if (params.position) properties.Position = { X: params.position.x, Y: params.position.y, Z: params.position.z };
+      if (params.size) properties.Size = { X: params.size.x, Y: params.size.y, Z: params.size.z };
+      if (params.color) {
+        const c = params.color;
+        if (c.startsWith("#")) properties.Color = c;
+        else if (c.startsWith("rgb")) {
+          const m = c.match(/(\d+)/g);
+          if (m && m.length >= 3) properties.Color = { red: parseInt(m[0]), green: parseInt(m[1]), blue: parseInt(m[2]) };
+        } else properties.BrickColor = c;
+      }
+      if (params.material) properties.Material = params.material;
+      if (params.transparency !== void 0) properties.Transparency = params.transparency;
+      if (params.anchored !== void 0) properties.Anchored = params.anchored;
+      else properties.Anchored = true;
+      if (params.canCollide !== void 0) properties.CanCollide = params.canCollide;
+      if (params.shape && params.shape !== "Block") properties.Shape = params.shape;
+      const className = params.shape === "Wedge" ? "WedgePart" : params.shape === "CornerWedge" ? "CornerWedgePart" : "Part";
+      const res = await wsServer.sendRequest(CliMsg.INSERT_INSTANCE, {
+        className,
+        parentPath: params.parent ?? "Workspace",
+        name: params.name,
+        properties
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "clone_instance",
+    "Clone an existing instance, optionally rename it, move it, or offset its position",
+    {
+      path: z.string().describe("Path of instance to clone"),
+      newName: z.string().optional().describe("Name for the clone"),
+      newParent: z.string().optional().describe("Parent path for the clone"),
+      offset: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional().describe("Position offset from original")
+    },
+    async (params) => {
+      assertConnected();
+      const parts = params.path.split(".");
+      let resolve = "game";
+      for (const p of parts) resolve += `["${p}"]`;
+      const lines = [`local orig = ${resolve}`, `local clone = orig:Clone()`];
+      if (params.newName) lines.push(`clone.Name = "${params.newName}"`);
+      if (params.newParent) {
+        const pp = params.newParent.split(".");
+        let pr = "game";
+        for (const p of pp) pr += `["${p}"]`;
+        lines.push(`clone.Parent = ${pr}`);
+      } else {
+        lines.push(`clone.Parent = orig.Parent`);
+      }
+      if (params.offset) {
+        lines.push(`if clone:IsA("BasePart") then`);
+        lines.push(`  clone.Position = clone.Position + Vector3.new(${params.offset.x}, ${params.offset.y}, ${params.offset.z})`);
+        lines.push(`end`);
+      }
+      lines.push(`print("Cloned: " .. clone:GetFullName())`);
+      const res = await wsServer.sendRequest(CliMsg.RUN_CODE, { code: lines.join("\n") });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "group_instances",
+    "Group multiple instances into a Model or Folder",
+    {
+      paths: z.array(z.string()).describe("Array of instance paths to group"),
+      groupName: z.string().describe("Name for the group"),
+      groupClass: z.enum(["Model", "Folder"]).optional().describe("Container class (default: Model)"),
+      parent: z.string().optional().describe("Parent path (default: Workspace)")
+    },
+    async (params) => {
+      assertConnected();
+      const gc = params.groupClass ?? "Model";
+      const parent = params.parent ?? "Workspace";
+      const parentParts = parent.split(".");
+      let parentResolve = "game";
+      for (const p of parentParts) parentResolve += `["${p}"]`;
+      const resolves = params.paths.map((path2) => {
+        const parts = path2.split(".");
+        let r = "game";
+        for (const part of parts) r += `["${part}"]`;
+        return r;
+      });
+      const code = [
+        `local group = Instance.new("${gc}")`,
+        `group.Name = "${params.groupName}"`,
+        `group.Parent = ${parentResolve}`,
+        ...resolves.map((r) => `${r}.Parent = group`),
+        `print("Grouped ${params.paths.length} instances into: " .. group:GetFullName())`
+      ].join("\n");
+      const res = await wsServer.sendRequest(CliMsg.RUN_CODE, { code });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "build_multiple",
+    "Create many parts/instances in one batch. Send an array of specs \u2014 all created in a single round-trip. Ideal for building trees, houses, vehicles.",
+    {
+      parts: z.array(z.object({
+        name: z.string(),
+        className: z.string().optional(),
+        parent: z.string().optional(),
+        position: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional(),
+        size: z.object({ x: z.number(), y: z.number(), z: z.number() }).optional(),
+        color: z.string().optional().describe('Hex "#RRGGBB" or BrickColor name'),
+        material: z.string().optional(),
+        transparency: z.number().optional(),
+        anchored: z.boolean().optional(),
+        shape: z.enum(["Block", "Ball", "Cylinder", "Wedge"]).optional()
+      })).describe("Array of part specifications"),
+      groupName: z.string().optional().describe("Group all parts into a Model with this name"),
+      groupParent: z.string().optional().describe("Parent for the group (default: Workspace)")
+    },
+    async (params) => {
+      assertConnected();
+      const parts = params.parts;
+      const groupName = params.groupName;
+      const groupParent = params.groupParent ?? "Workspace";
+      function resolveP(path2) {
+        const segs = path2.split(".");
+        let r = "game";
+        for (const s of segs) r += `["${s}"]`;
+        return r;
+      }
+      const lines = [];
+      if (groupName) {
+        lines.push(`local _group = Instance.new("Model")`);
+        lines.push(`_group.Name = "${groupName}"`);
+        lines.push(`_group.Parent = ${resolveP(groupParent)}`);
+      }
+      for (let i = 0; i < parts.length; i++) {
+        const p = parts[i];
+        const v = `_p${i}`;
+        const cn = p.className ?? (p.shape === "Wedge" ? "WedgePart" : "Part");
+        lines.push(`local ${v} = Instance.new("${cn}")`);
+        lines.push(`${v}.Name = "${p.name}"`);
+        if (p.position) lines.push(`${v}.Position = Vector3.new(${p.position.x}, ${p.position.y}, ${p.position.z})`);
+        if (p.size) lines.push(`${v}.Size = Vector3.new(${p.size.x}, ${p.size.y}, ${p.size.z})`);
+        if (p.color) {
+          if (p.color.startsWith("#")) lines.push(`${v}.Color = Color3.fromHex("${p.color}")`);
+          else lines.push(`${v}.BrickColor = BrickColor.new("${p.color}")`);
+        }
+        if (p.material) lines.push(`${v}.Material = Enum.Material.${p.material}`);
+        if (p.transparency !== void 0) lines.push(`${v}.Transparency = ${p.transparency}`);
+        lines.push(`${v}.Anchored = ${p.anchored ?? true}`);
+        if (p.shape && p.shape !== "Block" && cn === "Part") lines.push(`${v}.Shape = Enum.PartType.${p.shape}`);
+        lines.push(`${v}.Parent = ${groupName ? "_group" : resolveP(p.parent ?? "Workspace")}`);
+      }
+      lines.push(`print("Built ${parts.length} parts${groupName ? ` in ${groupName}` : ""}")`);
+      const res = await wsServer.sendRequest(CliMsg.RUN_CODE, { code: lines.join("\n") });
+      return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
+    }
+  );
+  mcp.tool(
+    "recall_memory",
+    "Search persistent memory for facts about the current Roblox project",
+    { query: z.string().describe("What to search for") },
+    async ({ query }) => {
+      const facts = recallFacts("current", query, 15);
+      const scripts = getScriptIndex("current");
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ facts: facts.map((f) => f.content), scriptIndex: scripts }, null, 2)
+        }]
+      };
+    }
+  );
+  mcp.tool(
+    "remember",
+    "Store a fact about the project in persistent memory for future sessions",
+    {
+      fact: z.string().describe("The fact to remember"),
+      category: z.enum(["architecture", "pattern", "preference", "bug", "api", "general"]).describe("Category")
+    },
+    async ({ fact, category }) => {
+      const now = Date.now();
+      storeFact({ projectId: "current", content: fact, category, source: "mcp", relevance: 1, createdAt: now, accessedAt: now });
+      return { content: [{ type: "text", text: `Remembered: ${fact}` }] };
+    }
+  );
+  mcp.resource(
+    "studio://status",
+    "studio://status",
+    async () => {
+      const info = wsServer.getConnectionInfo();
+      return {
+        contents: [{
+          uri: "studio://status",
+          text: JSON.stringify({
+            connected: wsServer.isConnected(),
+            placeName: info?.placeName,
+            placeId: info?.placeId,
+            studioVersion: info?.studioVersion,
+            port: wsServer.getPort()
+          }, null, 2),
+          mimeType: "application/json"
+        }]
+      };
+    }
+  );
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+}
+function assertConnected() {
+  if (!wsServer.isConnected()) {
+    throw new Error(
+      "Roblox Studio is not connected. Open Studio and click the Dominus plugin Connect button."
+    );
+  }
+}
+
+// src/mcp/index.ts
+startMcpServer().catch((err) => {
+  console.error("Failed to start Dominus MCP server:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=mcp.js.map
+//# sourceMappingURL=mcp.js.map