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.

Status: version 0.1, in development. The package is built for PyPI (routeros-lsp) by the release pipeline in .github/workflows/. Until the first release is out, install it from the repository as described below.

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. Once a release is on PyPI:

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

Until then, 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.

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