convez.ai
MCP ServerProdutividadeAvançado
0neShot101

rbxdev-ls

0neShot101/rbxdev-ls

Language server Luau para Roblox com type checking e tooling live-game no editor

Ver no GitHub
BomPluginScore · de 0 a 100

Language server e extensão VS Code completa para desenvolvimento em Roblox com Luau, oferecendo type checking rigoroso, completions inteligentes baseadas na API oficial, e ferramentas live-game (explorador de instâncias, property inspector, remote spy) integradas ao editor. Inclui servidor MCP para assistentes de IA como Claude.

Instalação

$npx convez-ai 0neShot101/rbxdev-ls

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
20
Forks
3
Acompanhando
0
Saúde
57%
Último commit
há 4 dias
Versão
v0.5.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Desenvolvimento de jogos em Roblox com validação de tipos em tempo real
  • Debugging e inspeção de game state sem sair do editor
  • Espionagem de RemoteEvent/RemoteFunction para análise de comunicação de rede
  • Integração de assistentes de IA (Claude via MCP) para análise e geração de código Luau

Veredito

Solução madura e abrangente para o ecossistema Roblox, dominando o nicho de desenvolvimento Luau com recursos que vão além do sintático. O suporte MCP e bridge com Studio elevam a produtividade significativamente em projetos médios e grandes.

README

A tradução para o português deste README ainda está na fila.


Overview

rbxdev-ls is a monorepo that ships a full-featured Luau language server, a VS Code extension, a standalone MCP server, and a Roblox Studio bridge plugin. The workspaces are server (parser, type checker, 30+ LSP handlers, and the executor bridge protocol), vscode (game tree explorer, properties panel, remote spy, and AI tool registration), mcp (the @oneshot101/rbxdev-mcp package for Claude, Cursor, Windsurf, and other MCP-compatible assistants), and studio-plugin (a Luau plugin built with Rojo that bridges Studio to the language server).

Most Luau editors offer syntax highlighting and maybe basic completions. rbxdev-ls goes further by loading the official Roblox API dump for type-aware completions and hover docs, running a real type checker that respects --!strict / --!nonstrict / --!nocheck annotations, and layering live-game tooling on top — you can browse the instance hierarchy, edit properties, execute code, and spy on remote calls without leaving your editor. The MCP server extends the same bridge to AI assistants so they can read game state and run code as part of a conversation.

Features

  • Full Roblox API completions and hover docs — loaded from the official API dump, including inherited members, deprecated tags, and documentation strings.
  • Luau type checking — three strictness modes (--!strict, --!nonstrict, --!nocheck) with diagnostics surfaced inline in the editor.
  • 30+ LSP handlers — completion, hover, signature help, go-to-definition, find references, rename, document symbols, semantic tokens, code actions, formatting, inlay hints, call hierarchy, folding, selection range, type hierarchy, code lens, document links, color picker, and linked editing.
  • Rojo and sourcemap support — resolves cross-file require() calls using default.project.json and sourcemap.json so go-to-definition and auto-import work across a Rojo project.
  • Game Tree explorer — a sidebar panel that renders the live instance hierarchy from a connected Roblox game, with expand/collapse, property inspection, and context-menu actions.
  • Remote Spy — captures RemoteEvent and RemoteFunction traffic in real time, with filtering, block lists, and quick-copy to reproduce calls.
  • In-editor code execution — run the current file, a selection, or a bundled multi-file payload directly inside the game.
  • MCP server for AI assistants — 19 tools (execute code, browse the game tree, read/write properties, manage instances, read console output, and more) exposed over the Model Context Protocol.
  • GitHub Copilot integration — the same 19 tools are registered with VS Code's Language Model API so Copilot can interact with the game without a separate MCP client.
  • Instance manipulation — create, clone, delete, reparent, and teleport to instances from the editor or through AI tools.

Table of Contents

Quick Start

Install the extension from the VS Code Marketplace or Open VSX, open a folder containing .lua or .luau files, and start coding. The language server activates automatically and provides completions, type checking, and hover docs with no additional setup.

--!strict

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local character = localPlayer.Character or localPlayer.CharacterAdded:Wait()

Type checking, completions, and hover documentation appear immediately. For live-game features (game tree, remote spy, code execution), see Executor Bridge Setup.

How It Works

When VS Code activates the extension, it spawns the language server as a Node.js child process communicating over JSON-RPC (the standard LSP transport). The server parses every open .lua and .luau file into an AST, runs a type checker against the Roblox API dump and any workspace definitions, and responds to editor requests through 30+ registered LSP handlers. Rojo project files and sourcemap.json are read at startup and watched for changes so that cross-file require() resolution stays current without manual reloads.

