@adiholick/nvstudio-mcp 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# nvstudio-mcp 🚀
+
+**nvstudio-mcp** adalah jembatan pintar (*Model Context Protocol Bridge*) yang menghubungkan Asisten AI Anda (seperti Antigravity IDE, Cursor, Claude Desktop, atau Windsurf) secara langsung ke dalam **Roblox Studio**. Dengan plugin ini, AI Anda dapat membaca, mengedit script, men-generate terrain, dan berinteraksi dengan API Roblox Studio layaknya seorang asisten *Co-Pilot* sejati.
+
+Sistem ini didesain menggunakan **Hybrid Architecture** yang memisahkan logika Engine (*Studio Plugin*) dan aturan anti-halusinasi (*Agent Plugin*).
+
+---
+
+## 📥 Instalasi
+
+Langkah instalasinya **sangat gampang!**
+
+### 1. Jalankan Installer (Otomatis)
+
+Pilih perintah sesuai terminal yang Anda gunakan:
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/Adiholick/nvstudio-mcp/main/install.ps1 | iex
+```
+
+**macOS / Linux / Git Bash:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/Adiholick/nvstudio-mcp/main/install.sh | bash
+```
+
+
+**Installer ini akan secara otomatis melakukan hal berikut:**
+- Memasang dependensi Node.js dan melakukan kompilasi TypeScript (*Bridge Server*).
+- Menyalin file plugin `nvstudio_mcp.rbxmx` ke dalam sistem Plugin Roblox Studio di OS Anda (Windows/macOS/WSL) secara otomatis.
+- Mengintegrasikan *AI Agent Skills* langsung ke **Antigravity IDE** (`~/.gemini/config/plugins/nvstudio-mcp`).
+- Melakukan auto-konfigurasi JSON jika Anda menggunakan **Cursor Editor**.
+
+### 2. Mengaktifkan Izin di Roblox Studio
+1. Buka proyek game Anda di Roblox Studio.
+2. Di pojok kiri atas, buka **Home** -> **Game Settings** -> **Security**.
+3. Centang (aktifkan) opsi **`Allow HTTP Requests`** agar plugin dapat berkomunikasi dengan AI.
+
+---
+
+## 🔌 Cara Menggunakan (Untuk AI Lain)
+
+Jika Anda menggunakan AI Client lain (misalnya: **Claude Desktop** atau klien yang tidak dikonfigurasi otomatis), Anda dapat menambahkan `nvstudio-mcp` secara manual ke konfigurasi `mcp.json` Anda.
+
+Salin konfigurasi ini:
+```json
+{
+  "mcpServers": {
+    "nvstudio-mcp": {
+      "command": "node",
+      "args": [
+        "C:/Path/Ke/Folder/nvstudio-mcp/dist/index.js"
+      ]
+    }
+  }
+}
+```
+*(Ingat untuk mengganti path `args` di atas dengan direktori instalasi aktual Anda, biasanya berada di `~/.nvstudio-mcp/dist/index.js`).*
+
+---
+
+## 🗑️ Cara Uninstall (Mencopot Pemasangan)
+
+Jika Anda ingin berhenti menggunakan `nvstudio-mcp`, Anda dapat membersihkannya dari sistem Anda secara menyeluruh dengan 4 langkah berikut:
+
+### 1. Hapus Plugin dari Roblox Studio
+Hapus file plugin dari folder lokal Roblox Anda.
+- **Windows:** Buka folder `%LOCALAPPDATA%\Roblox\Plugins` (atau `AppData\Local\Roblox\Plugins`) dan hapus file `nvstudio_mcp.rbxmx` (atau `nvstudio_mcp.rbxm`).
+- **macOS:** Buka folder `~/Documents/ROBLOX/Plugins` dan hapus file `nvstudio_mcp.rbxmx` (atau `nvstudio_mcp.rbxm`).
+
+### 2. Hapus Agen dari Antigravity (Jika Menggunakan AGY)
+Hapus *bundle* keterampilan *anti-halusinasi* dari memori AI Anda:
+```bash
+rm -rf ~/.gemini/config/plugins/nvstudio-mcp
+```
+*(Untuk pengguna Windows PowerShell, Anda bisa menghapus folder `C:\Users\NamaAnda\.gemini\config\plugins\nvstudio-mcp` secara manual).*
+
+### 3. Hapus File Instalasi Node.js
+Installer `install.sh` sebelumnya mengkloning repositori dan menginstal Node.js di dalam direktori *Home* Anda (secara bawaan di `~/.nvstudio-mcp`). Hapus direktori tersebut:
+```bash
+rm -rf ~/.nvstudio-mcp
+```
+
+### 4. Hapus Konfigurasi dari Editor AI Anda
+Jika Anda memasukkan konfigurasi MCP secara otomatis ke Cursor atau secara manual ke Claude Desktop, buka file pengaturan `mcp.json` tersebut dan **hapus blok `"nvstudio-mcp"`** dari dalam objek `mcpServers`.
+
+---
+
+**Selamat Menciptakan Game Impian Anda dengan AI! 🎮🤖**

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const roblox_bridge_1 = require("./roblox-bridge");
+const task_queue_1 = require("./task-queue");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const HISTORY_DIR = path_1.default.join(process.cwd(), '.history');
+if (!fs_1.default.existsSync(HISTORY_DIR)) {
+    fs_1.default.mkdirSync(HISTORY_DIR, { recursive: true });
+}
+function backupScript(target, code) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const safeTargetName = target.replace(/[^a-zA-Z0-9]/g, '_');
+    const fileName = `${safeTargetName}_${timestamp}.luau`;
+    fs_1.default.writeFileSync(path_1.default.join(HISTORY_DIR, fileName), code);
+}
+// 1. Impor dan jalankan server Express lokal di port 3055
+(0, roblox_bridge_1.startBridgeServer)(3055);
+// 2. Inisialisasi server MCP
+const server = new index_js_1.Server({
+    name: "nvstudio-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// 3 & 4. Daftarkan tool call_mcp_tool dan definisikan schema parameternya
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "call_mcp_tool",
+                description: "ALAT MUTLAK UNTUK ROBLOX. DILARANG KERAS menggunakan PowerShell atau skrip bypass (fetch_mcp_source.js). WAJIB memanggil 'get_children' terlebih dahulu sebelum 'get_script_source' untuk memverifikasi tipe instance agar tidak terjadi error teks kosong.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        command: {
+                            type: "string",
+                            description: "Perintah yang akan dieksekusi (contoh: 'get_children', 'get_script_source', 'update_script_source', 'rollback_script', 'get_logs').",
+                        },
+                        target: {
+                            type: "string",
+                            description: "Path absolut dari objek target di Roblox Studio (contoh: 'Workspace.Map.Script' atau 'ServerScriptService.MainModule').",
+                        },
+                        data: {
+                            type: "string",
+                            description: "Data tambahan opsional, misalnya isi source code baru saat menjalankan perintah 'update_script_source'.",
+                        },
+                    },
+                    required: ["command", "target"],
+                },
+            },
+        ],
+    };
+});
+// 5. Handler untuk menangani pemanggilan call_mcp_tool
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "call_mcp_tool") {
+        throw new Error(`Tool tidak dikenali: ${request.params.name}`);
+    }
+    const args = request.params.arguments;
+    const { command, target, data } = args;
+    if (!command || !target) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "error",
+                        error: "Parameter 'command' dan 'target' wajib diisi.",
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // 6. 🔴 GUARDRAIL MUTLAK: Cegah tebakan path buta
+    if (command === "get_script_source") {
+        const genericTargets = ["Workspace", "ServerScriptService", "ReplicatedStorage", "StarterGui", "StarterPack", "game"];
+        if (genericTargets.includes(target) || !target.includes(".")) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "🔴 SERVER GUARDRAIL BLOCKED: DILARANG mengekstrak kode secara buta dari direktori utama atau target yang tidak spesifik. Anda WAJIB memanggil perintah 'get_children' pada '" + target + "' terlebih dahulu untuk memverifikasi nama dan ClassName (Pastikan target adalah LuaSourceContainer)."
+                    }],
+                isError: true
+            };
+        }
+    }
+    // 7. Teruskan ke antrean dan kembalikan hasilnya sebagai string JSON
+    try {
+        if (command === "update_script_source" && data) {
+            backupScript(target, String(data));
+        }
+        const result = await (0, task_queue_1.addTaskToQueue)(command, target, data);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "error",
+                        error: err?.message || String(err),
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// 8. Jalankan koneksi MCP menggunakan StdioServerTransport
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("[nvstudio-mcp] MCP Server aktif melalui StdioServerTransport.");
+    // Tangani penutupan koneksi (misal IDE ditutup) agar server ikut mati
+    process.stdin.on('close', () => {
+        console.error("[nvstudio-mcp] Koneksi stdin ditutup oleh IDE. Mematikan server...");
+        process.exit(0);
+    });
+}
+main().catch((err) => {
+    console.error("[nvstudio-mcp] Gagal menjalankan MCP server:", err);
+    process.exit(1);
+});

