JetBrains Plugin Backend
Relevant source files
The following files were used as context for generating this wiki page:
The JetBrains Plugin Backend is a high-performance code analysis and editing engine for Serena that leverages the native capabilities of JetBrains IDEs (such as IntelliJ IDEA, PyCharm, and WebStorm). It serves as a premium alternative to the default Language Server Protocol (LSP) backend, offering deeper semantic understanding, advanced refactoring tools, and interactive debugging features.
The system operates by establishing a connection between the Serena MCP server and a local JetBrains IDE instance via a dedicated plugin. This allows AI agents to perform complex operations like cross-file renames, symbol moves, and type hierarchy analysis with IDE-level precision.
Sources: README.md:104-121, src/serena/jetbrains/jetbrains_plugin_client.py:10-25
Architecture and Connectivity
The backend architecture relies on a client-server model where Serena acts as the client and the JetBrains IDE (running the Serena plugin) acts as the server. The connection is managed through a port-scanning mechanism to identify active IDE instances.
Plugin Client Manager
The JetBrainsPluginClientManager is a singleton responsible for discovering available plugin instances. It scans a range of ports (starting from SerenaPorts.JETBRAINS_PLUGIN_SERVER_BASE_PORT) to find a plugin instance that matches the current project root.
The manager uses a ThreadPoolExecutor to perform parallel scans across 20 potential ports to minimize latency during connection initialization.
Sources: src/serena/jetbrains/jetbrains_plugin_client.py:84-110, src/serena/jetbrains/jetbrains_plugin_client.py:183-195
Connection Lifecycle
A JetBrainsPluginClient instance communicates with the IDE via a REST API. It handles version validation to ensure compatibility with specific tools and performs automatic snake_case conversion for Python-friendly data handling.
| Component | Responsibility |
|---|---|
JetBrainsPluginClient | Executes HTTP requests to the plugin and processes responses. |
JetBrainsPluginClientManager | Singleton manager for discovering and matching IDE instances. |
SerenaPorts | Defines the base port (62541) for the plugin server. |
Sources: src/serena/jetbrains/jetbrains_plugin_client.py:175-185, src/serena/jetbrains/jetbrains_plugin_client.py:270-300
Semantic Retrieval Tools
The JetBrains backend provides advanced retrieval capabilities that exceed standard LSP functionality, particularly in handling project dependencies and complex type relationships.
Type Hierarchy and Symbol Discovery
The backend can traverse class hierarchies in both directions (superclasses and subclasses). This is implemented through the JetBrainsTypeHierarchyTool, which requests data from the /getSupertypes and /getSubtypes endpoints.
Key Retrieval Tools
JetBrainsFindSymbolTool: Searches for symbols across the project and its dependencies (search_deps=True).JetBrainsGetSymbolsOverviewTool: Provides a compact overview of a file's structure, including docstrings.JetBrainsFindReferencingSymbolsTool: Finds all code entities that reference a specific symbol, including cross-file usages.
Sources: src/serena/tools/jetbrains_tools.py:22-60, src/serena/tools/jetbrains_tools.py:237-260, src/serena/tools/jetbrains_tools.py:330-350
Advanced Refactoring and Symbolic Editing
The JetBrains backend enables "symbolic editing," which treats code as structured entities rather than raw text. This is supported by the IDE's internal refactoring engine.
Refactoring Operations
Unlike standard text-based edits, these tools automatically update all references across the entire codebase to maintain integrity.
| Tool | Action | Description |
|---|---|---|
JetBrainsMoveTool | Move Symbol/File | Moves symbols to new parents or files to new directories. |
JetBrainsRenameTool | Global Rename | Renames symbols, files, or directories with reference updates. |
JetBrainsSafeDeleteTool | Safe Delete | Checks for usages before deletion; can propagate to unused code. |
JetBrainsInlineSymbol | Inline | Replaces all call sites with the symbol's body and optionally deletes the definition. |
Sources: src/serena/tools/jetbrains_tools.py:112-140, src/serena/tools/jetbrains_tools.py:164-185, src/serena/resources/config/modes/editing.yml:5-20
Refactoring Data Flow
When a refactoring tool is called, it verifies the minimum required plugin version before dispatching the request.
Interactive Debugging and Inspection
A unique feature of the JetBrains backend is the JetBrainsDebugTool, which provides a persistent REPL-style interface for runtime inspection.
Debugging with Groovy REPL
The backend allows an agent to evaluate Groovy or Java expressions within the context of the running IDE. This is used for:
- Inspecting variable states.
- Evaluating complex expressions.
- Controlling execution flow.
The state is maintained across calls using a repl_key.
Sources: src/serena/tools/jetbrains_tools.py:530-555, src/serena/jetbrains/jetbrains_plugin_client.py:535-555
Static Analysis and Inspections
The JetBrainsRunInspectionsTool leverages the IDE's inspection engine to find potential bugs, type mismatches, and code style violations. Agents can filter by min_severity (e.g., "ERROR" or "WARNING") or target specific inspection_names.
Sources: src/serena/tools/jetbrains_tools.py:560-585, src/serena/tools/jetbrains_tools.py:595-610
Configuration and Setup
The backend is activated by setting the language_backend to JetBrains in the global or project configuration.
Global Configuration
The SerenaConfig class handles the plugin connection settings:
jetbrains_plugin_server_address: Defaults to127.0.0.1.jetbrains_launch_command: Optional command to automatically start the IDE on demand.
Sources: src/serena/config/serena_config.py:475-485, src/serena/config/serena_config.py:540-550
Project Level Setup
Project configurations can override the backend selection, though the backend is typically fixed at startup.
# project.yml example
language_backend: JetBrains
read_only: false
excluded_tools: []
Sources: src/serena/resources/project.template.yml:55-65
Conclusion
The JetBrains Plugin Backend provides a robust, IDE-native toolset for Serena. By leveraging the internal semantic engines of JetBrains products, it allows agents to perform complex, multi-file refactorings and deep code analysis that are more reliable and efficient than standard LSP or text-based approaches. This backend is essential for high-integrity workflows involving large-scale code modifications and interactive debugging.