Adding New Language Support
Relevant source files
The following files were used as context for generating this wiki page:
Serena provides semantic code analysis through two primary backends: Language Servers (LSP) and the Serena JetBrains Plugin. Adding support for a new language typically involves integrating an open-source language server into the SolidLSP library, which is the internal component responsible for managing LSP communication.
Sources: README.md:120-135, src/serena/config/serena_config.py:194-205
Architectural Overview
The project uses a multi-layered configuration system to manage language support. Global settings are defined in serena_config.yml, while specific project requirements are handled in project.yml. When a language is added via the LSP backend, Serena spawns a dedicated language server process managed by the SolidLSP library.
The diagram shows the flow of adding a new language from the user interface through the configuration updates to the process spawning of a language server.
Sources: src/serena/resources/dashboard/dashboard.js:1068-1095, src/serena/config/serena_config.py:440-455
Integration Steps for New LSP Support
1. Language Server Implementation
A new language server integration must inherit from SolidLanguageServer. This involves defining the language identifier, the command to launch the server, and handling platform-specific binary distributions.
| Component | Description |
|---|---|
| Language Identifier | A unique string identifying the language (e.g., "elixir"). |
| Launch Command | The standard input/output command to start the server (e.g., expert --stdio). |
| File Extensions | Mapping of extensions (e.g., .ex, .exs) to the language server. |
| Ignored Paths | Language-specific build directories to ignore (e.g., _build/, deps/). |
Sources: src/solidlsp/language_servers/elixir_tools/README.md:16-56
2. Configuration Update
The Language enum must be updated to include the new language string. This allows the system to recognize the language in project.yml files.
# project.yml template
languages: ["python", "new_language"]
ls_specific_settings:
new_language:
setting_key: value
Sources: src/serena/resources/project.template.yml:32-47, src/serena/config/serena_config.py:317-330
3. Dashboard Integration
The Serena Dashboard facilitates adding languages dynamically. It polls the server for available languages and sends a POST request to /add_language to update the active project configuration.
The sequence shows the asynchronous interaction between the Dashboard and the MCP server when a user adds a new language.
Sources: src/serena/resources/dashboard/dashboard.js:1000-1090
Language Server Requirements
To ensure optimal performance and accuracy (especially for cross-file references), some language servers have specific requirements:
- Prerequisites: Tools like
elixirornpmmust be available in the systemPATH. - Compilation: Some servers (like Elixir's Expert) require the project to be compiled (e.g.,
mix compile) before full symbol information is available. - Platform Support: Integrations should ideally support Linux, macOS, and Windows across x64 and arm64 architectures.
Sources: src/solidlsp/language_servers/elixir_tools/README.md:5-25, src/solidlsp/language_servers/elixir_tools/README.md:65-80
Testing the Integration
New language support must be verified using integration tests. These tests validate symbol detection, reference finding, and diagnostics.
- Initialization: Verify the server starts and identifies as the correct language.
- Symbol Detection: Test
request_document_symbolsagainst sample files to ensure classes, functions, and headings are detected. - Reference Finding: Verify that cross-file references are resolved correctly.
Sources: test/solidlsp/markdown/test_markdown_basic.py:24-60, test/solidlsp/matlab/test_matlab_basic.py:38-75
Summary
Adding language support in Serena requires defining the LSP implementation details in the SolidLSP library, updating the Language enum, and ensuring the MCP server can persist these changes to the project's configuration. This process enables agents to perform symbol-level retrievals and refactorings in the newly supported language.
Sources: CONTRIBUTING.md:10-15, src/serena/config/serena_config.py:440-460