package/dist/roblox-bridge.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startBridgeServer = startBridgeServer;
+const express_1 = __importDefault(require("express"));
+const http_1 = require("http");
+const socket_io_1 = require("socket.io");
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const task_queue_1 = require("./task-queue");
+function startBridgeServer(port = 3055) {
+    const app = (0, express_1.default)();
+    const httpServer = (0, http_1.createServer)(app);
+    const io = new socket_io_1.Server(httpServer, { cors: { origin: "*" } });
+    // FIX: Menaikkan limit ke 50mb agar file .Source (Lua) yang besar tidak melempar error 413 Payload Too Large
+    app.use(express_1.default.json({ limit: '50mb' }));
+    app.use(express_1.default.static(path_1.default.join(__dirname, '../public')));
+    let dashboardOpened = false;
+    // Endpoint Studio Polling
+    app.get('/api/tasks', (req, res) => {
+        if (!dashboardOpened) {
+            dashboardOpened = true;
+            const startCmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+            (0, child_process_1.exec)(`${startCmd} http://localhost:${port}`);
+            console.error(`[Bridge] Pertama kali terhubung dengan Studio! Membuka Dashboard...`);
+        }
+        if (task_queue_1.taskQueue.length > 0) {
+            const task = task_queue_1.taskQueue.shift();
+            io.emit('log', `[AI Task] Mengirim perintah '${task?.command}' ke Studio.`);
+            res.json(task);
+        }
+        else {
+            res.json({ id: null });
+        }
+    });
+    // Endpoint Studio Response
+    app.post('/api/response', (req, res) => {
+        const { id, status, result, error } = req.body;
+        io.emit('log', `[Studio Response] Status: ${status}`);
+        if (error)
+            io.emit('log', `[Error] ${error}`);
+        // Memanggil fungsi resolve secara sinkron (menghindari promise import circular palsu)
+        (0, task_queue_1.resolvePendingTask)(id, status, result, error);
+        res.json({ message: "Response diterima" });
+    });
+    httpServer.listen(port, () => {
+        console.error(`[Bridge] Dashboard visual & server aktif di http://localhost:${port}`);
+    });
+}

