rbxstudio-mcp 2.3.1 → 2.4.0

package/dist/tools/index.js

@@ -1,5 +1,9 @@
 import { StudioHttpClient } from './studio-client.js';
 import * as zlib from 'zlib';
+import { randomUUID } from 'node:crypto';
+import { ensureDocsCache } from '../docs/fetcher.js';
+import { listDocs, readDocFile, searchDocs, } from '../docs/search.js';
+import { resolveReference } from '../docs/reference.js';
 // PNG encoding utilities
 function createPNG(rgbaData, width, height) {
     // PNG signature
@@ -70,6 +74,54 @@ export class RobloxStudioTools {
         this.bridge = bridge;
         this.client = new StudioHttpClient(bridge);
     }
+    // ============================================
+    // MCP-INTERNAL SAFETY GUARDS
+    //
+    // run_live_lua relies on injected companion Scripts that live in
+    // ServerScriptService and StarterPlayer.StarterPlayerScripts. We don't
+    // want a confused AI to accidentally delete/edit/disable them via the
+    // generic destructive tools (set_property, delete_object, set_script_source,
+    // edit_script, find_and_replace_in_scripts, move_instance) — those would
+    // silently break the bridge.
+    //
+    // The plugin already does opportunistic sweeping by tag/name on activate
+    // and at the start/end of each play_solo. This guard is the second layer:
+    // refuse the operation outright with a friendly explanation, so the AI
+    // gets explicit feedback instead of mysterious "no eval reply" errors.
+    // ============================================
+    static MCP_INTERNAL_NAMES = [
+        '_MCPTestCompanion',
+        '_MCPTestCompanion_Client',
+    ];
+    isMCPInternal(path) {
+        if (!path || typeof path !== 'string')
+            return false;
+        for (const name of RobloxStudioTools.MCP_INTERNAL_NAMES) {
+            // Match as a path segment (preceded/followed by '.' or end-of-string),
+            // not as a substring inside an arbitrary user-named instance.
+            if (path === name ||
+                path.endsWith('.' + name) ||
+                path.includes('.' + name + '.') ||
+                path.startsWith(name + '.')) {
+                return true;
+            }
+        }
+        return false;
+    }
+    mcpInternalRefusal(action, instancePath) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: 'mcp_internal',
+                        message: `Refusing to ${action} "${instancePath}" — this is an MCP-internal companion Script used by run_live_lua / play_solo. The plugin manages its lifecycle automatically; if you really want it gone, run stop_play and the plugin will sweep it on the next activation. (Names reserved: _MCPTestCompanion, _MCPTestCompanion_Client.)`,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
     // File System Tools
     async getFileTree(path = '') {
         const response = await this.client.request('/api/file-tree', { path });
@@ -207,11 +259,57 @@ export class RobloxStudioTools {
             ]
         };
     }
+    /**
+     * grep — Claude Code-style search across the instance tree.
+     *
+     * Forwards to the Studio plugin which does a single `GetDescendants` walk
+     * scoped to `path`, filters by `type` (via `IsA`) and `glob` (Lua pattern
+     * over Name), then scans `Source` line-by-line (or full-source if
+     * `multiline`) for `pattern`. Designed to mirror the parameter surface of
+     * Claude Code's Grep tool 1:1 so the LLM can reuse muscle memory.
+     */
+    async grep(pattern, options = {}) {
+        if (typeof pattern !== 'string' || pattern.length === 0) {
+            throw new Error('pattern is required for grep (use ".*" for name-only searches)');
+        }
+        const response = await this.client.request('/api/grep', {
+            pattern,
+            path: options.path ?? 'game',
+            glob: options.glob,
+            type: options.type ?? ['LuaSourceContainer'],
+            caseInsensitive: options.caseInsensitive ?? false,
+            after: options.after ?? 0,
+            before: options.before ?? 0,
+            context: options.context ?? 0,
+            outputMode: options.outputMode ?? 'files_with_matches',
+            headLimit: options.headLimit ?? 0,
+            multiline: options.multiline ?? false,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    }
     // Property Modification Tools
     async setProperty(instancePath, propertyName, propertyValue) {
         if (!instancePath || !propertyName) {
             throw new Error('Instance path and property name are required for set_property');
         }
+        // Refuse to mutate MCP-internal companions — only the destructive
+        // properties; reading/altering benign metadata (e.g. Source via the
+        // dedicated API) is already gated below.
+        if (this.isMCPInternal(instancePath)) {
+            const dangerous = new Set([
+                'Disabled', 'Source', 'Parent', 'Name', 'Archivable', 'RunContext', 'Enabled',
+            ]);
+            if (dangerous.has(propertyName)) {
+                return this.mcpInternalRefusal(`set ${propertyName} on`, instancePath);
+            }
+        }
         const response = await this.client.request('/api/set-property', {
             instancePath,
             propertyName,
@@ -331,6 +429,9 @@ export class RobloxStudioTools {
         if (!instancePath) {
             throw new Error('Instance path is required for delete_object');
         }
+        if (this.isMCPInternal(instancePath)) {
+            return this.mcpInternalRefusal('delete', instancePath);
+        }
         const response = await this.client.request('/api/delete-object', { instancePath });
         return {
             content: [
@@ -416,7 +517,14 @@ export class RobloxStudioTools {
             ]
         };
     }
-    // Script Management Tools
+    // ============================================
+    // SCRIPT MANAGEMENT TOOLS
+    //
+    // The legacy line-based partial editors (edit_script_lines /
+    // insert_script_lines / delete_script_lines) were removed in favor of
+    // the string-based editScript() below — line numbers shift after every
+    // edit, which makes line-based editing unreliable for AI workflows.
+    // ============================================
     async getScriptSource(instancePath, startLine, endLine) {
         if (!instancePath) {
             throw new Error('Instance path is required for get_script_source');
@@ -435,50 +543,10 @@ export class RobloxStudioTools {
         if (!instancePath || typeof source !== 'string') {
             throw new Error('Instance path and source code string are required for set_script_source');
         }
-        const response = await this.client.request('/api/set-script-source', { instancePath, source });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(response, null, 2)
-                }
-            ]
-        };
-    }
-    // Partial Script Editing Tools
-    async editScriptLines(instancePath, startLine, endLine, newContent) {
-        if (!instancePath || !startLine || !endLine || typeof newContent !== 'string') {
-            throw new Error('Instance path, startLine, endLine, and newContent are required for edit_script_lines');
-        }
-        const response = await this.client.request('/api/edit-script-lines', { instancePath, startLine, endLine, newContent });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(response, null, 2)
-                }
-            ]
-        };
-    }
-    async insertScriptLines(instancePath, afterLine, newContent) {
-        if (!instancePath || typeof newContent !== 'string') {
-            throw new Error('Instance path and newContent are required for insert_script_lines');
-        }
-        const response = await this.client.request('/api/insert-script-lines', { instancePath, afterLine: afterLine || 0, newContent });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(response, null, 2)
-                }
-            ]
-        };
-    }
-    async deleteScriptLines(instancePath, startLine, endLine) {
-        if (!instancePath || !startLine || !endLine) {
-            throw new Error('Instance path, startLine, and endLine are required for delete_script_lines');
+        if (this.isMCPInternal(instancePath)) {
+            return this.mcpInternalRefusal('rewrite source of', instancePath);
         }
-        const response = await this.client.request('/api/delete-script-lines', { instancePath, startLine, endLine });
+        const response = await this.client.request('/api/set-script-source', { instancePath, source });
         return {
             content: [
                 {
@@ -488,12 +556,9 @@ export class RobloxStudioTools {
             ]
         };
     }
-    // ============================================
-    // CLAUDE CODE-STYLE SCRIPT EDITING TOOLS
-    // ============================================
     /**
-     * edit_script - String-based script editing like Claude Code's Edit tool
-     * Find exact text and replace it - no line numbers needed!
+     * edit_script - String-based script editing like Claude Code's Edit tool.
+     * Find exact text and replace it - no line numbers needed.
      */
     async editScript(instancePath, oldString, newString, replaceAll = false, validateAfter = true) {
         if (!instancePath) {
@@ -508,6 +573,9 @@ export class RobloxStudioTools {
         if (oldString === newString) {
             throw new Error('old_string and new_string must be different');
         }
+        if (this.isMCPInternal(instancePath)) {
+            return this.mcpInternalRefusal('edit', instancePath);
+        }
         const response = await this.client.request('/api/edit-script', {
             instancePath,
             oldString,
@@ -525,7 +593,7 @@ export class RobloxStudioTools {
         };
     }
     /**
-     * search_script - Search for patterns within a script (like grep)
+     * search_script - Search for patterns within a script (like grep).
      */
     async searchScript(instancePath, pattern, useRegex = false, contextLines = 0) {
         if (!instancePath || !pattern) {
@@ -547,7 +615,7 @@ export class RobloxStudioTools {
         };
     }
     /**
-     * get_script_function - Extract a specific function from a script by name
+     * get_script_function - Extract a specific function from a script by name.
      */
     async getScriptFunction(instancePath, functionName) {
         if (!instancePath || !functionName) {
@@ -567,7 +635,7 @@ export class RobloxStudioTools {
         };
     }
     /**
-     * find_and_replace_in_scripts - Find and replace across multiple scripts
+     * find_and_replace_in_scripts - Batch find-and-replace across multiple scripts.
      */
     async findAndReplaceInScripts(paths, oldString, newString, validateAfter = true) {
         if (!paths || paths.length === 0) {
@@ -576,12 +644,43 @@ export class RobloxStudioTools {
         if (typeof oldString !== 'string' || typeof newString !== 'string') {
             throw new Error('old_string and new_string are required');
         }
+        // Filter out MCP-internal paths and report which ones we skipped, so
+        // the AI doesn't silently include companions in a batch rename.
+        const blocked = [];
+        const allowed = [];
+        for (const p of paths) {
+            if (this.isMCPInternal(p)) {
+                blocked.push(p);
+            }
+            else {
+                allowed.push(p);
+            }
+        }
+        if (allowed.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'mcp_internal',
+                            message: `All targeted paths are MCP-internal companion Scripts. Refusing to edit. Blocked: ${blocked.join(', ')}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         const response = await this.client.request('/api/find-and-replace-in-scripts', {
-            paths,
+            paths: allowed,
             oldString,
             newString,
             validateAfter
         });
+        if (blocked.length > 0) {
+            const responseObj = response;
+            responseObj.skippedMCPInternal = blocked;
+            responseObj.note = `${blocked.length} MCP-internal companion Script(s) were skipped: ${blocked.join(', ')}`;
+        }
         return {
             content: [
                 {
@@ -742,6 +841,9 @@ export class RobloxStudioTools {
         if (!sourcePath || !targetParent) {
             throw new Error('Source path and target parent are required for clone_instance');
         }
+        if (this.isMCPInternal(sourcePath)) {
+            return this.mcpInternalRefusal('clone', sourcePath);
+        }
         const response = await this.client.request('/api/clone-instance', {
             sourcePath,
             targetParent,
@@ -760,6 +862,9 @@ export class RobloxStudioTools {
         if (!instancePath || !newParent) {
             throw new Error('Instance path and new parent are required for move_instance');
         }
+        if (this.isMCPInternal(instancePath)) {
+            return this.mcpInternalRefusal('move', instancePath);
+        }
         const response = await this.client.request('/api/move-instance', {
             instancePath,
             newParent
@@ -796,26 +901,54 @@ export class RobloxStudioTools {
     // ============================================
     // UNDO/REDO TOOLS
     // ============================================
-    async undo() {
-        const response = await this.client.request('/api/undo', {});
+    async undo(count) {
+        // Default + clamp client-side so the plugin can stay strict. Studio's
+        // own undo stack is the real source of truth; the plugin stops early if
+        // it runs out, regardless of what we ask for.
+        const safeCount = typeof count === 'number' && Number.isFinite(count)
+            ? Math.max(1, Math.min(100, Math.floor(count)))
+            : 1;
+        const response = await this.client.request('/api/undo', { count: safeCount });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(response, null, 2)
-                }
-            ]
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
         };
     }
-    async redo() {
-        const response = await this.client.request('/api/redo', {});
+    async redo(count) {
+        const safeCount = typeof count === 'number' && Number.isFinite(count)
+            ? Math.max(1, Math.min(100, Math.floor(count)))
+            : 1;
+        const response = await this.client.request('/api/redo', { count: safeCount });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(response, null, 2)
-                }
-            ]
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    }
+    async getHistory(limit, includeDetails) {
+        // 20 is a sweet spot: enough for "what did I just do?" recall without
+        // bloating context. Plugin caps at MAX_ACTION_HISTORY (100).
+        const safeLimit = typeof limit === 'number' && Number.isFinite(limit)
+            ? Math.max(1, Math.min(100, Math.floor(limit)))
+            : 20;
+        const response = await this.client.request('/api/get-history', {
+            limit: safeLimit,
+            includeDetails: includeDetails === true,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
         };
     }
     // ============================================
@@ -974,6 +1107,170 @@ export class RobloxStudioTools {
         };
     }
     // ============================================
+    // RUN_LIVE_LUA — execute code inside the running play test
+    //
+    // Flow:
+    //   1. Pre-flight: bridge.getTestSessionStatus() — fail fast with a
+    //      structured `error` field (no thrown exception) for the common
+    //      cases the AI needs to handle differently (no playtest, ended,
+    //      companion not yet connected, no clients on a client-target call,
+    //      loadstring disabled).
+    //   2. Generate a replyId, register a watchdog slot.
+    //   3. Enqueue an "eval" command on the appropriate companion's queue.
+    //      The companion picks it up on its next poll (~400ms cadence),
+    //      runs it under loadstring + xpcall + LogService capture, then
+    //      POSTs the result to /test-session/eval-result.
+    //   4. Await the slot — resolves with the companion's reply, or with a
+    //      synthetic timeout / companion_error if the watchdog fires.
+    //
+    // This method NEVER throws — all failure paths come back as
+    // `{ success: false, error: <enum>, message: ... }` so the AI can branch
+    // on the error type without try/catch ceremony.
+    // ============================================
+    async runLiveLua(code, target = 'server', playerName, timeoutMs = 5000, captureLogs = true) {
+        // Helper to wrap structured failures consistently.
+        const fail = (error, message, extra = {}) => ({
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ success: false, error, message, target, ...extra }, null, 2),
+                },
+            ],
+        });
+        // ---- Argument validation (still no throws — friendly errors) -------
+        if (typeof code !== 'string' || code.length === 0) {
+            return fail('invalid_args', 'code is required and must be a non-empty string.');
+        }
+        if (target !== 'server' && target !== 'client') {
+            return fail('invalid_args', `target must be "server" or "client", got "${target}".`);
+        }
+        const tMs = Math.max(1000, Math.min(30000, Math.floor(Number(timeoutMs) || 5000)));
+        // ---- Pre-flight on the bridge state --------------------------------
+        const status = this.bridge.getTestSessionStatus();
+        if (!status) {
+            return fail('no_playtest', 'No play test is running. Call play_solo first to start one, then retry run_live_lua.');
+        }
+        if (status.status === 'ended') {
+            return fail('playtest_ended', `The play test has already ended. Start a new one with play_solo before running live code.`);
+        }
+        // ---- Resolve target slot -------------------------------------------
+        // Architecture note: HttpService is server-only in Roblox, so the client
+        // companion CANNOT POST eval-results directly. Instead, target='client'
+        // commands ride the SERVER queue with a `forwardTo` metadata field; the
+        // server companion picks them up, dispatches via clientRelay:InvokeClient,
+        // and POSTs the result on the client's behalf. This means the bridge's
+        // reply slot is always 'server' regardless of logical target.
+        let resolvedClientName = null;
+        let resolvedClientUserId = null;
+        const evalArgs = {
+            // replyId added below
+            code,
+            timeoutMs: tMs,
+            captureLogs: !!captureLogs,
+        };
+        if (target === 'server') {
+            if (!status.serverReady) {
+                return fail('companion_not_ready', 'Server companion has not connected yet. The play test was started but the in-test Script has not made its first poll. Wait ~1s and retry.');
+            }
+            if (!status.serverLoadstringReady) {
+                return fail('loadstring_disabled', 'ServerScriptService.LoadStringEnabled is false in this place, so the server companion cannot loadstring user code. Enable LoadStringEnabled in Studio (Game Settings → Security → Allow HTTP Requests / LoadString) BEFORE starting the test, then re-run play_solo.');
+            }
+        }
+        else {
+            // target === 'client'
+            const clients = status.clients;
+            if (clients.length === 0) {
+                return fail('no_clients_connected', 'No client companion has registered yet. Either no Player has joined the test, the LocalScript hasn\'t fired its hello RemoteEvent yet, or the server companion isn\'t set up. Wait briefly, or fall back to target="server".');
+            }
+            let chosen = clients[0];
+            if (playerName) {
+                const match = clients.find((c) => c.name === playerName || c.name.toLowerCase() === playerName.toLowerCase());
+                if (!match) {
+                    return fail('no_such_player', `No connected client named "${playerName}". Connected players: ${clients
+                        .map((c) => `${c.name} (userId=${c.userId})`)
+                        .join(', ')}.`, { connectedClients: clients });
+                }
+                chosen = match;
+            }
+            else if (clients.length > 1) {
+                // Multi-client play test, ambiguous — bail loudly.
+                return fail('multiple_clients', `Multiple clients are connected; pass playerName to disambiguate. Connected: ${clients
+                    .map((c) => `${c.name} (userId=${c.userId})`)
+                    .join(', ')}.`, { connectedClients: clients });
+            }
+            if (!chosen.ready) {
+                return fail('companion_not_ready', `Client companion for ${chosen.name} (userId=${chosen.userId}) has not finished its hello yet. Wait briefly and retry.`);
+            }
+            // Loadstring is core (always enabled in client LocalScripts), but we
+            // surface the flag for completeness if the companion ever reports
+            // false.
+            if (!chosen.loadstringReady) {
+                return fail('loadstring_disabled', `Client companion for ${chosen.name} reported loadstring unavailable. (This is unusual on the client; check that the LocalScript was injected correctly.)`);
+            }
+            resolvedClientName = chosen.name;
+            resolvedClientUserId = chosen.userId;
+            // forwardTo tells the server companion to InvokeClient this player
+            // instead of running the code locally on the server.
+            evalArgs.forwardTo = { userId: chosen.userId, playerName: chosen.name };
+        }
+        // ---- Register slot, then enqueue the command ----------------------
+        // Use the bridge's enqueue first because if it returns false we want
+        // to skip allocating a watcher promise. But we need the replyId baked
+        // into the enqueued args, so generate it up front.
+        const replyId = randomUUID();
+        evalArgs.replyId = replyId;
+        // Register the watchdog slot BEFORE enqueueing. We always use 'server'
+        // as the slot target because the server companion is what actually
+        // POSTs /test-session/eval-result back to us (even for client-target
+        // evals — see forwardTo dispatch in the server companion template).
+        const replyPromise = this.bridge.registerEvalReply(replyId, 'server', tMs);
+        const queued = this.bridge.enqueueTestCommand({
+            cmd: 'eval',
+            args: evalArgs,
+        }, 'server');
+        if (!queued) {
+            // Bridge couldn't accept (session ended between status check and
+            // enqueue, or invalid target). The watchdog will eventually trigger
+            // a companion_error reply, but we'd rather not wait a full grace
+            // window — return immediately.
+            return fail('companion_error', 'Failed to enqueue eval command on the bridge (session may have just ended). Re-check play_solo state.');
+        }
+        // Await the reply (will always resolve — watchdog guarantees it).
+        const startedAt = Date.now();
+        const reply = await replyPromise;
+        const totalDurationMs = Date.now() - startedAt;
+        // ---- Map the reply into the canonical Result shape ----------------
+        const baseResult = {
+            success: !!reply.ok,
+            target,
+            timeoutMs: tMs,
+            durationMs: typeof reply.durationMs === 'number' ? reply.durationMs : totalDurationMs,
+        };
+        if (resolvedClientName)
+            baseResult.player = { name: resolvedClientName, userId: resolvedClientUserId };
+        if (reply.ok) {
+            baseResult.values = reply.values ?? [];
+            if (reply.logs && reply.logs.length > 0)
+                baseResult.logs = reply.logs;
+        }
+        else {
+            baseResult.error = reply.errorType ?? 'companion_error';
+            baseResult.message = reply.error ?? 'Unknown eval failure.';
+            if (reply.traceback)
+                baseResult.traceback = reply.traceback;
+            if (reply.logs && reply.logs.length > 0)
+                baseResult.logs = reply.logs;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(baseResult, null, 2),
+                },
+            ],
+        };
+    }
+    // ============================================
     // SCREENSHOT TOOL
     // ============================================
     async captureScreenshot(maxWidth, maxHeight) {
@@ -1122,6 +1419,80 @@ export class RobloxStudioTools {
             ],
         };
     }
+    /**
+     * render_gui - Render a 2D GUI (ScreenGui / GuiObject) to a PNG image.
+     *
+     * ViewportFrame is 3D-only, so GUIs are captured plugin-side by cloning the
+     * target's real ScreenGui into CoreGui (faithful placement), taking a
+     * full-screen CaptureService screenshot, then cropping. region "element"
+     * (default) crops tight to the element's rect; "screen" returns the whole
+     * viewport so on-screen placement can be verified. Here we just convert the
+     * returned RGBA to PNG, mirroring renderObjectView.
+     */
+    async renderGui(instancePath, options) {
+        if (!instancePath) {
+            throw new Error('Instance path is required for render_gui');
+        }
+        const response = await this.client.request('/api/render-gui', {
+            instancePath,
+            region: options?.region || 'element',
+            maxWidth: options?.maxWidth,
+            maxHeight: options?.maxHeight,
+        });
+        const responseData = response;
+        if (responseData.success && responseData.base64) {
+            try {
+                const rgbaBuffer = Buffer.from(responseData.base64, 'base64');
+                const width = responseData.width;
+                const height = responseData.height;
+                const expectedSize = width * height * 4;
+                if (rgbaBuffer.length !== expectedSize) {
+                    throw new Error(`Buffer size mismatch: got ${rgbaBuffer.length}, expected ${expectedSize}`);
+                }
+                const pngBuffer = createPNG(rgbaBuffer, width, height);
+                const pngBase64 = pngBuffer.toString('base64');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: responseData.message,
+                                guiInfo: responseData.guiInfo,
+                                format: 'PNG',
+                            }, null, 2),
+                        },
+                        {
+                            type: 'image',
+                            data: pngBase64,
+                            mimeType: 'image/png',
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: `PNG conversion failed: ${err instanceof Error ? err.message : String(err)}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    }
     // ============================================
     // CAMERA CONTROL SYSTEM
     // ============================================
@@ -1165,5 +1536,151 @@ export class RobloxStudioTools {
             ]
         };
     }
+    // ============================================
+    // ROBLOX CREATOR-DOCS TOOLS
+    //
+    // These tools mirror github.com/Roblox/creator-docs to a local cache
+    // and let the model search/read it like a local repo. They do NOT go
+    // through the Studio HTTP bridge — they're pure server-side.
+    //
+    // The cache is downloaded lazily on first use (~5s, ~30MB) and
+    // refreshed at most once every 24h with a SHA short-circuit. See
+    // src/docs/fetcher.ts for the strategy.
+    // ============================================
+    async searchRobloxDocs(query, options = {}) {
+        if (!query || typeof query !== 'string') {
+            throw new Error('query is required for search_roblox_docs');
+        }
+        const ensured = await ensureDocsCache();
+        // Plumb the docs SHA through so hybrid mode can locate / build the
+        // matching semantic index. Without this, hybrid mode degrades to
+        // pure keyword (semanticUsed=false in the response).
+        const summary = await searchDocs(ensured.cacheDir, query, options, {
+            docsSha: ensured.meta.sha,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        cache: {
+                            action: ensured.action,
+                            sha: ensured.meta.sha,
+                            downloadedAt: ensured.meta.downloadedAt,
+                            durationMs: ensured.durationMs,
+                        },
+                        query,
+                        options,
+                        ...summary,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async getRobloxDoc(relPath) {
+        if (!relPath || typeof relPath !== 'string') {
+            throw new Error('path is required for get_roblox_doc');
+        }
+        const ensured = await ensureDocsCache();
+        const doc = await readDocFile(ensured.cacheDir, relPath);
+        if (!doc) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Doc not found: "${relPath}". Use list_roblox_docs to discover paths, or search_roblox_docs to find a hit.`,
+                            cache: {
+                                sha: ensured.meta.sha,
+                                fileCount: ensured.meta.fileCount,
+                                cacheDir: ensured.cacheDir,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        path: doc.path,
+                        bytes: doc.bytes,
+                        cache: {
+                            action: ensured.action,
+                            sha: ensured.meta.sha,
+                        },
+                        content: doc.content,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async listRobloxDocs(relPath = '', options = {}) {
+        const ensured = await ensureDocsCache();
+        const listing = await listDocs(ensured.cacheDir, relPath, options);
+        if (!listing) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Path not found: "${relPath}".`,
+                            cache: { sha: ensured.meta.sha, fileCount: ensured.meta.fileCount },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        cache: {
+                            action: ensured.action,
+                            sha: ensured.meta.sha,
+                        },
+                        ...listing,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async getRobloxApiReference(name, category) {
+        if (!name || typeof name !== 'string') {
+            throw new Error('name is required for get_roblox_api_reference');
+        }
+        const ensured = await ensureDocsCache();
+        const result = await resolveReference(ensured.cacheDir, name, category);
+        if (!result) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `No API reference found for "${name}"${category ? ` in category "${category}"` : ''}. Try search_roblox_docs to find similar names.`,
+                            cache: { sha: ensured.meta.sha, fileCount: ensured.meta.fileCount },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        cache: {
+                            action: ensured.action,
+                            sha: ensured.meta.sha,
+                        },
+                        ...result,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
 }
 //# sourceMappingURL=index.js.map