LSP Project Registration

LSP Project Registration

Use this skill to register a project for LSP-backed code intelligence. Once registered, all lsp_* query tools become available for that project.

Prerequisites

• karellen-lsp-mcp must be installed and on PATH
• An LSP server for the target language:
  • C/C++: clangd — install via pip install --user karellen-lsp-mcp[clangd] or system package manager
  • Java/Kotlin: jdtls — install via pip install --user karellen-lsp-mcp[jdtls]
  • Python: pyright — install via pip install --user karellen-lsp-mcp[pyright]
  • Rust: rust-analyzer — install via rustup component add rust-analyzer
  • All servers: pip install --user karellen-lsp-mcp[all]
  • Other languages: any LSP server, specified via lsp_command

Workflow

1. Scan or Detect the Project (Optional)

Quick scan — count file extensions and see what languages are present:

lsp_scan_languages(project_path="/path/to/project")

Full detection — analyze build systems, IDE metadata, and configuration:

lsp_detect_project(project_path="/path/to/project")

Both return language recommendations without registering anything. Use scan for a quick overview, detect for build system details and configuration.

2. Register the Project

Auto-Detection (Recommended)

Omit the language parameter to let the server auto-detect:

lsp_register_project(project_path="/path/to/project")

Auto-detection scans for build system markers (CMakeLists.txt, build.gradle, pom.xml, pyproject.toml, Cargo.toml, etc.), IDE metadata (.idea/, .classpath, .vscode/), and source file conventions.

Explicit Language

Specify the language when auto-detection isn't sufficient:

lsp_register_project(project_path="/path/to/project", language="cpp")

C/C++ with compile_commands.json

For best results with clangd, provide the compile database location:

lsp_register_project(
    project_path="/path/to/project",
    language="cpp",
    build_info={"compile_commands_dir": "/path/to/build"}
)

If not provided, the adapter searches for compile_commands.json in common locations and generates one for CMake/Meson projects automatically. Generated files go to a platform-specific data directory (never pollutes the project tree).

Generating compile_commands.json manually:

• CMake: cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build
• Meson: meson setup build (generates automatically)
• Bear (any build system): bear -- make

Java/Kotlin with jdtls

jdtls handles both Java and Kotlin via karellen-jdtls-kotlin:

lsp_register_project(project_path="/path/to/project", language="java")

For multi-module Gradle projects, register the root (where settings.gradle is):

lsp_register_project(project_path="/path/to/gradle-root", language="java")

Python with pyright

lsp_register_project(project_path="/path/to/project", language="python")

Virtual environments are detected automatically. To specify one explicitly:

lsp_register_project(
    project_path="/path/to/project",
    language="python",
    build_info={"venv_path": "/path/to/.venv"}
)

Rust with rust-analyzer

Register at the directory containing Cargo.toml:

lsp_register_project(project_path="/path/to/crate", language="rust")

For Cargo workspaces, register at any member crate — the workspace root is detected automatically. Do NOT register at a parent directory that has no Cargo.toml.

Custom LSP Server

For languages without a built-in adapter:

lsp_register_project(
    project_path="/path/to/project",
    language="go",
    lsp_command=["gopls"]
)

3. Wait for Indexing (Large Codebases)

Single-file queries (definition, hover, symbols) work immediately. Cross-file queries (references, call hierarchy, diagnostics) wait for indexing automatically with progress-driven timeout extension.

Check indexing progress on large codebases:

lsp_indexing_status(project_id="<id>")

4. Use LSP Query Tools

All queries use the project_id returned by registration:

• lsp_read_definition — go to definition
• lsp_read_declaration — go to declaration (header/interface)
• lsp_read_type_definition — go to the type definition of a variable
• lsp_find_references — find all references
• lsp_find_implementations — find all implementations of interface/abstract
• lsp_hover — type signature and documentation
• lsp_document_symbols — list symbols in a file
• lsp_workspace_symbols — search symbols across the project by name
• lsp_call_tree_incoming / lsp_call_tree_outgoing — recursive call trees (preferred)
• lsp_call_hierarchy_incoming / lsp_call_hierarchy_outgoing — single-level call chains
• lsp_type_tree_supertypes / lsp_type_tree_subtypes — recursive type trees (preferred)
• lsp_type_hierarchy_supertypes / lsp_type_hierarchy_subtypes — single-level type info
• lsp_diagnostics — compiler errors and warnings

5. Deregister When Done

lsp_deregister_project(registration_id="<registration_id>")

This decrements the refcount using the unique registration_id returned by lsp_register_project. Each token can only be used once. The LSP server stops when all registrations are released.

Key Rules

• NEVER run build system commands (cmake, make, meson, cargo build, gradle, mvn, pip install, etc.) on the user's project. The LSP adapter handles build configuration automatically. If compile_commands.json is missing for C/C++, register the project anyway — clangd still works without it, and the adapter generates one for CMake/Meson in a managed directory without polluting the project tree.
• Register at the language-specific project root, not the repository root. In monorepos or polyglot projects, use lsp_detect_project first to find the correct root for each language (where Cargo.toml, pyproject.toml, CMakeLists.txt, etc. lives). Registering at a parent directory that lacks the language's build system marker will fail or produce no results.
• Register once per session. Multiple registrations of the same project share one LSP server instance (refcounted).
• Use force=True to restart. If the LSP server gets into a bad state, re-register with force=True to kill and restart it.
• Use regenerate=True to rebuild from scratch. Cleans all managed data (compilation databases, workspace caches) and force-restarts the LSP server. Equivalent to lsp_regenerate_index but available directly on lsp_register_project.
• All positions are 1-based. Line and character offsets start at 1.
• All tools accept timeout. Optional timeout parameter (seconds) overrides the default readiness timeout. Defaults: 30s for lifecycle tools, 120s for query tools.
• Cross-file queries include indexing status. Check the indexing field in results; if true, results may be incomplete.