rbxdev-ls

Luau language server and VS Code extension for Roblox development with live-game tooling.

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 @0neshot101/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 — 16 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 16 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.

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.

Component	Transport	Direction
Editor ↔ Language Server	JSON-RPC over stdio	Bidirectional
Extension ↔ Executor	WebSocket on port 21324	Bidirectional
MCP Client ↔ MCP Server	stdio (Model Context Protocol)	Bidirectional
MCP Server ↔ Extension	WebSocket proxy	Bidirectional (when extension is running)
Studio Plugin ↔ Extension	WebSocket on port 21324	Bidirectional

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["@0neshot101/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:

Marketplace	Link
VS Code Marketplace	rbxdev.rbxdev-ls
Open VSX	rbxdev/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:

Mode	Shortcut	Behavior
Execute file	`Ctrl+Shift+E`	Sends the entire active file to the executor
Execute selection	`Ctrl+Shift+Alt+E`	Sends only the selected text
Bundle and execute	`Ctrl+Alt+E`	Resolves `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;
})

Parameter	Default	Purpose
`host`	`ws://127.0.0.1:21324`	WebSocket URL the bridge connects to
`reconnectDelay`	`5`	Seconds between reconnection attempts after a disconnect
`firstConnectDepth`	`999`	How many levels deep to scan the instance tree on first connection
`updateTreeDepth`	`2`	Depth of tree updates sent when instances change
`expandedTreeDepth`	`2`	Depth of subtree sent when expanding a node in the game tree panel

MCP Server

The @0neshot101/rbxdev-mcp package exposes 16 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 hosted on GitHub Packages. Configure npm to use the GitHub registry for the @0neshot101 scope by adding this to your ~/.npmrc:

@0neshot101:registry=https://npm.pkg.github.com

Then add this block to your MCP client configuration:

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

The config file location depends on your tool:

Tool	Config location
Claude Code	`~/.claude/mcp_config.json`
Claude Desktop	Settings → MCP Servers
Cursor	`.cursor/mcp.json` in your project
Windsurf	Cascade → 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", "@0neshot101/rbxdev-mcp"],
      "env": {
        "RBXDEV_BRIDGE_PORT": "21325"
      }
    }
  }
}

Available MCP Tools

Tool	Description
`get_bridge_status`	Check whether the bridge is running and an executor is connected
`execute_code`	Run Luau code in the game with full Roblox API access
`get_game_tree`	Browse the game hierarchy (services, instances, children)
`get_properties`	Read property values from any instance
`set_property`	Set properties on instances (supports Vector3, Color3, UDim2, and more)
`get_children`	List children of a specific instance
`create_instance`	Create new instances in the game
`clone_instance`	Clone existing instances
`delete_instance`	Remove instances from the game
`reparent_instance`	Move instances to a new parent
`teleport_player`	Teleport the local player to an instance's position
`get_script_source`	Decompile and read script source code
`get_console_output`	Read recent print/warn/error output from the game
`refresh_game_tree`	Request a fresh snapshot of the game tree
`get_remote_calls`	View captured RemoteEvent/RemoteFunction calls
`set_remote_spy_enabled`	Toggle the remote spy on or off

The server also exposes three MCP resources for passive reading:

Resource URI	Content
`rbxdev://bridge/status`	Connection status as JSON
`rbxdev://game/tree`	Full game tree rendered as text
`rbxdev://console/logs`	Recent 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.

Setting	Default	Purpose
`rbxdev-ls.typeCheckMode`	`nonstrict`	Controls the default type checking strictness for files without a `--!` annotation at the top. Accepts `strict`, `nonstrict`, or `nocheck`
`rbxdev-ls.enableSuncApi`	`false`	Loads Sunc executor API definitions into the type environment, providing completions and type checking for Sunc-specific globals
`rbxdev-ls.executorBridge.port`	`21324`	The TCP port the WebSocket bridge server listens on for executor and Studio plugin connections
`rbxdev-ls.mcp.enabled`	`true`	Enables 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.debugLogs`	`false`	Enables verbose logging in the extension output channel for troubleshooting connection and protocol issues

Keyboard Shortcuts

Shortcut	Command
`Ctrl+Shift+E`	Execute the current file in-game
`Ctrl+Shift+Alt+E`	Execute the selected text in-game
`Ctrl+Alt+E`	Bundle all required modules and execute
`Ctrl+Shift+R`	Copy the last Remote Spy call to clipboard
`Ctrl+Shift+Alt+R`	Insert the last Remote Spy call at the cursor
`Ctrl+Alt+C`	Quick 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        16 language model tools for Copilot integration
│   ├── mcp/                       Standalone MCP server (@0neshot101/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
│   ├── publish-mcp.ts             Publishes @0neshot101/rbxdev-mcp to GitHub Packages
│   ├── 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

Dependency	Minimum Version	Install
Bun	≥ 1.0.0	`curl -fsSL https://bun.sh/install \| bash`
Node.js	≥ 18	Required for MCP package builds and runtime
Rojo	Latest	Only 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

Script	Description
`bun run build`	Build the language server (compiles `packages/server` with Bun targeting Node.js)
`bun run build:mcp`	Build the standalone MCP server
`bun run build:all`	Build the language server and MCP server in sequence
`bun run test`	Run the full test suite (984 tests across 29 files)
`bun run type-check`	Run the TypeScript compiler in check-only mode against the server package
`bun run lint:check`	Run ESLint without auto-fixing
`bun run lint`	Run ESLint with auto-fix
`bun run format:check`	Check formatting with Prettier
`bun run format`	Auto-format with Prettier
`bun run fetch-api`	Download the latest Roblox API dump and write it to `packages/server/data/roblox-api.json`
`bun run build:vsix`	Package the VS Code extension as a `.vsix` file for distribution
`bun run build:beta`	Package a beta build of the extension
`bun run build:studio`	Build 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.

Name		Name	Last commit message	Last commit date
Latest commit History 159 Commits
.github		.github
.vscode		.vscode
apps/web		apps/web
packages		packages
roblox		roblox
scripts		scripts
.editorconfig		.editorconfig
.eslintrc.cjs		.eslintrc.cjs
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
foreman.toml		foreman.toml
mcp-config.example.json		mcp-config.example.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

rbxdev-ls

Overview

Features

Table of Contents

Quick Start

How It Works

Architecture

Installation

VS Code Extension

MCP Server (Standalone)

Usage

Language Server

Live-Game Features

Code Execution

Executor Bridge Setup

MCP Server

Setup

Proxy Mode

Custom Port

Configuration

Keyboard Shortcuts

Project Structure

Development

Prerequisites

Setup

Scripts

Verify

Contributing

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages