ballerina-ls

This MCP server provides a suite of analysis and tooling aimed at querying and analyzing the Ballerina Language Server codebase within the context of the Java language server integration. It exposes a collection of tools under the ballerin-language-server MCP entry that support code search, repository statistics, LSP protocol analysis, design pattern identification, dependencies, file structure, and more. You can use Claude Desktop to connect to this MCP server and access features such as advanced code search, class information extraction, repository-wide analytics, LSP capability discovery, and various quality/structure analyses for the Ballerina Language Server project. Tools include fuzzy code search, class/method introspection, protocol handler discovery, dependency mapping, design pattern detection, and code structure insights, all designed to help understand and navigate the codebase more efficiently. The server is designed to index the repository, analyze Java-based code, and provide structured results with relevance ranking, pagination, and summaries.

Typical workflows include performing a targeted search for relevant APIs (for example, searching for CompletionProvider-related classes), inspecting class definitions and methods, auditing repository statistics (file counts, top packages, largest classes), and analyzing LSP-related implementations and capabilities to understand how the server handles protocol messages. You can also re-index or re-scan the repository to pick up changes, and use dependency and pattern analyses to gain deeper architectural insights into the codebase.

Prerequisites

• Claude Desktop (or equivalent MCP client)
• Git (for cloning repositories)
• uv (Python/uv runtime) or an environment that can run the MCP server as configured

Setup and Installation

1. Clone the MCP server repository (if not already done).
2. Install dependencies using uv, which is used to run the Python-based MCP server:

uv sync

3. Ensure Claude Desktop (or your MCP client) is configured to point to the MCP server. The configuration example in the README shows adding the following entry to claude_desktop_config.json:

{
  "mcpServers": {
    "ballerina-language-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<PATH_TO_BALLERINA_LS_MCP_SERVER>",
        "run",
        "--active",
        "run.py"
      ],
      "env": {
        "BALLERINA_REPO_PATH": "<PATH_TO_BALLERINA_LANGUAGE_SERVER_REPO>"
      }
    }
  }
}

4. Restart Claude Desktop to apply the changes. After restarting, verify the MCP server appears under the Search and tools menu as ballerina-language-server.

Prerequisite notes

• You may need to adjust PATHS in the config JSON to point to the actual local paths for the MCP server and the Ballerina language server repository.
• Ensure file permissions allow reading the repository and launching uv run.py.
• Ballmerina-repo-path should point to the Ballerina Language Server codebase you want to analyze.

Tips and common issues:

• If you see a "Repository not indexed" error, ensure BALLERINA_REPO_PATH is set correctly and that the path exists and contains Java source files with read permissions.
• Initial indexing can take longer for large repos; allow time for the index to complete, and consider excluding non-essential directories to improve performance.
• The MCP tools support pagination and configurable result limits to prevent overly large responses; adjust limits as needed for your workflow.
• Environment variable configuration (e.g., BALLERINA_REPO_PATH) is critical for proper operation; verify paths are accessible from the runtime.
• Re-indexing (reindex_repository) helps pick up new changes after updates to the codebase.