Live-game features use a separate WebSocket channel. The extension starts a WebSocket server on port 21324 (configurable) and waits for an executor bridge client to connect from inside a running Roblox game. Once connected, the extension can send commands (execute code, request the instance tree, read properties) and receive events (game tree snapshots, remote spy captures, runtime errors, console logs). The MCP server can either own this WebSocket server directly or connect as a proxy client through the extension's bridge when both are running simultaneously.

ComponentTransportDirection
Editor ↔ Language ServerJSON-RPC over stdioBidirectional
Extension ↔ ExecutorWebSocket on port 21324Bidirectional
MCP Client ↔ MCP Serverstdio (Model Context Protocol)Bidirectional
MCP Server ↔ ExtensionWebSocket proxyBidirectional (when extension is running)
Studio Plugin ↔ ExtensionWebSocket on port 21324Bidirectional

Architecture

graph TD
    subgraph Editor["VS Code"]
        EXT["Extension Client"]
        GT["Game Tree Panel"]
        PROPS["Properties Panel"]
        RSPY["Remote Spy Panel"]
        COPILOT["Copilot Tools"]
    end

    subgraph Server["Language Server (Node.js)"]
        LSP["LSP Handlers"]
        PARSER["Luau Parser"]
        TC["Type Checker"]
        DEFS["API Definitions"]
        WS["Workspace / Rojo"]
    end

    subgraph Bridge["Executor Bridge (WebSocket :21324)"]
        BRIDGE["Bridge Server"]
    end

    subgraph MCP["MCP Server"]
        MCPS["@oneshot101/rbxdev-mcp"]
    end

    subgraph Game["Roblox Game"]
        EXEC["Executor Client"]
        STUDIO["Studio Plugin"]
    end

    EXT <-->|JSON-RPC| LSP
    LSP --> PARSER
    LSP --> TC
    TC --> DEFS
    LSP --> WS
    EXT <--> BRIDGE
    GT <--> BRIDGE
    PROPS <--> BRIDGE
    RSPY <--> BRIDGE
    COPILOT <--> BRIDGE
    BRIDGE <-->|WebSocket| EXEC
    BRIDGE <-->|WebSocket| STUDIO
    MCPS <-->|Proxy or Direct| BRIDGE

Installation

The simplest path is installing the pre-built extension from a marketplace. For contributors who want to build from source, see Development.

VS Code Extension

Install from either marketplace:

MarketplaceLink
VS Code Marketplacerbxdev.rbxdev-ls
Open VSXrbxdev/rbxdev-ls

Alternatively, search for rbxdev-ls in the VS Code extensions panel and install directly.

MCP Server (Standalone)

If you want AI assistants to interact with Roblox games without VS Code, install the MCP server globally or run it via npx. See MCP Server for full setup instructions.

Usage

Language Server

