@choigawoon/mlua-lsp

Fast, cross-platform LSP server for mLua (MapleStory Worlds scripting).

Wraps the official msw.mlua VS Code extension and exposes it as a standalone CLI + TCP daemon for any LSP client.

Benchmark

Tested on macOS arm64, Node v22.22.0, tuto-1 project (88-line script, 600+ .mlua files).

| Command | Legacy (one-shot) | Optimized (daemon) | Speedup | |---------|-------------------|-------------------|---------| | hover | 66s | 32ms | 2000x | | complete | 66s | 35ms | 1900x | | definition | 66s | 28ms | 2300x |

Legacy daemon had a TCP half-close bug causing 100% fallback to one-shot mode. See docs/benchmark.md for full methodology and analysis.

Key optimizations

• Zero sleep for non-diagnostic commands — hover, complete, definition, references, signature fire immediately (legacy had 1500ms hardcoded sleep)
• mtime-based file cache — skips re-read when file hasn't changed
• TCP localhost IPC — works on macOS, Windows, Linux (legacy: Unix socket, macOS only)
• Newline-delimited JSON protocol — avoids TCP half-close timing issues
• Optimized LSP parser — chunk-list buffer to reduce GC pressure
• Selective diagnostic pull — only pulls for the changed file

Install

npm install -g @choigawoon/mlua-lsp

Usage

CLI (persistent daemon mode)

# Diagnostics
mlua-lsp diagnose <project-root> <file.mlua>

# Type info at position (line/col are 1-based)
mlua-lsp hover <project-root> <file.mlua> <line> <col>

# Code completion
mlua-lsp complete <project-root> <file.mlua> <line> <col>

# Go to definition
mlua-lsp definition <project-root> <file.mlua> <line> <col>

# Find references
mlua-lsp references <project-root> <file.mlua> <line> <col>

# Signature help
mlua-lsp signature <project-root> <file.mlua> <line> <col>

# Daemon management
mlua-lsp status <project-root>
mlua-lsp dump <project-root> [--verbose]    # live session snapshot (safe mid-batch)
mlua-lsp describe [<project-root>]          # machine-readable command catalog
mlua-lsp stop <project-root>

dump exposes counters (inFlight, completed, failed, byCommand) plus the files actually opened in the underlying language server — useful for progress-tracking a large batch or confirming lazy didOpen behavior. Pass --verbose to include the full file list.

describe returns a JSON catalog of the commands this daemon speaks, including each command's required/optional fields and response shape. Intended as the canonical probe for AI clients that want to discover capabilities without parsing help text. Works with or without a running daemon.

LSP server mode (stdio)

mlua-lsp server --stdio

One-shot mode (no daemon)

mlua-lsp hover <project-root> <file.mlua> 10 5 --no-daemon

How it works

1. First run auto-downloads the msw.mlua extension from VS Code Marketplace
2. A background TCP daemon keeps the language server alive between CLI calls
3. Subsequent requests reuse the warm server — sub-second responses
4. Daemon auto-shuts down after 30 minutes of inactivity (override via MLUA_LSP_IDLE_MINUTES)

License

MIT