roblox-mcp-difz 1.0.0

package/bin/roblox-mcp

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// roblox-mcp CLI entry point
+// Referenced by "bin" in package.json
+require('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * cli.ts — CLI dispatcher for roblox-mcp-difz
+ *
+ * Commands:
+ *   roblox-mcp-difz              → start HTTP server
+ *   roblox-mcp-difz start        → start HTTP server
+ *   roblox-mcp-difz start:stdio  → start stdio MCP transport + HTTP
+ *   roblox-mcp-difz setup        → interactive setup wizard
+ *   roblox-mcp-difz setup --ai <name> → auto-setup for specific AI
+ */
+const path = require('path');
+const readline = require('readline');
+function printBanner(port, toolsCount, mode, wsCount) {
+    console.log('╔══════════════════════════════════════════════════════╗');
+    console.log('║           Roblox MCP Server v1.0.0                  ║');
+    console.log('╠══════════════════════════════════════════════════════╣');
+    console.log(`║  HTTP Server : http://localhost:${port}               ║`);
+    console.log(`║  MCP Endpoint: POST http://localhost:${port}/mcp      ║`);
+    console.log(`║  WS Endpoint : ws://localhost:${port}/ws              ║`);
+    console.log(`║  Client Script: http://localhost:${port}/mcp.luau     ║`);
+    console.log(`║  Tools       : ${String(toolsCount).padStart(2)} registered                  ║`);
+    console.log(`║  Mode        : ${mode.padEnd(20)}        ║`);
+    console.log('╚══════════════════════════════════════════════════════╝');
+}
+async function cmdStart(stdioMode) {
+    const { createApp } = require('./server-core');
+    const PORT = parseInt(process.env.MCP_PORT, 10) || 28429;
+    if (stdioMode) {
+        const orig = console.log;
+        console.log = function (...args) {
+            process.stderr.write('[MCP] ' + args.join(' ') + '\n');
+        };
+    }
+    const { app, server, tools, mcp, wss } = createApp({ stdio: stdioMode });
+    server.listen(PORT, () => {
+        const mode = stdioMode ? 'HTTP + stdio MCP + WS' : 'HTTP + WS';
+        printBanner(PORT, tools.count, mode, wss ? wss.connectedCount : 0);
+        if (stdioMode) {
+            console.log('[MCP] stdio transport active — waiting for JSON-RPC messages on stdin…');
+            const rl = readline.createInterface({ input: process.stdin });
+            rl.on('line', async (line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                let message;
+                try {
+                    message = JSON.parse(trimmed);
+                }
+                catch {
+                    return;
+                }
+                if (message.id === undefined || message.id === null) {
+                    try {
+                        await mcp.handleMessage(message);
+                    }
+                    catch { }
+                    return;
+                }
+                try {
+                    const result = await mcp.handleMessage(message);
+                    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, ...result }) + '\n');
+                }
+                catch (err) {
+                    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: err.message } }) + '\n');
+                }
+            });
+            rl.on('close', () => process.exit(0));
+        }
+    });
+}
+async function cmdSetup(targetAI) {
+    const { runSetupWizard } = require('./setup');
+    await runSetupWizard(targetAI);
+}
+function cmdHelp() {
+    console.log(`
+roblox-mcp-difz — Roblox MCP Server
+
+USAGE:
+  roblox-mcp-difz                     Start HTTP server (port 28429)
+  roblox-mcp-difz start               Start HTTP server
+  roblox-mcp-difz start:stdio         Start stdio MCP transport + HTTP
+  roblox-mcp-difz setup               Interactive setup wizard
+  roblox-mcp-difz setup --ai <name>   Setup for specific AI (claude-code, claude-desktop, cursor, windsurf, generic)
+  roblox-mcp-difz --help              Show this help
+
+ENV:
+  MCP_PORT  Port for HTTP server (default: 28429)
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        cmdHelp();
+        return;
+    }
+    if (cmd === 'setup') {
+        const aiFlag = args.indexOf('--ai');
+        const targetAI = aiFlag !== -1 ? args[aiFlag + 1] : null;
+        await cmdSetup(targetAI);
+        return;
+    }
+    if (cmd === 'start:stdio' || args.includes('--stdio')) {
+        await cmdStart(true);
+        return;
+    }
+    await cmdStart(false);
+}
+if (require.main === module) {
+    main().catch((err) => {
+        console.error('[roblox-mcp-difz] Fatal:', err.message);
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * index.ts — Programmatic entry for roblox-mcp
+ *
+ * Usage:
+ *   const robloxMcp = require('roblox-mcp-difz');
+ *   const { app, queue, tools } = robloxMcp.createApp({ verbose: true });
+ *   app.listen(28429);
+ *
+ *   console.log('Tools:', robloxMcp.getTools().length);
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * index.ts — Programmatic entry for roblox-mcp
+ *
+ * Usage:
+ *   const robloxMcp = require('roblox-mcp-difz');
+ *   const { app, queue, tools } = robloxMcp.createApp({ verbose: true });
+ *   app.listen(28429);
+ *
+ *   console.log('Tools:', robloxMcp.getTools().length);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const { createApp } = require('./server-core');
+const { ToolDefinitions } = require('./tool-definitions');
+const { QueueManager } = require('./queue-manager');
+const { SessionManager } = require('./session-manager');
+const { WsServer } = require('./ws-server');
+const processManager = require('./process-manager');
+function getTools() {
+    return new ToolDefinitions().getTools();
+}
+module.exports = {
+    createApp,
+    getTools,
+    ToolDefinitions,
+    QueueManager,
+    SessionManager,
+    WsServer,
+    processManager,
+};

package/dist/mcp-handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * mcp-handler.ts
+ *
+ * MCP (Model Context Protocol) JSON-RPC 2.0 message handler.
+ *
+ * Server-side tools (get_roblox_processes, launch_roblox, open_game, etc.)
+ * are executed directly on Node — not sent to the executor queue.
+ */
+export {};

package/dist/mcp-handler.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * mcp-handler.ts
+ *
+ * MCP (Model Context Protocol) JSON-RPC 2.0 message handler.
+ *
+ * Server-side tools (get_roblox_processes, launch_roblox, open_game, etc.)
+ * are executed directly on Node — not sent to the executor queue.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Tools that run on the Node server directly, not via executor */
+const SERVER_SIDE_TOOLS = new Set([
+    'get_roblox_processes',
+    'launch_roblox',
+    'open_game',
+    'capture_roblox_screenshot',
+    'get_roblox_versions',
+]);
+class McpHandler {
+    /**
+     * @param queue - The task queue manager
+     * @param tools - Tool definitions registry
+     * @param sessions - Session manager
+     * @param processManager - Process manager module
+     */
+    constructor(queue, tools, sessions, processManager) {
+        this.queue = queue;
+        this.tools = tools;
+        this.sessions = sessions;
+        this.proc = processManager;
+        this.serverInfo = {
+            name: 'roblox-mcp-difz-server',
+            version: '1.0.0',
+            description: 'Roblox MCP — full game control, reverse engineering, ' +
+                'and exploitation framework via Model Context Protocol.',
+        };
+        this.initialized = false;
+    }
+    async handleMessage(message) {
+        const { method, params } = message;
+        if (!method) {
+            return { error: { code: -32600, message: 'Invalid Request: method is required' } };
+        }
+        switch (method) {
+            case 'initialize':
+                return this._handleInitialize(params);
+            case 'shutdown':
+                return this._handleShutdown();
+            case 'notifications/initialized':
+                return { result: { acknowledged: true } };
+            case 'tools/list':
+                return this._handleToolsList();
+            case 'tools/call':
+                return await this._handleToolsCall(params);
+            case 'resources/list':
+                return this._handleResourcesList();
+            case 'resources/read':
+                return await this._handleResourcesRead(params);
+            case 'prompts/list':
+                return this._handlePromptsList();
+            case 'ping':
+                return { result: { status: 'pong', timestamp: Date.now(), stats: this.queue.getStats() } };
+            case 'mcp/setup':
+                return this._handleSetup();
+            default:
+                return { error: { code: -32601, message: `Method not found: ${method}` } };
+        }
+    }
+    _handleInitialize(_params) {
+        this.initialized = true;
+        return {
+            result: {
+                protocolVersion: '2024-11-05',
+                capabilities: {
+                    tools: { listChanged: false },
+                    resources: { listChanged: false, subscribe: false },
+                    prompts: {},
+                },
+                serverInfo: this.serverInfo,
+            },
+        };
+    }
+    _handleShutdown() {
+        this.initialized = false;
+        return { result: { success: true, message: 'Server shutting down' } };
+    }
+    _handleToolsList() {
+        return { result: { tools: this.tools.getTools() } };
+    }
+    async _handleToolsCall(params) {
+        const { name, arguments: args } = (params || {});
+        if (!name) {
+            return { error: { code: -32602, message: 'Tool name is required' } };
+        }
+        const tool = this.tools.getTool(name);
+        if (!tool) {
+            return { error: { code: -32602, message: `Unknown tool: ${name}` } };
+        }
+        try {
+            // Server-side tools run on Node directly
+            if (SERVER_SIDE_TOOLS.has(name)) {
+                const result = this._runServerTool(name, args || {});
+                return {
+                    result: {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        meta: { tool: name, execution: 'server' },
+                    },
+                };
+            }
+            // Executor tools — queue for executor, with optional workerId targeting
+            const startTime = Date.now();
+            const workerId = (args && args.pid) ? String(args.pid) : undefined;
+            const result = await this.queue.submitTask(name, args || {}, { workerId });
+            const elapsed = Date.now() - startTime;
+            return {
+                result: {
+                    content: [{
+                            type: 'text',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                    meta: { executionTimeMs: elapsed, tool: name },
+                },
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                result: {
+                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: errorMessage }) }],
+                    isError: true,
+                    meta: { tool: name, error: errorMessage },
+                },
+            };
+        }
+    }
+    _runServerTool(name, args) {
+        switch (name) {
+            case 'get_roblox_processes':
+                return { success: true, processes: this.proc.listRobloxProcesses(), count: this.sessions.activeCount };
+            case 'launch_roblox':
+                return this.proc.launchRoblox(args.path || null);
+            case 'open_game':
+                return this.proc.openGame(args.place_id, {
+                    jobId: args.job_id,
+                    privateServerLinkCode: args.private_server_link_code,
+                    browserTrackerId: args.browser_tracker_id,
+                    launchTime: args.launch_time,
+                    launchMode: args.launch_mode,
+                    authTicket: args.auth_ticket,
+                    experienceId: args.experience_id,
+                });
+            case 'capture_roblox_screenshot':
+                return this.proc.captureRobloxWindow(args.pid || null);
+            case 'get_roblox_versions':
+                return this._getRobloxVersions();
+            default:
+                return { success: false, error: `Unknown server tool: ${name}` };
+        }
+    }
+    _getRobloxVersions() {
+        const fs = require('fs');
+        const path = require('path');
+        const versions = [];
+        const candidates = [
+            process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, 'Roblox', 'Versions') : '',
+            'C:\\Program Files (x86)\\Roblox\\Versions',
+            'C:\\Program Files\\Roblox\\Versions',
+        ];
+        for (const dir of candidates) {
+            if (!dir || !fs.existsSync(dir))
+                continue;
+            try {
+                const entries = fs.readdirSync(dir).filter((v) => v.startsWith('version-')).sort().reverse();
+                for (const ver of entries) {
+                    const launcher = path.join(dir, ver, 'RobloxPlayerLauncher.exe');
+                    const player = path.join(dir, ver, 'RobloxPlayerBeta.exe');
+                    versions.push({
+                        version: ver.replace('version-', ''),
+                        path: dir + '/' + ver,
+                        hasPlayerLauncher: fs.existsSync(launcher),
+                        hasPlayerBeta: fs.existsSync(player),
+                    });
+                }
+            }
+            catch {
+                // ignore inaccessible directories
+            }
+        }
+        return { success: true, versions };
+    }
+    _handleResourcesList() {
+        return {
+            result: {
+                resources: [
+                    { uri: 'mcp://roblox/game/metadata', name: 'Game Metadata', description: 'Current game session metadata', mimeType: 'application/json' },
+                    { uri: 'mcp://roblox/game/players', name: 'Active Players', description: 'Real-time player data', mimeType: 'application/json' },
+                    { uri: 'mcp://roblox/game/remotes', name: 'Remote Events & Functions', description: 'All detected remotes', mimeType: 'application/json' },
+                    { uri: 'mcp://roblox/game/workspace', name: 'Workspace Objects', description: '3D object tree', mimeType: 'application/json' },
+                    { uri: 'mcp://roblox/game/console', name: 'Console Logs', description: 'Recent LogService output', mimeType: 'application/json' },
+                ],
+            },
+        };
+    }
+    async _handleResourcesRead(params) {
+        const { uri } = (params || {});
+        if (!uri)
+            return { error: { code: -32602, message: 'Resource URI is required' } };
+        const resourceMap = {
+            'mcp://roblox/game/metadata': 'get_game_metadata',
+            'mcp://roblox/game/players': 'dump_workspace_players',
+            'mcp://roblox/game/remotes': 'dump_remote_events',
+            'mcp://roblox/game/workspace': 'get_workspace_objects',
+            'mcp://roblox/game/console': 'get_console_logs',
+        };
+        const toolName = resourceMap[uri];
+        if (!toolName)
+            return { error: { code: -32602, message: `Unknown resource: ${uri}` } };
+        try {
+            const result = await this.queue.submitTask(toolName, {});
+            return {
+                result: {
+                    contents: [{
+                            uri,
+                            mimeType: 'application/json',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                },
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return { error: { code: -32603, message: `Failed to read resource: ${errorMessage}` } };
+        }
+    }
+    _handlePromptsList() {
+        return {
+            result: {
+                prompts: [
+                    { name: 'analyze_game', description: 'Dumps game metadata, remotes, and player data in one shot.', arguments: [] },
+                    { name: 'find_exploit_vector', description: 'Scan remotes and workspace to find exploit entry points.', arguments: [] },
+                ],
+            },
+        };
+    }
+    _handleSetup() {
+        return {
+            result: {
+                config: {
+                    type: 'url',
+                    url: 'http://localhost:28429/mcp',
+                    name: 'Roblox MCP Difz',
+                    description: 'Full game control & exploitation framework',
+                },
+            },
+        };
+    }
+}
+module.exports = { McpHandler };

package/dist/process-manager.d.ts

@@ -0,0 +1,12 @@
+/**
+ * process-manager.ts
+ *
+ * Roblox process management — runs on Node side, not via executor queue.
+ *
+ * Provides:
+ *   listRobloxProcesses()   — scan OS for RobloxPlayerBeta processes
+ *   launchRoblox(path)      — spawn RobloxPlayerLauncher.exe
+ *   openGame(placeId, opts) — open game via roblox-player protocol with full join URL
+ *   captureRobloxWindow(pid) — capture screenshot of a Roblox process window
+ */
+export {};