Lsp Register

---
description: Register a project for LSP code intelligence. Auto-detects language and build system, or accepts explicit configuration. Handles C/C++ (clangd), Java/Kotlin (jdtls), Python (pyright), Rust (rust-analyzer), and custom LSP servers.
---

# 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.