Karellen Lsp MCP

LSP代码智能MCP服务器（karellen LSP-MCP）

  

](https://pypi.org/project/karellen-lsp-mcp/) ](https://pypi.org/project/karellen-lsp-mcp/) ](https://pypi.org/project/karellen-lsp-mcp/) ](https://pypi.org/project/karellen-lsp-mcp/) ](https://pypi.org/project/karellen-lsp-mcp/)

概述

karellen-lsp-mcp 通过以下方式为LLM客户端提供结构化代码智能 语言服务器协议 （语言服务器协议） 服务器。LLM可以查询定义， 引用、调用层次结构、类型层次结构、悬停文档、符号和 诊断——人类开发人员从IDE中获得的相同信息。

两个接口，一个守护进程：

• MCP接口 (karellen-lsp-mcp)：具有结构化响应的显式工具调用。

需要MCP工具批准或允许规则。

• LSP代理接口 (karellen-lsp)：Claude Code使用的本地LSP服务器

透明--没有权限提示，没有手动项目注册。自动检测 语言和到后端LSP服务器的路由。

建筑

每个项目的多个Claude会话共享单个守护进程和单个LSP服务器， 避免重复的服务器实例和冗余索引：

Claude Code LSP           Claude MCP Session 1      Claude MCP Session 2
     │ (stdio)                  │ (stdio)                  │ (stdio)
     ▼                          ▼                          ▼
┌─────────────┐          ┌─────────────┐          ┌─────────────┐
│  LSP proxy  │          │  MCP stdio  │          │  MCP stdio  │
│  frontend   │          │  frontend   │          │  frontend   │
└──────┬──────┘          └──────┬──────┘          └──────┬──────┘
       │ (Unix socket)          │                        │
       ▼                        ▼                        ▼
┌──────────────────────────────────────────────────────────────┐
│     karellen-lsp-mcp daemon                                  │
│                                                              │
│  Project Registry (refcounted)                               │
│    project-A  refcount=3  ──► clangd                         │
│    project-B  refcount=1  ──► jdtls                          │
└──────────────────────────────────────────────────────────────┘

• 守护进程：持久进程，拥有所有LSP服务器子进程和项目

注册表。在Unix域套接字上侦听。用户范围。第一次启动时自动启动 前端连接，空闲超时后自动退出，无连接。

• MCP前端：每个Claude会话都有精简的stdio进程。连接到守护进程、代理

MCP工具调用。返回结构化数据（数据类）以进行快速LLM处理。

• LSP代理前端：标准LSP服务器通过stdio。自动检测语言

initialize，注册项目，将LSP请求路由到正确的后端。 重复使用与MCP相同的适配器、归一化器和就绪跟踪。

支持的语言

项目在以下情况下自动检测 language 省略了 lsp_register_project，或 通过以下方式明确检查 lsp_detect_project检测扫描构建系统标记， IDE元数据（JetBrains .idea/Eclipse、VS Code）和源文件约定。

需求

• python >= 3.10
• LSP服务器 适用于您的语言，已安装并位于PATH上
• Linux 或 macOS （使用Unix域套接字；Windows 10 build 17063+也适用）

安装

pip install --user karellen-lsp-mcp

使用LSP服务器依赖项进行安装：

pip install --user karellen-lsp-mcp[clangd]         # C/C++ support
pip install --user karellen-lsp-mcp[jdtls]          # Java/Kotlin support
pip install --user karellen-lsp-mcp[pyright]        # Python support
pip install --user karellen-lsp-mcp[all]            # All LSP servers
# Rust: rustup component add rust-analyzer

或者使用pipx用于隔离环境：

pipx install 'karellen-lsp-mcp[all]'

Claude代码集成

插件安装（推荐）

该插件在一个包中提供了两个接口：

• 本地LSP服务器 (karellen-lsp)：透明的代码智能——Claude code使用

对于支持的文件类型，它会自动执行。无权限提示，无需手动注册。 自动检测来自CWD的语言，并将其路由到后端LSP服务器。

• MCP工具 (karellen-lsp-mcp)：具有结构化响应的显式工具调用，以及

钩子（先决条件检查、编译器错误检测）， 技能(/karellen-lsp-mcp:lsp-register, /karellen-lsp-mcp:lsp-investigate)，以及 自主的 lsp-investigator 代理人。

两者共享相同的守护进程——MCP注册的项目对本机LSP查询可见 反之亦然。

来自Karellen市场：

claude plugin marketplace add karellen/claude-plugins
claude plugin install karellen-lsp-mcp@karellen-plugins

从本地结账：

claude --plugin-dir /path/to/karellen-lsp-mcp

手动MCP配置（备选）

如果您不想使用插件系统，请直接配置MCP服务器：

claude mcp add --transport stdio karellen-lsp-mcp -- karellen-lsp-mcp

或手动添加到 ~/.claude.json （用户范围）或 .mcp.json 在项目根目录中 （项目范围，通过版本控制共享）：

{
  "mcpServers": {
    "karellen-lsp-mcp": {
      "type": "stdio",
      "command": "karellen-lsp-mcp"
    }
  }
}

如果与pipx一起安装：

claude mcp add --transport stdio karellen-lsp-mcp -- pipx run karellen-lsp-mcp

或手动：

{
  "mcpServers": {
    "karellen-lsp-mcp": {
      "type": "stdio",
      "command": "pipx",
      "args": ["run", "karellen-lsp-mcp"]
    }
  }
}

注意：手动MCP配置仅提供工具，没有挂钩、技能或代理。

自动批准MCP工具

本地LSP接口不需要批准——Claude Code透明地使用它。

对于MCP工具，默认情况下Claude Code会提示确认。要自动批准，请添加 用户设置的权限规则 (~/.claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__karellen-lsp-mcp__*",
      "mcp__plugin_karellen-lsp-mcp_karellen-lsp-mcp__*"
    ]
  }
}

或者，对于项目范围的设置，将相同的规则添加到 .claude/settings.json 在你的 项目根目录（此文件可以提交给版本控制，以便所有团队成员都能获得它）。

教克劳德LSP工作流程

克劳德会自动发现所有 lsp_* 工具，但教它 何时与如何 到 有效地使用它们，将以下内容添加到您的项目中 CLAUDE.md:

## LSP Code Intelligence

### When to Use LSP Tools

Use the `lsp_*` MCP tools for navigating and understanding codebases — especially when
you need to trace call chains, find all references to a symbol, understand type
hierarchies, or check compiler diagnostics without reading entire files.

### Setup

Register your project once at the start of a session. Do NOT ask the user for
configuration details. Do NOT narrate intermediate steps. Do the entire setup
(search, generate if needed, register) in one action sequence without pausing for
confirmation.

**C/C++ projects** use clangd as the default LSP server. clangd needs a
`compile_commands.json` for accurate results. Most projects don't have one pre-built.
Do all of this in one go:

1. Search for an existing `compile_commands.json` — use `Glob` to check the project
   tree. Also check if there's an existing build directory (look for `build/`,
   `cmake-build-*/`, `out/`, or a `compile_commands.json` symlink in the project root).
2. If not found, detect the build system and generate it:
   - `CMakeLists.txt` → check if there's already a build directory with cmake cache
     (in-tree or out-of-tree). If an existing build dir has `CMakeCache.txt`, re-run
     cmake there with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`. Otherwise run
     `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build`.
   - `meson.build` → `meson setup build` (generates it automatically)
   - `Makefile`/`configure`/autotools → use Bear if available (`bear -- make`), or
     run `make -n` to get compiler commands and write `compile_commands.json` yourself
   - No build system → register without `build_info` (clangd still works for basics)
3. Register immediately — don't ask for confirmation:

lsp_register_project( project_path="/path/to/project", language="cpp", # or "c" build_info={"compile_commands_dir": "/path/to/dir/containing/compile_commands.json"} )

**Other languages**: pass a custom `lsp_command`:

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

### Key Rules

- **Use LSP instead of grepping**: `lsp_find_references` is semantically aware — it finds
  actual references, not string matches. It won't return comments, strings, or unrelated
  symbols with the same name
- **Hover before reading**: `lsp_hover` gives you the type signature and documentation
  for any symbol — often enough to understand usage without reading the full definition
- **Call hierarchy for impact analysis**: before changing a function, use
  `lsp_call_tree_incoming` to get the full recursive call tree in one shot, or
  `lsp_call_hierarchy_incoming` for a single level
- **Single-file queries work immediately**: `lsp_read_definition`, `lsp_hover`, and
  `lsp_document_symbols` don't wait for background indexing. Use these freely even on
  large codebases that are still indexing
- **Cross-file queries wait for indexing automatically**: `lsp_find_references`,
  call hierarchy, type hierarchy, and `lsp_diagnostics` wait for indexing to finish,
  with the timeout extending automatically as long as progress is being made. No need
  to poll or sleep. Use `lsp_indexing_status(project_id)` to check progress on large
  codebases
- **All positions are 1-based**: line and character offsets in both input and output
  start at 1. Values from one tool's output (e.g. `lsp_workspace_symbols`) can be
  fed directly into another tool's input (e.g. `lsp_read_definition`)
- **Stale compile_commands.json is auto-detected**: if build config files
  (`CMakeLists.txt`, `meson.build`) are newer than `compile_commands.json`, or
  5% or more of referenced source files no longer exist, the server regenerates
  it automatically for CMake/Meson projects. For other build systems, the stale
  file is used with a warning. Use `lsp_regenerate_index` to force regeneration
- **Per-tool timeout**: all tools accept an optional `timeout` parameter (seconds)
  to override the default readiness timeout for that call. Useful for large
  codebases or debugging timeout issues
- **Deregister when done**: `lsp_deregister_project` takes the `registration_id` returned
  by register; the LSP server shuts down when all registrations are released

可用工具

项目生命周期

代码导航

符号和结构

诊断

结构化响应

所有工具都返回结构化数据（数据类），而不是纯文本。这实现了快速LLM 无需解析即可处理。示例：

lsp_read_definition 回报 LocationResult:

{
  "locations": [
    {"file": "/path/to/impl.cpp", "line": 42, "character": 5}
  ]
}

lsp_document_symbols 回报 DocumentSymbolsResult:

{
  "symbols": [
    {"name": "MyClass", "kind": "Class", "line": 10, "children": [
      {"name": "method1", "kind": "Method", "line": 12},
      {"name": "method2", "kind": "Method", "line": 18}
    ]}
  ]
}

lsp_call_hierarchy_incoming 回报 CallHierarchyResult:

{
  "direction": "incoming",
  "items": [
    {"name": "main", "kind": "Function", "file": "/path/to/main.cpp", "line": 5, "call_sites": 1}
  ],
  "indexing": true
}

lsp_call_tree_incoming 回报 CallTreeResult （递归，默认深度3）：

{
  "direction": "incoming",
  "root": {
    "name": "target_func", "kind": "Function", "file": "/path/to/file.cpp", "line": 42,
    "call_sites": 1,
    "children": [
      {"name": "caller_a", "kind": "Function", "file": "/path/to/a.cpp", "line": 10,
       "call_sites": 2, "has_more": true, "children": [
        {"name": "main", "kind": "Function", "file": "/path/to/main.cpp", "line": 5,
         "call_sites": 1, "children": []}
      ]},
      {"name": "caller_b", "kind": "Function", "file": "/path/to/b.cpp", "line": 20,
       "call_sites": 1, "children": []}
    ]
  },
  "indexing": false
}

节点与 has_more: true 有更深层次的可用资源——增加 max_depth 探索。

跨文件查询包括 "indexing": true 当LSP服务器仍在构建其 索引，表明结果可能不完整。

lsp_indexing_status 回报 IndexingStatusResult:

{
  "state": "indexing",
  "elapsed_seconds": 45.2,
  "active_tasks": [
    {"title": "indexing", "message": "loading index shards", "percentage": 30}
  ],
  "completed_tasks": 2
}

配置

超时

所有超时都可以通过环境变量（以秒为单位）进行配置。将它们设置在您的 MCP服务器配置：

{
  "mcpServers": {
    "karellen-lsp-mcp": {
      "type": "stdio",
      "command": "karellen-lsp-mcp",
      "env": {
        "LSP_MCP_READY_TIMEOUT": "300",
        "LSP_MCP_REQUEST_TIMEOUT": "120"
      }
    }
  }
}

每工具超时

所有工具都接受可选 timeout 参数（以秒为单位），用于覆盖 守护进程对该特定调用的默认准备超时。这对 调试或需要更多时间索引的大型代码库：

lsp_find_references(project_id="", file_path="...", line=42, character=10, timeout=300)

默认超时：生命周期工具（扫描、检测、注销、列表、索引状态）为30秒， 120秒用于查询工具和注册。

环境变量

对于大型代码库（例如LLVM、Linux内核），跨文件查询超时会延长 只要索引正在进行，就会自动执行。单文件查询（定义， 悬停、文档符号）只等待服务器启动，不等待索引。确保 LSP_MCP_CLIENT_TIMEOUT 超出预期的最大索引时间+ LSP_MCP_REQUEST_TIMEOUT.

使用cland进行C/C++设置

compile_commands.json

cland需要一个 编译数据库 要了解项目的构建标志，请包含路径和定义。生成一个：

CMake：

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build

熊（任何构建系统）：

bear -- make

Meson：

meson setup build  # compile_commands.json is generated automatically

然后在包含以下内容的目录中注册 compile_commands.json:

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

背景索引

对于大型项目，请通过 --background-index 为了实现跨文件功能，请点击cland：

lsp_register_project(
    project_path="/path/to/project",
    language="cpp",
    lsp_command=["clangd", "--background-index"],
    build_info={"compile_commands_dir": "/path/to/build"}
)

安装cland

Fedora/RHEL/CentOS：

sudo dnf install clang-tools-extra

Ubuntu/Debian：

sudo apt install clangd

Arch Linux：

sudo pacman -S clang

macOS：

brew install llvm

故障排除

守护程序文件

守护进程将其文件存储在平台标准目录中（通过 平台):

如果守护进程进入不良状态，请删除套接字文件，它将重新启动 在下次MCP工具调用时自动执行。检查 daemon.log 诊断碰撞或 意想不到的行为。

LSP服务器未启动

如果工具返回有关LSP服务器的错误，请检查：

1. LSP服务器二进制文件位于PATH上（例如。 which clangd)
2. 项目路径是绝对路径
3. 对于C/C++， compile_commands.json 存在于指定的 compile_commands_dir

索引过程中的结果不完整

自动进行跨文件查询（引用、调用层次结构、类型层次结构、诊断） 等待索引完成，超时时间根据进度动态延长。 如果查询在索引仍在进行时完成（例如，服务器已“准备就绪”） 在完全索引完成之前），响应包括 indexing: true 标志--结果 可能不完整。使用 lsp_indexing_status 检查进度或稍后重新查询。 单文件查询（定义、悬停、文档符号）总是立即工作。

调试

集 LSP_MCP_LOG_LEVEL 以控制LSP代理和守护进程的日志冗长度。 价值观： DEBUG, INFO （默认）， WARNING, ERROR.

LSP代理日志 转到stderr。当由Claude Code启动时，使用 claude --debug 到 请参阅LSP服务器输出。对于独立测试：

LSP_MCP_LOG_LEVEL=DEBUG karellen-lsp 2>lsp-debug.log

守护进程日志 写信给 daemon.log （位置见上表）。启用 调试日志记录，杀死守护进程并使用env-var集重新启动：

pkill -f "karellen_lsp_mcp.daemon"
LSP_MCP_LOG_LEVEL=DEBUG karellen-lsp-mcp  # daemon auto-starts with debug level

过时的守护进程

如果你更新 karellen-lsp-mcp 对于新版本，正在运行的守护进程可能仍然是 旧版本。杀死守护进程以强制重新启动：

pkill -f "karellen_lsp_mcp.daemon"

下一个MCP工具调用或LSP查询将自动启动新版本。

许可证

阿帕奇-2.0