routeros-lsp

A Language Server Protocol server for MikroTik RouterOS scripts (.rsc files).

It gives editors and AI coding agents immediate feedback while they write RouterOS scripts: syntax errors, unknown menus, commands and parameters, variable scope mistakes, and completion and hover from the RouterOS command list. It follows the RouterOS scripting documentation, and where the documentation is silent or a real router behaves differently, the behaviour was measured on a router and written down in docs/ambiguities.md instead of guessed.

What it reports

Hover and completion use the same command list: menus and commands, parameters (required ones first), values after name=, and the variables in scope after $. There is also a symbol outline and folding. docs/features.md has the details and the limits; docs/rules.md lists every rule with its default severity.

A finding is labelled when it rests on RouterOS behaviour that the documentation does not describe, so a quirk of one version is never presented as the language specification.

Install and use

Python 3.10 or newer, no other dependencies:

pipx install routeros-lsp      # or: uv tool install routeros-lsp
routeros-lsp --version

To try the unreleased master, install straight from the repository:

pipx install git+https://github.com/wiresage/routeros-lsp.git

The server speaks LSP over stdio:

routeros-lsp --stdio

uvx routeros-lsp --stdio runs it without installing anything.

Claude Code

plugin/ is a Claude Code plugin that starts the server for .rsc files (language id routeros). It expects the routeros-lsp command on your PATH. Settings go into its .lsp.json; see docs/configuration.md.

Other editors

Start routeros-lsp --stdio for the language id routeros from any LSP client.

Check files from the command line

The same analysis runs without an editor, for a pre-commit hook, a CI job or a script an AI agent just wrote:

routeros-lsp check backup.rsc scripts/        # files and directories (every .rsc below them)
routeros-lsp check --strict --format json export.rsc
cat export.rsc | routeros-lsp check -         # standard input

Findings are printed as path:line:column: severity: message [rule], or as a JSON array with --format json; a summary goes to stderr, so stdout can be piped. The exit status is 0 when there is nothing to fix, 1 when errors were found (with --strict warnings count too) and 2 when a file cannot be read or an option is wrong. The settings of the editor integration are options: --scope, --schema, --severity RULE=LEVEL and --context-variable NAME; see routeros-lsp check --help.

The command list

Menus, commands and parameters come from a database generated from a RouterOS 7.21.4 CHR with /console/inspect (src/routeros_lsp/data/routeros-7.21.4.json.gz). A CHR has no wireless, LTE or switch-chip packages and some parameters exist only on some hardware, so unknown-name findings are warnings by default. To cover your own hardware, generate the database from your router (nothing is executed or changed on it) and point the schema setting at it:

pip install paramiko
ROUTEROS_PASSWORD=... python tools/gen_schema.py --host 192.0.2.1 --user admin --out my-router.json.gz

Develop

python -m venv .venv && . .venv/bin/activate     # on Windows: .venv/Scripts/activate
pip install -e ".[dev]"
ruff check . && mypy && pytest

The tests need no router. Releases are cut by the pipeline in docs/releasing.md. See CONTRIBUTING.md, AGENTS.md and docs/architecture.md.

How the language was pinned down

• docs/grammar.md: the grammar derived from the documentation, each rule tagged as documented, shown by an example, observed on a device, or open.
• docs/ambiguities.md: every gap and conflict, with evidence from RouterOS 7.21.4 and the default used.
• research/: the probes that produced that evidence. RouterOS can check a script without running it (/import file.rsc verbose=yes dry-run), which is the test oracle for this project; tests/conformance/ replays more than 800 recorded answers.

License

MIT