Editor Support

Editor support

.art files get syntax highlighting + a full LSP (diagnostics, goto-definition, completion) in VS Code and Emacs, and the artheia generator surface is exposed to Claude Code as an MCP server. All three drive code that ships with pip install artheia.

artheia-lsp — the language server

artheia-lsp is a pygls-based LSP server (artheia/lsp/server.py) that re-uses the same textX parser as the CLI. The full source is re-parsed on every change — for the corpus sizes artheia targets this is sub-millisecond.

Capabilities

feature	behavior
Diagnostics	published on open / change / save. textX errors carry a position (.line / .col), translated into LSP ranges. Same errors as artheia parse.
Goto-definition	resolves cross-refs across files: port → interface, prototype → node, connect source/target → port, gateway_route → node, type refs in messages and interfaces. Prefers the real (non-extern) definition, so a jump from a forward-decl extern interface X { } lands on the real body wherever it lives in the workspace.
Completion	keyword completion (the full grammar keyword set), in-workspace symbol completion (messages / interfaces / nodes), and gateway-catalog message names loaded from catalog.json / gateway_catalog*.json files in the workspace.
Import completion	on an import … line, suggests sibling subpackages by walking the file system (descends on ., filters on a partial segment, offers * at a leaf package).

The server eagerly parses every .art in the workspace folders on initialized (skipping .venv / node_modules / .git), so goto-definition works across files you haven't opened.

Anti-noise completion rule

Completion is intentionally conservative: outside an explicit invocation (Ctrl+Space), it only offers items when the cursor sits on an identifier prefix. The only trigger character is . — whitespace and Enter never pop (and risk auto-inserting) the menu on arrow-key navigation.

Running it standalone

artheia-lsp          # speaks LSP over stdio

The console script is installed by pip install artheia. Editor clients launch it for you (below).

VS Code

The extension lives in the umbrella repo at contrib/editors/vscode/. It contributes:

• the artheia language (.art) with a TextMate grammar (syntaxes/) + language-configuration.json (comments, brackets),
• an LSP client (src/) that activates onLanguage:artheia and spawns artheia-lsp,
• a configuration section for pointing at the server command.

Build / install:

cd contrib/editors/vscode
npm install
npm run compile        # or: npm run package  -> a .vsix to install

artheia-lsp must be on PATH (install artheia into the active environment).

Emacs

The mode lives at contrib/editors/emacs/artheia-mode.el (requires Emacs 27.1+ and lsp-mode 8.0+). It provides:

• artheia-mode: font-lock + comments + indentation for .art (the Emacs counterpart of the VS Code extension),
• an lsp-mode client that launches the same artheia-lsp server, giving diagnostics, goto-definition (port → interface, prototype → node), and keyword / in-workspace-symbol completion.

Install (with the repo on load-path):

(require 'artheia-mode)                ; .art -> artheia-mode, LSP client registered
(add-hook 'artheia-mode-hook #'lsp)    ; auto-start the LSP on open

artheia-lsp must be on PATH. Override the launch command with M-x customize-variable RET artheia-lsp-server-command.

artheia-mcp — generators as MCP tools for Claude Code

artheia-mcp (artheia/adapters/mcp_server.py) is a FastMCP server over stdio that exposes the generator CLI as MCP tools, so Claude Code drives gen-app / gen-manifest / parse / … as an API instead of shelling out. Every call runs in-process through Click's CliRunner against the live artheia.cli.main group (no per-call subprocess fork).

Tools

tool	what it does
list_generators	the LIVE command catalog (name + one-line help) — introspection-driven, never drifts
describe(command)	the full --help for one command (nested groups as group/sub)
parse(art_file, depth?)	resolve / validate an .art tree (the smoke test)
check_addresses(art_file)	assert TIPC (type, instance) uniqueness
gen_app(...)	the C++ FC/app scaffold (lib/main/impl + proto)
gen_manifest(art_file, out_file)	the Functional-Cluster manifest module
gen_proto(art_file, out?)	.proto per message
gen_schema(art_file, out)	the combined config-schema JSON
gen_netgraph(art_file, out?)	the nodes + compositions JSON netgraph
gen(command, args?)	the escape hatch — invoke ANY artheia command by name + raw argv (covers the long tail: gen-can-codec, import-dbc, audit-manifest, …)

Relative .art paths resolve against the workspace root (THEIA_INVOCATION_CWD or cwd).

Running it

artheia-mcp                              # or: python -m artheia.adapters.mcp_server

Wire it into Claude Code via an .mcp.json at the workspace root pointing at the artheia-mcp script (or the artheia/run_mcp.sh wrapper, which sources the workspace venv first). Claude Code then discovers it automatically.

See also

• Generators — what each command emits.
• Grammar — the keyword set the LSP completes against.