package/dist/task-queue.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pendingTasks = exports.taskQueue = void 0;
+exports.addTaskToQueue = addTaskToQueue;
+exports.resolvePendingTask = resolvePendingTask;
+const uuid_1 = require("uuid");
+// 1. Array untuk menampung antrean tugas (task queue)
+exports.taskQueue = [];
+// 2. Map untuk menyimpan Promise dari tugas yang sedang menunggu (pending tasks)
+exports.pendingTasks = new Map();
+/**
+ * Menambahkan task baru ke antrean dan mengembalikan Promise
+ * yang tertahan sampai ada response atau timeout 30 detik.
+ */
+function addTaskToQueue(command, target, data) {
+    const id = (0, uuid_1.v4)();
+    const task = { id, command, target, data };
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            if (exports.pendingTasks.has(id)) {
+                exports.pendingTasks.delete(id);
+                reject(new Error("Timeout: Roblox Studio tidak merespons"));
+            }
+        }, 30000);
+        exports.pendingTasks.set(id, { resolve, reject, timer });
+        exports.taskQueue.push(task);
+    });
+}
+/**
+ * Menyelesaikan pending task berdasarkan id dan status respons dari Roblox Studio.
+ */
+function resolvePendingTask(id, status, result, error) {
+    const pending = exports.pendingTasks.get(id);
+    if (!pending) {
+        return false;
+    }
+    clearTimeout(pending.timer);
+    exports.pendingTasks.delete(id);
+    if (status === "success") {
+        pending.resolve(result);
+    }
+    else {
+        pending.reject(new Error(error || "Terjadi kesalahan pada Roblox Studio"));
+    }
+    return true;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@adiholick/nvstudio-mcp",
+  "version": "1.0.0",
+  "description": "Local Bridge Server MCP for Roblox Studio",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "public"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "roblox",
+    "studio"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "express": "^5.2.1",
+    "socket.io": "^4.8.3",
+    "uuid": "^14.0.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.4.1",
+    "@types/socket.io": "^3.0.1",
+    "@types/uuid": "^10.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^7.0.2"
+  }
+}

package/public/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>nvstudio-mcp | Live Dashboard</title>
+    <style>
+        body { font-family: 'Consolas', monospace; background-color: #0f172a; color: #38bdf8; margin: 0; padding: 20px; }
+        h1 { color: #f8fafc; font-size: 1.5rem; border-bottom: 1px solid #334155; padding-bottom: 10px; }
+        #log-container { background-color: #1e293b; padding: 15px; border-radius: 8px; height: 75vh; overflow-y: auto; box-shadow: 0 4px 6px rgba(0,0,0,0.3); }
+        .log-entry { margin-bottom: 8px; border-bottom: 1px solid #334155; padding-bottom: 4px; }
+        .log-time { color: #94a3b8; font-size: 0.85em; margin-right: 10px; }
+    </style>
+</head>
+<body>
+    <h1>nvstudio-mcp : Activity Dashboard (Port 3055)</h1>
+    <div id="log-container"></div>
+
+    <script src="/socket.io/socket.io.js"></script>
+    <script>
+        const socket = io();
+        const container = document.getElementById('log-container');
+
+        socket.on('log', (msg) => {
+            const el = document.createElement('div');
+            el.className = 'log-entry';
+            const time = new Date().toLocaleTimeString();
+            el.innerHTML = `<span class="log-time">[${time}]</span>${msg}`;
+            container.appendChild(el);
+            container.scrollTop = container.scrollHeight; // Auto-scroll
+        });
+    </script>
+</body>
+</html>