The language server activates automatically for any workspace containing .lua or .luau files. It provides the full range of editor features without any configuration:

  • Type game:GetService(" to see a completion list of all Roblox services.
  • Hover over any Roblox API member to see its type signature and documentation.
  • Use Ctrl+Click (or F12) to jump to the definition of a local variable, function, or required module.
  • Rename a symbol with F2 and all references update across the workspace.
  • Type errors appear as diagnostics in the Problems panel, respecting the --!strict / --!nonstrict / --!nocheck annotation at the top of each file.

Live-Game Features

After connecting an executor bridge (see Executor Bridge Setup), the sidebar panels become active:

  • Game Tree — expand services and instances to browse the hierarchy. Right-click for actions like teleport, clone, delete, or copy the Luau path.
  • Properties — select an instance in the game tree to view and edit its properties. Supports all standard Roblox types (Vector3, CFrame, Color3, UDim2, and more).
  • Remote Spy — toggle the spy to capture all RemoteEvent and RemoteFunction traffic. Filter by name, set up block lists, and copy calls as runnable Luau code.

Code Execution

Three execution modes are available through keyboard shortcuts or the command palette:

ModeShortcutBehavior
Execute fileCtrl+Shift+ESends the entire active file to the executor
Execute selectionCtrl+Shift+Alt+ESends only the selected text
Bundle and executeCtrl+Alt+EResolves require() calls, bundles into a single payload, and executes

Runtime errors and print/warn/error output appear in the VS Code output channel.

Executor Bridge Setup

The executor bridge is a Luau script that runs inside a Roblox game and opens a WebSocket connection back to the language server. To enable live-game features, paste this into your executor's auto-execute:

loadstring(game:HttpGetAsync('https://raw.githubusercontent.com/0neShot101/rbxdev-ls/main/scripts/executor-bridge.lua'))()

The bridge connects to ws://127.0.0.1:21324 by default. If you need to customize the connection, pass a config table:

loadstring(game:HttpGetAsync('https://raw.githubusercontent.com/0neShot101/rbxdev-ls/main/scripts/executor-bridge.lua'))({
    host = 'ws://127.0.0.1:21324';
    reconnectDelay = 5;
    firstConnectDepth = 999;
    updateTreeDepth = 2;
    expandedTreeDepth = 2;
})
ParameterDefaultPurpose
hostws://127.0.0.1:21324WebSocket URL the bridge connects to
reconnectDelay5Seconds between reconnection attempts after a disconnect
firstConnectDepth999How many levels deep to scan the instance tree on first connection
updateTreeDepth2Depth of tree updates sent when instances change
expandedTreeDepth2Depth of subtree sent when expanding a node in the game tree panel

MCP Server

The @oneshot101/rbxdev-mcp package exposes 19 tools over the Model Context Protocol, letting Claude, Cursor, Windsurf, and other MCP-compatible AI assistants interact with a live Roblox game. It requires Node.js 18+ and a running executor bridge connection.

Setup

The package is published to the public npm registry under the @oneshot101 scope.

Then add this block to your MCP client configuration:

{
  "mcpServers": {
    "rbxdev-roblox": {
      "command": "npx",
      "args": ["-y", "@oneshot101/rbxdev-mcp"]
    }
  }
}

The config file location depends on your tool:

ToolConfig location
Claude Code~/.claude/mcp_config.json
Claude DesktopSettings → MCP Servers
Cursor.cursor/mcp.json in your project
WindsurfCascade → MCP → Add Server

Proxy Mode

If the rbxdev-ls VS Code extension is already running (it owns the WebSocket server on port 21324), the MCP server automatically connects as a proxy client through the extension's bridge. Both tools share the same executor connection with no port conflicts. If the extension is not running, the MCP server starts its own WebSocket server and connects to the executor directly.

Custom Port

To use a non-default port, set the RBXDEV_BRIDGE_PORT environment variable:

{
  "mcpServers": {
    "rbxdev-roblox": {
      "command": "npx",
      "args": ["-y", "@oneshot101/rbxdev-mcp"],
      "env": {
        "RBXDEV_BRIDGE_PORT": "21325"
      }
    }
  }
}
ToolDescription
get_bridge_statusCheck whether the bridge is running and an executor is connected
execute_codeRun Luau code in the game with full Roblox API access
get_game_treeBrowse the game hierarchy (services, instances, children)
get_propertiesRead property values from any instance
set_propertySet properties on instances (supports Vector3, Color3, UDim2, and more)
get_childrenList children of a specific instance
create_instanceCreate new instances in the game
clone_instanceClone existing instances
delete_instanceRemove instances from the game
reparent_instanceMove instances to a new parent
teleport_playerTeleport the local player to an instance's position
get_script_sourceDecompile and read script source code
get_console_outputRead recent print/warn/error output from the game
refresh_game_treeRequest a fresh snapshot of the game tree
get_remote_callsView captured RemoteEvent/RemoteFunction calls
set_remote_spy_enabledToggle the remote spy on or off
set_remote_spy_block_listBlock selected remotes from firing to the server
set_script_sourceUpdate script source when connected through Studio
save_instanceSave the game or a specific instance to a file

The server also exposes three MCP resources for passive reading:

Resource URIContent
rbxdev://bridge/statusConnection status as JSON
rbxdev://game/treeFull game tree rendered as text
rbxdev://console/logsRecent console output

Configuration

All settings are prefixed with rbxdev-ls. and can be set in VS Code's settings.json or through the Settings UI.

SettingDefaultPurpose
rbxdev-ls.typeCheckModenonstrictControls the default type checking strictness for files without a --! annotation at the top. Accepts strict, nonstrict, or nocheck
rbxdev-ls.enableSuncApifalseLoads Sunc executor API definitions into the type environment, providing completions and type checking for Sunc-specific globals
rbxdev-ls.executorBridge.port21324The TCP port the WebSocket bridge server listens on for executor and Studio plugin connections
rbxdev-ls.mcp.enabledtrueEnables the built-in MCP server integration that registers language model tools with VS Code's Copilot API
rbxdev-ls.bundler.path""Path to a custom luau-bundle binary used for the bundle-and-execute command. When empty, the built-in bundler is used
rbxdev-ls.debugLogsfalseEnables verbose logging in the extension output channel for troubleshooting connection and protocol issues

Keyboard Shortcuts

ShortcutCommand
Ctrl+Shift+EExecute the current file in-game
Ctrl+Shift+Alt+EExecute the selected text in-game
Ctrl+Alt+EBundle all required modules and execute
Ctrl+Shift+RCopy the last Remote Spy call to clipboard
Ctrl+Shift+Alt+RInsert the last Remote Spy call at the cursor
Ctrl+Alt+CQuick copy (copies the last Remote Spy call as a Luau snippet)

Project Structure

rbxdev-ls/
├── packages/
│   ├── server/                    Language server package (rbxdev-server)
│   │   ├── src/
│   │   │   ├── core/              LSP server bootstrap, connection, and capability registration
│   │   │   ├── lsp/
│   │   │   │   └── handlers/      30+ LSP request handlers (completion, hover, rename, etc.)
│   │   │   ├── parser/            Luau lexer, parser, and doc-comment extraction
│   │   │   ├── typings/           Type system, type checker, and subtyping logic
│   │   │   ├── definitions/       Roblox API, stdlib, executor, and third-party type definitions
│   │   │   ├── workspace/         Module resolution, Rojo integration, and sourcemap support
│   │   │   ├── executor/          Bridge protocol, WebSocket server, and proxy handling
│   │   │   └── utils/             Shared utility functions
│   │   ├── tests/                 29 test suites (984 tests)
│   │   └── data/                  Roblox API dump (roblox-api.json)
│   ├── vscode/                    VS Code extension client
│   │   └── src/
│   │       ├── extension.ts       Extension activation and command registration
│   │       ├── gameTreeProvider.ts Game tree sidebar data provider
│   │       ├── propertiesProvider.ts Properties panel data provider
│   │       ├── remoteSpyWebview.ts Remote spy webview panel
│   │       └── mcpTools.ts        19 language model tools for Copilot integration
│   ├── mcp/                       Standalone MCP server (@oneshot101/rbxdev-mcp)
│   │   └── src/
│   │       ├── index.ts           Entry point (stdio transport)
│   │       └── server.ts          Tool and resource registration
│   └── studio-plugin/             Roblox Studio bridge plugin (Luau, built with Rojo)
│       ├── default.project.json   Rojo project file
│       └── src/                   Plugin source
├── scripts/                       Build orchestration and maintenance
│   ├── build-vsix.ts              Packages the VS Code extension as a .vsix
│   ├── build-studio-plugin.ts     Builds the Studio plugin via Rojo
│   ├── fetch-roblox-api.ts        Downloads the latest Roblox API dump
│   └── executor-bridge.lua        Bridge script loaded by executors at runtime
└── package.json                   Workspace root (bun workspaces)

Development

Prerequisites

DependencyMinimum VersionInstall
Bun≥ 1.0.0curl -fsSL https://bun.sh/install | bash
Node.js≥ 18Required for MCP package builds and runtime
RojoLatestOnly needed for build:studio (optional)

Setup

git clone https://github.com/0neShot101/rbxdev-ls && cd rbxdev-ls
bun install

All dependencies across every workspace are installed by the single bun install at the repo root.

Scripts

ScriptDescription
bun run buildBuild the language server (compiles packages/server with Bun targeting Node.js)
bun run build:mcpBuild the standalone MCP server
bun run build:allBuild the language server and MCP server in sequence
bun run testRun the full test suite (984 tests across 29 files)
bun run type-checkRun the TypeScript compiler in check-only mode against the server package
bun run lint:checkRun ESLint without auto-fixing
bun run lintRun ESLint with auto-fix
bun run format:checkCheck formatting with Prettier
bun run formatAuto-format with Prettier
bun run fetch-apiDownload the latest Roblox API dump and write it to packages/server/data/roblox-api.json
bun run build:vsixPackage the VS Code extension as a .vsix file for distribution
bun run build:betaPackage a beta build of the extension
bun run build:studioBuild the Roblox Studio plugin using Rojo

Verify

After cloning and installing, confirm everything works:

bun run build && bun run test

All 984 tests should pass. If they do, the language server binary is at packages/server/dist/index.js and ready for the extension to consume.

Contributing

Issues and pull requests are welcome. If you are adding new behavior or changing existing behavior, include tests in the relevant packages/server/tests/ suite. Bug reports should include the Luau snippet that reproduces the issue and the expected versus actual behavior.

To submit a pull request, fork the repository, create a branch, and open a PR against main. The CI pipeline runs type checking, linting, formatting, and the full test suite on every push.

License

MIT © 2025 Andrew

Ver o original no GitHub

Bom para

Relacionados