This server provides AI assistants with programmatic access to Rell Language Server Protocol (LSP) features for analyzing and working with Rell code, including automated LSP download and management.
Start and manage the LSP server: Initialize (start_lsp) with a project root, restart (restart_lsp_server) if needed, and adjust logging verbosity (set_log_level).
Manage documents: Open, save, and close files (open_document, save_document, close_document) to make them available for analysis.
Get hover information: Retrieve type details and documentation at a specific location (get_info_on_location, also via lsp-hover:// resource).
Get code completions: Obtain context-aware suggestions at a position (get_completions, also via lsp-completions:// resource).
Get code actions: Access refactorings and quick fixes for a selected range (get_code_actions).
Get diagnostics: Retrieve errors and warnings for open files (get_diagnostics, also via lsp-diagnostics:// resource with real-time updates).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Chromia LSP MCP Start the Rell LSP server on /path/to/my-dapp and show diagnostics for all open files"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Rell language intelligence for AI coding agents, over the Model Context Protocol. It ships as a container image with the Rell language server inside, so there is nothing to install beyond a container runtime.
The canonical repository is on GitLab: gitlab.com/chromaway/core-tools/chromia-lsp-mcp. The image is published to that project's container registry. The old npm package
@chromia/chromia-lsp-mcpis no longer maintained.
Agents like Claude Code and Cursor only see Rell as text. This server gives them what an IDE has:
Types, docs, and the meaning of the symbol at any position
Completions actually in scope there
The compiler's and linter's own errors and warnings
Navigation: definitions, references, outlines, project-wide symbol search
Edits written to disk: rename, quick fixes, formatting
Related MCP server: LSP-MCP
Only an OCI compatible container runtime.
Images are published for linux/amd64 and linux/arm64, so Apple Silicon runs natively.
An MCP entry is bound to one project: the project directory appears twice in the run command, once as the mount and once as the working directory. Configure this server per project, not once globally — a single global entry cannot follow you from one dapp to the next, and aiming one at a parent directory holding several projects makes the language server index all of them at once. Every client below is therefore configured inside the project it serves.
Mount the project root — the directory holding chromia.yml and src/ — because only what is
mounted is visible to the language server.
On Linux, use docker with --user "$(id -u):$(id -g)" — without it, files the server edits come
back owned by root. Podman needs no such flag.
On macOS, use Apple's container, started once per boot with
container system start, or Docker Desktop or Colima with docker. No --user needed. Docker
Desktop shares only /Users by default.
On Windows, work in WSL2 with Docker Desktop's WSL integration and follow the Linux line, keeping
the project on the WSL filesystem rather than /mnt/c/.... Windows-native Docker cannot work: a
Linux container has no C:\... path.
Examples below use docker; substitute container or podman.
Run this from the project root. The shell expands $(pwd) as the entry is written, so it is
pinned to this project. On Linux:
claude mcp add chromia-lsp -- docker run --rm -i \
--user "$(id -u):$(id -g)" \
-v "$(pwd):$(pwd)" -w "$(pwd)" \
registry.gitlab.com/chromaway/core-tools/chromia-lsp-mcp:latestOn macOS, with Apple's runtime started (container system start):
claude mcp add chromia-lsp -- container run --rm -i \
-v "$(pwd):$(pwd)" -w "$(pwd)" \
registry.gitlab.com/chromaway/core-tools/chromia-lsp-mcp:latestclaude mcp add defaults to local scope, which is what you want here: the entry is stored under
this project's path and loads only in it. Avoid --scope user, which would offer one project's
hardcoded path in every other project you open. claude mcp list shows whether it connects, and
claude mcp remove chromia-lsp undoes it.
For a team, --scope project writes the entry to .mcp.json in the repository instead. That file
travels to other machines, so the absolute path has to come from somewhere per-developer — Claude
Code expands ${VAR} in arguments, so have everyone set one variable in their shell:
"args": [
"run", "--rm", "-i",
"-v", "${RELL_PROJECT_DIR}:${RELL_PROJECT_DIR}",
"-w", "${RELL_PROJECT_DIR}",
"registry.gitlab.com/chromaway/core-tools/chromia-lsp-mcp:latest"
]Cursor keeps project servers in .cursor/mcp.json at the project root. It substitutes
${workspaceFolder}, so the file resolves to the right path on every machine and can be committed:
{
"mcpServers": {
"chromia-lsp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "${workspaceFolder}:${workspaceFolder}",
"-w", "${workspaceFolder}",
"registry.gitlab.com/chromaway/core-tools/chromia-lsp-mcp:latest"
]
}
}
}~/.cursor/mcp.json is the global equivalent and the wrong home for this server: one entry cannot
serve two projects.
Copilot in VS Code reads .vscode/mcp.json in the project, names the key servers instead of
mcpServers, and substitutes ${workspaceFolder} the same way Cursor does. The entry is otherwise
identical.
A client with no variable substitution needs the project's absolute path spelled out:
{
"mcpServers": {
"chromia-lsp": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "/home/you/my-dapp:/home/you/my-dapp",
"-w", "/home/you/my-dapp",
"registry.gitlab.com/chromaway/core-tools/chromia-lsp-mcp:latest"
]
}
}
}Keep that file out of version control — the path in it is true only on your machine.
:latest follows releases. Pin a specific one when you want the language server
version to stay put; each image tag carries one Rell language server, recorded in the image label
com.chromia.rell-lsp.version. Image tags match the repository's git tags.
Your MCP client starts the container; you never run it by hand. Ask the AI agent to work on Rell
code and it drives the tools itself, starting with start_lsp. That one defaults to the mounted
working directory, so in the setups above it needs no argument — if the agent ever picks the wrong
place, name the right one:
Start the Rell LSP server with root directory /home/you/my-dapp
The container lives as long as the client session and holds the language server's index in memory, so the first query after startup is the slow one.
Tool | What it does |
| Start the language server on a project root. Call this first. |
| Restart it, optionally on a different root |
| Open a file for analysis |
| Push the file's current content so diagnostics refresh |
| Close a file and release what it holds |
| Errors and warnings for one file or all open files |
| Hover: types, docs, and context at a position |
| Completions valid at a position |
| Quick fixes and refactorings for a range |
| Apply one of them, writing the result to disk |
| Where a symbol is declared |
| Every use of a symbol |
| Outline of one file |
| Find a symbol anywhere in the project |
| Rename across every file that references it |
| Format a file or a range within it |
| Change logging verbosity at runtime |
Line and column arguments are 1-based, the way an editor reports them.
lsp-diagnostics:// — diagnostics for every open file, and lsp-diagnostics:///path/to/file.rell
for one of them. Subscribe to either and the server notifies you whenever the language server
republishes.
lsp-hover:///path/to/file.rell?line=6&column=8
lsp-completions:///path/to/file.rell?line=25&column=10
The server reports what it is doing as MCP log notifications. Ask the assistant to set the log
level to debug, or start it that way:
-e LOG_LEVEL=debugadded to the docker run arguments. In Claude Code, claude --mcp-debug additionally shows the
raw traffic between client and server. Everything the server writes for humans goes to stderr;
stdout carries the protocol and nothing else.
Variable | Default | Purpose |
|
|
|
|
| Language server to run |
| — | JVM flags for the language server process, e.g. |
The server runs inside a container, but the agent talks about files by path — the paths it sees on your machine. So the project is mounted at the same path inside the container:
-v "/home/you/my-dapp:/home/you/my-dapp" -w "/home/you/my-dapp"With that, /home/you/my-dapp/src/main.rell means the same file on both sides and no translation
is needed anywhere. Every example in this README follows that pattern.
Cannot read /home/you/my-dapp/src/main.rell means the file is outside the mount. Check that the
-v path is the project root and that -w matches it.
Empty diagnostics are usually a timing problem: the language server pushes them after indexing, and only for open files. Open the file first and retry; on a large project the first pass takes a few seconds.
Files coming back owned by root on Linux means the --user "$(id -u):$(id -g)" flag is missing
from the run arguments.
If every tool returns an empty result, the language server probably failed to start. Set
LOG_LEVEL=debug and read the client's MCP server log — the language server's own output is
forwarded there.
An MCP server runs on your machine with your files, so what it executes matters. The retired npm
package downloaded the language server — and on most platforms a whole Java runtime — from package
registries at run time and executed them, with no checksum standing between a registry compromise
and your machine. The image closes that channel: nothing is fetched at run time. The language
server version is pinned in this repository, every build dependency is pinned by SHA-256 in
gradle/verification-metadata.xml, the base image is pinned by digest, and each release is an
immutable image you can pin by tag or digest yourself. The container also bounds what the server
can touch: it reads and writes only the project directory you mount.
The supply chain behind the build shrank with the move too. The npm package's lockfile pinned 288
packages, each one an independently owned npm account and a separate thing to trust; MCP's
documented install idiom, npx -y <server>, additionally fetches the latest of all of that at
launch, and that channel has already burned the MCP ecosystem — the September 2025 chalk/debug
compromise reached transitive dependencies of the official MCP TypeScript SDK. This server's
runtime classpath is about 35 JARs from a handful of organizations, JetBrains and Eclipse for the
most part, and it changes only when a commit to this repository changes the pinned checksums.
Close a file in the LSP server. Use this tool when you're done with a file to free up resources and reduce memory usage. It's good practice to close files that are no longer being actively analyzed, especially in long-running sessions or when working with large codebases.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the file to close |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the resource-freeing behavior, which is helpful, but doesn't state what happens if the file isn't open or whether unsaved changes are affected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value—purpose, usage context, and best practice. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description adequately covers purpose and usage. It omits return value/error scenarios, but these are not critical for a straightforward close operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with a single parameter (file_path) and its description. The tool description adds no further semantic detail beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Close a file in the LSP server' with a specific verb and resource, distinguishing it from sibling tools like open_document and save_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use the tool ('when you're done with a file to free up resources') and specific scenarios (long-running sessions, large codebases). It doesn't mention alternatives but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get code actions for a specific range in a file. Use this tool to obtain available refactorings, quick fixes, and other code modifications that can be applied to a selected code range. Examples include adding imports, fixing errors, or implementing interfaces. Requires the file to be opened first.
| Name | Required | Description | Default |
|---|---|---|---|
| end_line | Yes | End line number | |
| file_path | Yes | Path to the file | |
| end_column | Yes | End column position | |
| start_line | Yes | Start line number | |
| language_id | Yes | The programming language the file is written in | |
| start_column | Yes | Start column position |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral transparency. It discloses the file-open prerequisite but fails to state whether the operation is read-only or whether it applies changes, nor does it describe the return format. This leaves ambiguity about the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and stays focused. The first sentence defines the purpose, the second adds illustrative examples, and the third states a key prerequisite. It is concise without being overly terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should explain what the tool returns. It mentions 'obtain available refactorings' but does not describe the response structure or possible error conditions. The prerequisite helps, but completeness is only moderate for a tool with six required parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters are individually documented in the schema. The description adds only the concept of a 'specific range', which aligns with the start/end line/column parameters, but provides no additional parameter semantics beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get code actions for a specific range in a file.' It provides a specific verb-resource pair and concrete examples (refactorings, quick fixes), distinguishing it from sibling tools like get_completions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this tool to obtain available refactorings, quick fixes, and other code modifications' and warns that the file must be opened first. It does not list exclusion criteria or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get completion suggestions at a specific location in a file. Use this tool to retrieve code completion options based on the current context, including variable names, function calls, object properties, and more. Helpful for code assistance and auto-completion at a particular location. Use this when determining which functions you have available in a given package, for example when changing libraries. Requires the file to be opened first.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | Line number | |
| column | Yes | Column position | |
| file_path | Yes | Path to the file | |
| language_id | Yes | The programming language the file is written in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses an important behavioral constraint: the file must be opened first. It also clarifies that completions are context-based. However, it does not describe return format, error conditions, or whether an LSP server must be running, so it only partially covers transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of five sentences but contains redundancy: sentences 1 and 2 both describe retrieving completions, and sentence 3 ('Helpful for...') adds little. The useful unique information (use case and prerequisite) could be expressed in fewer words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a completion tool, the description covers the core purpose, context, example use case, and a critical prerequisite (open file). It omits details about the return value or error handling, but given the simplicity and lack of output schema, it is reasonably complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description indirectly references location and context but does not add specific parameter details beyond what the schema provides. The prerequisite about opening the file adds a bit of context for file_path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the main function ('Get completion suggestions at a specific location in a file') and elaborates on the types of completions (variable names, function calls, object properties). This distinguishes it from siblings like get_diagnostics or get_code_actions, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases ('when determining which functions you have available in a given package, for example when changing libraries') and a prerequisite ('Requires the file to be opened first'). However, it does not explicitly name alternative tools or say when not to use it, so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get diagnostic messages (errors, warnings) for files. Use this tool to identify problems in code files such as syntax errors, type mismatches, or other issues detected by the language server. When used without a file_path, returns diagnostics for all open files. Requires files to be opened first.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No | Path to the file to get diagnostics for. If not provided, returns diagnostics for all open files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing the default behavior when file_path is omitted (returns diagnostics for all open files) and the prerequisite that files be opened first. It doesn't describe the return format, but the read-only nature is implied by 'Get' and the description adds useful context beyond the bare tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that front-load the main action and then provide optional behavior and prerequisites. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single optional parameter and no output schema, the description adequately covers purpose, usage context, and key behavioral nuance (all open files). It could explicitly mention the output structure, but for a diagnostics tool the expected return is generally understood.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description adds no new meaning beyond the input schema: the schema already states that file_path is optional and that omitting it returns diagnostics for all open files. Since schema coverage is 100%, and the description merely repeats the parameter's behavior, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves diagnostic messages for files, using a specific verb ('Get') and identifying the resource (diagnostics for files). It distinguishes itself from sibling tools like get_completions or get_code_actions by focusing on errors, warnings, and language-server-detected issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this tool to identify problems in code files' and notes a prerequisite (files must be opened). It doesn't explicitly name exclusions or alternatives, but the clear scope provides sufficient guidance for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information on a specific location in a file via LSP hover. Use this tool to retrieve detailed type information, documentation, and other contextual details about symbols in your code. Particularly useful for understanding variable types, function signatures, and module documentation at a specific location in the code. Use this whenever you need to get a better idea on what a particular function is doing in that context. Requires the file to be opened first.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | Line number | |
| column | Yes | Column position | |
| file_path | Yes | Path to the file | |
| language_id | Yes | The programming language the file is written in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the prerequisite 'Requires the file to be opened first' and implies a read-only operation via 'get information' and 'LSP hover.' It does not explicitly state there are no side effects or describe error behavior, but the key requirement is covered, making it reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose and redundant. Sentences 2 and 3 both mention retrieving type information and documentation, and sentence 4 repeats 'use this' guidance. It could be condensed to two or three clear sentences without losing meaning, so it does not earn full points for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only hover tool with four parameters, the description covers purpose, usage scenarios, and a key prerequisite. There is no output schema, so the description gives a general idea of the return content ('detailed type information, documentation...'). While more detail on return format or error handling would improve completeness, it is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all four parameters, so the baseline is 3. The description does not add any parameter-specific details beyond the schema. It refers to 'a specific location' (line/column) and 'a file,' but these are already implied by the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get information on a specific location in a file via LSP hover,' which is a specific verb+resource statement that clearly conveys the tool's function. It also distinguishes this from siblings like get_completions and get_code_actions by focusing on retrieving hover/type information rather than generating completions or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, stating it is 'particularly useful for understanding variable types, function signatures, and module documentation.' It also says 'Use this whenever you need to get a better idea on what a particular function is doing in that context.' However, it does not explicitly mention when not to use it or name alternative tools, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a file in the LSP server for analysis. Use this tool before performing operations like getting diagnostics, hover information, or completions for a file. The file remains open for continued analysis until explicitly closed
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the file to open |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It notes that 'The file remains open for continued analysis until explicitly closed,' which is a critical stateful behavior beyond what the schema reveals. It doesn't cover potential errors or return values, but the key persistence trait is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and includes only necessary context about usage and persistence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is sufficient. It explains what, when, and the stateful behavior. The sibling tool list (e.g., close_document) provides additional context about the lifecycle, but the description alone already covers the essential aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'file_path' described as 'Path to the file to open.' The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Open') and resource ('file in the LSP server') with a clear purpose ('for analysis'). It distinguishes itself from siblings like close_document and get_diagnostics by stating it is a prerequisite for those operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'before performing operations like getting diagnostics, hover information, or completions for a file.' It doesn't explicitly mention when not to use or name alternatives, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart the LSP server process. Use this tool to reset the LSP server if it becomes unresponsive, has stale data, or when you need to apply configuration changes. Can optionally reinitialize with a new root directory. Useful for troubleshooting language server issues or when switching projects.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | No | The root directory for the LSP server. If not provided, the server will not be initialized automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions optional reinitialization with a new root directory and clarifies that the server won't auto-initialize if root_dir is omitted. However, it does not disclose side effects like loss of unsaved state, impact on open documents, or required permissions, which are important for a restart operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the core action in the first sentence. It is succinct, front-loaded, and contains no filler or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool without an output schema, the description covers the main purpose, common use cases, and parameter behavior. Minor gaps exist (e.g., side effects), but overall it provides enough context for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (root_dir is fully described in the schema). The description adds minor context by explaining that root_dir is optional and controls reinitialization, but it doesn't significantly go beyond the schema's own explanation. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Restart the LSP server process,' which clearly states the specific action and resource. It distinguishes this tool from siblings like start_lsp (initial startup) and get_diagnostics (inspection) by focusing on restarting an existing server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool: 'if it becomes unresponsive, has stale data, or when you need to apply configuration changes' and 'when switching projects.' It provides clear context but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a file in the LSP server for analysis. Use this tool before performing operations like getting diagnostics, hover information, or completions for a file. The file remains open for continued analysis until explicitly closed
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the file to save |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a key behavioral trait: 'The file remains open for continued analysis until explicitly closed.' This goes beyond the name and schema. However, it does not mention prerequisites like requiring the file to be opened first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with action and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage timing, and persistence behavior. Missing a clear statement of prerequisites (e.g., file must be opened first) and any error conditions, which would make it more complete for a no-output-schema tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description 'Path to the file to save', and the tool description repeats this without adding syntactic or semantic detail. Thus the description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's action ('Save a file in the LSP server for analysis') and distinguishes it from sibling tools by tying it to the pre-analysis workflow. It explicitly mentions use before diagnostics/hover/completions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use context: 'Use this tool before performing operations...' It doesn't mention alternatives or when-not-to-use, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the server logging level. Use this tool to control the verbosity of logs generated by the LSP MCP server. Available levels from least to most verbose: emergency, alert, critical, error, warning, notice, info, debug. Increasing verbosity can help troubleshoot issues but may generate large amounts of output.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | The logging level to set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses the effect on log output volume and its troubleshooting value. It does not cover persistence or broader side effects, but for a simple setter this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, then adding the level list and warning. Every sentence contributes value; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an enum and no output schema, the description fully covers the purpose, parameter semantics, and usage caveats. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds meaning by listing the levels in order of verbosity (emergency to debug), which clarifies the semantic ordering of the enum values and the practical impact of choosing a level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the server logging level and controls log verbosity. It uses a specific verb ('Set') and resource ('server logging level'), and is easily distinguished from siblings, which handle document/LSP operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (to control verbosity and troubleshoot issues) and includes a caveat that increasing verbosity may generate large output. It does not explicitly mention alternatives, but no sibling tool serves the same purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the LSP server with a specified root directory. IMPORTANT: This tool must be called before using any other LSP functionality. The root directory should point to the project's base folder, which typically contains configuration files like tsconfig.json, package.json, or other language-specific project files. All file paths in other tool calls will be resolved relative to this root.
| Name | Required | Description | Default |
|---|---|---|---|
| root_dir | Yes | The root directory for the LSP server |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses that the tool must precede all other LSP calls and that file paths resolve relative to the root. It does not cover failure modes or return values, but the critical behavioral traits are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: what it does, when to call it, and how to set the parameter. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description covers purpose, usage constraints, parameter semantics, and behavioral effects on other tools. It is complete for the intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only describes root_dir as 'The root directory for the LSP server'. The description enriches this with concrete examples (tsconfig.json, package.json) and explains path resolution implications, which is critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Start' with a clear resource 'LSP server' and a required parameter 'root directory'. It clearly differentiates from sibling tools like get_completions or restart_lsp_server by establishing itself as the initialization step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'This tool must be called before using any other LSP functionality', providing an unambiguous usage condition. It also gives guidance on choosing the root directory with examples, making it clear when and how to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.0.7close_documentget_code_actionsget_completionsget_diagnosticsget_info_on_locationopen_documentrestart_lsp_serversave_documentset_log_levelstart_lspScored across 10 tools
Each tool addresses a distinct LSP operation, but save_document and open_document have identical descriptions, creating potential confusion about their respective roles. Hover, completions, code actions, diagnostics, and lifecycle tools are otherwise clearly separated.
Most tools follow a verb_noun pattern with get_ for queries and open/save/close for document management. Minor inconsistencies exist: start_lsp lacks 'server' while restart_lsp_server includes it, and get_info_on_location is more verbose than sibling get_ tools.
10 tools appropriately cover server lifecycle, document lifecycle, and core LSP queries without redundancy or bloat. This is well within the ideal 3-15 range for a focused MCP server.
The tool set covers the essential LSP workflow: start server, open documents, retrieve diagnostics, hover info, completions, and code actions. However, common LSP features like go-to-definition, find references, formatting, and rename are absent, leaving notable gaps for a full language server experience.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
