cclsp - 不是普通的 LSP 适配器

cclsp 是一个模型上下文协议（MCP）服务器，可将基于 LLM 的编码助手与语言服务器协议（LSP）服务器无缝集成。基于 LLM 的编码助手通常难以提供准确的行号和列号，这使得简单地尝试与 LSP 服务器集成变得脆弱且令人沮丧。cclsp 通过智能地尝试多种位置组合，并提供强大的符号解析功能来解决这一问题，无论你的 AI 助手如何计算行数，它都能正常工作。

设置与使用演示

https://github.com/user-attachments/assets/52980f32-64d6-4b78-9cbf-18d6ae120cdd

目录

• 为什么选择 cclsp？
• 特性
• 📋 前置条件
• ⚡ 设置
  • 自动设置（推荐）
  • Claude Code 快速设置
  • 手动设置
  • 语言服务器安装
  • 验证
• 🚀 使用
  • 作为 MCP 服务器
  • 配置
• 🛠️ 开发
• 🔧 MCP 工具
  • find_definition
  • find_references
  • rename_symbol
  • rename_symbol_strict
  • get_diagnostics
  • restart_server
• 💡 现实世界示例
  • 查找函数定义
  • 查找所有引用
  • 重命名符号
• 🔍 故障排除
• 🤝 贡献
• 📄 许可证

为什么选择 cclsp？

在使用像 Claude 这样的 AI 驱动的编码助手时，你经常需要浏览代码库以理解符号之间的关系。cclsp 弥合了语言服务器协议功能与模型上下文协议之间的鸿沟，从而实现：

• 🔍 即时符号导航 - 无需手动搜索即可跳转到定义处
• 📚 完整引用查找 - 查找函数、变量和类型的全部用法
• ✏️ 安全的符号重命名 - 可以放心地在整个代码库中重命名符号
• 🌍 通用语言支持 - 适用于任何兼容 LSP 的语言服务器
• 🤖 AI 友好的接口 - 专为 LLM 设计，便于理解和有效使用

特性

• 转到定义：查找符号的定义位置
• 查找引用：定位符号的所有引用
• 多语言支持：可配置不同文件类型的 LSP 服务器
• TypeScript：通过 typescript-language-server 内置支持
• Python：通过 python-lsp-server (pylsp) 支持
• Go：通过 gopls 支持
• 以及更多：丰富的语言服务器配置

📋 前置条件

• Node.js 18+ 或 Bun 运行时
• 针对目标语言的语言服务器（需单独安装）

⚡ 设置

cclsp 提供了一个交互式设置向导，可自动完成整个配置过程。请选择您偏好的方法：

自动设置（推荐）

运行交互式设置向导：

# 一次性设置（无需安装）
npx cclsp@latest setup

# 对于用户范围的配置
npx cclsp@latest setup --user

设置向导将执行以下操作：

1. 🔍 自动检测项目中的语言，通过扫描文件进行识别
2. 📋 根据检测到的语言显示预选的 LSP 服务器
3. 📦 显示安装要求及详细指南
4. ⚡ 自动安装 LSP（可选，需用户确认）
5. 🔗 添加到 Claude MCP（可选，需用户确认）
6. ✅ 验证设置并显示可用工具

设置选项

• 项目配置（默认）：在当前目录下创建 .claude/cclsp.json
• 用户配置 (--user)：在 ~/.config/claude/cclsp.json 中创建全局配置

手动设置

如果您更倾向于手动配置：

1. 安装 cclsp：

   npm install -g cclsp
   

2. 安装语言服务器（请参阅 语言服务器安装）

3. 创建配置文件：

   # 使用交互式生成器
   cclsp setup
   
   # 或者手动创建（请参阅“配置”部分）
   

4. 添加到 Claude MCP：

   claude mcp add cclsp npx cclsp@latest --env CCLSP_CONFIG_PATH=/path/to/cclsp.json
   

液体服务器安装

设置向导会显示每个 LSP 的安装命令，但您也可以手动安装：

npm install -g typescript-language-server typescript

pip install "python-lsp-server[all]"
# 或基本安装：pip install python-lsp-server

go install golang.org/x/tools/gopls@latest

rustup component add rust-analyzer
rustup component add rust-src

# Ubuntu/Debian
sudo apt install clangd

# macOS
brew install llvm

# Windows：从 LLVM 发布版下载

gem install solargraph

npm install -g intelephense

🚀 使用

作为 MCP 服务器

在您的 MCP 客户端（例如 Claude Code）中进行配置：

使用 npm 包（全局安装后）

{
  "mcpServers": {
    "cclsp": {
      "command": "cclsp",
      "env": {
        "CCLSP_CONFIG_PATH": "/path/to/your/cclsp.json"
      }
    }
  }
}

使用本地安装

{
  "mcpServers": {
    "cclsp": {
      "command": "node",
      "args": ["/path/to/cclsp/dist/index.js"],
      "env": {
        "CCLSP_CONFIG_PATH": "/path/to/your/cclsp.json"
      }
    }
  }
}

配置

交互式配置生成器

为了方便设置，可以使用交互式配置生成器：

# 使用 npx（推荐用于一次性设置）
npx cclsp@latest setup

# 如果已全局安装
cclsp setup

# 或者直接使用开发版本运行
bun run setup

交互式工具将：

• 显示所有可用的语言服务器
• 让您通过直观的控件选择要配置的服务器：
  • 导航：使用 ↑/↓ 箭头键或 Ctrl+P/Ctrl+N（Emacs 风格）
  • 选择：按空格键切换，A 键全选/取消全选，I 键反选
  • 确认：按 Enter 键继续
• 展示所选语言的安装说明
• 自动生成配置文件
• 向您展示最终的配置

手动配置

或者，您可以手动创建一个 cclsp.json 配置文件：

{
  "servers": [
    {
      "extensions": ["py", "pyi"],
      "command": ["uvx", "--from", "python-lsp-server", "pylsp"],
      "rootDir": ".",
      "initializationOptions": {
        "settings": {
          "pylsp": {
            "plugins": {
              "jedi_completion": { "enabled": true },
              "jedi_definition": { "enabled": true },
              "jedi_hover": { "enabled": true },
              "jedi_references": { "enabled": true },
              "jedi_signature_help": { "enabled": true },
              "jedi_symbols": { "enabled": true },
              "pylint": { "enabled": false },
              "pycodestyle": { "enabled": false },
              "pyflakes": { "enabled": false }
            }
          }
        }
      }
    },
    {
      "extensions": ["js", "ts", "jsx", "tsx"],
      "command": ["npx", "--", "typescript-language-server", "--stdio"],
      "rootDir": "."
    }
  ]
}

配置选项：

• extensions：该服务器处理的文件扩展名数组
• command：用于启动 LSP 服务器的命令数组
• rootDir：LSP 服务器的工作目录（可选，默认为“.”）
• restartInterval：自动重启间隔（以分钟为单位，可选）
• initializationOptions：LSP 服务器的初始化选项（可选）

initializationOptions 字段允许您自定义每个 LSP 服务器的初始化方式。这对于像 pylsp（Python）这样具有丰富插件配置的服务器，或像 devsense-php-ls 这样需要特定设置的服务器来说特别有用。

{
  "servers": [
    {
      "extensions": ["go"],
      "command": ["gopls"],
      "rootDir": "."
    },
    {
      "extensions": ["rs"],
      "command": ["rust-analyzer"],
      "rootDir": "."
    },
    {
      "extensions": ["c", "cpp", "cc", "h", "hpp"],
      "command": ["clangd"],
      "rootDir": "."
    },
    {
      "extensions": ["java"],
      "command": ["jdtls"],
      "rootDir": "."
    },
    {
      "extensions": ["rb"],
      "command": ["solargraph", "stdio"],
      "rootDir": "."
    },
    {
      "extensions": ["php"],
      "command": ["intelephense", "--stdio"],
      "rootDir": "."
    },
    {
      "extensions": ["cs"],
      "command": ["omnisharp", "-lsp"],
      "rootDir": "."
    },
    {
      "extensions": ["swift"],
      "command": ["sourcekit-lsp"],
      "rootDir": "."
    }
  ]
}

🛠️ 开发

# 以开发模式运行
bun run dev

# 运行测试
bun test

# 运行手动集成测试
bun run test:manual

# 检查代码风格
bun run lint

# 格式化代码
bun run format

# 类型检查
bun run typecheck

🔧 MCP 工具

该服务器公开了以下 MCP 工具：

find_definition

根据文件中的名称和符号类型查找符号的定义。返回所有匹配符号的定义。

参数：

• file_path：文件路径
• symbol_name：符号名称
• symbol_kind：符号类型（函数、类、变量、方法等）（可选）

find_references

在整个工作区中查找符号的所有引用。返回所有匹配符号的引用。

参数：

• file_path：定义符号的文件路径
• symbol_name：符号名称
• symbol_kind：符号类型（函数、类、变量、方法等）（可选）
• include_declaration：是否包含声明（可选，默认为 true）

rename_symbol

根据文件中的名称和符号类型重命名符号。此工具现在默认会将重命名应用到所有受影响的文件。 如果有多个匹配的符号，则会返回候选位置，并建议使用 rename_symbol_strict。

参数：

• file_path：文件路径
• symbol_name：符号名称
• symbol_kind：符号类型（函数、类、变量、方法等）（可选）
• new_name：新名称
• dry_run：如果为真，则仅预览更改而不应用（可选，默认为假）

注意： 当 dry_run 为假时（默认），该工具会：

• 将重命名应用到所有受影响的文件
• 创建带有 .bak 扩展名的备份文件
• 返回已修改文件的列表。

rename_symbol_strict

在文件中的特定位置重命名符号。当 rename_symbol 返回多个候选位置时，请使用此工具。此工具现在默认会将重命名应用到所有受影响的文件。

参数：

• file_path：文件路径
• line：行号（从 1 开始计数）
• character：该行中的字符位置（从 1 开始计数）
• new_name：新名称
• dry_run：如果为真，则仅预览更改而不应用（可选，默认为假）

get_diagnostics

获取文件的语言诊断信息（错误、警告、提示）。使用 LSP 的 textDocument/diagnostic 方法来获取当前的诊断信息。

参数：

• file_path：要获取诊断信息的文件路径

restart_server

手动重启 LSP 服务器。可以针对特定文件扩展名重启服务器，也可以重启所有正在运行的服务器。

参数：

• extensions：要重启服务器的文件扩展名数组（例如，["ts", "tsx"]）。如果未提供，则会重启所有服务器（可选）

💡 实际案例

查找函数定义

当 Claude 需要理解某个函数的工作原理时：

Claude：让我找到 `processRequest` 函数的定义吧。
> 使用 cclsp.find_definition，设置 symbol_name="processRequest"，symbol_kind="function"

结果：在 src/handlers/request.ts 的第 127 行第 1 列找到了定义。

查找所有引用

在重构代码或了解代码影响时：

Claude：我要找出所有使用 `CONFIG_PATH` 的地方。
> 使用 cclsp.find_references，设置 symbol_name="CONFIG_PATH"

结果：找到了 5 处引用：
- src/config.ts 的第 10 行第 1 列（声明）
- src/index.ts 的第 45 行第 15 列
- src/utils/loader.ts 的第 23 行第 8 列
- tests/config.test.ts 的第 15 行第 10 列
- tests/config.test.ts 的第 89 行第 12 列

重命名符号

在整个代码库中安全地重构（现在会实际修改文件！）：

Claude：我要把 `getUserData` 重命名为 `fetchUserProfile`
> 使用 cclsp.rename_symbol，参数为 symbol_name="getUserData", new_name="fetchUserProfile"

结果：成功将 getUserData（函数）重命名为 "fetchUserProfile"。

修改的文件：
- src/api/user.ts
- src/services/auth.ts
- src/components/UserProfile.tsx
... （共12个文件）

在应用更改之前预览更改（使用 dry_run）：

Claude：我先预览一下哪些地方会被重命名
> 使用 cclsp.rename_symbol，参数为 symbol_name="getUserData", new_name="fetchUserProfile", dry_run=true

结果：[模拟运行] 将会把 getUserData（函数）重命名为 "fetchUserProfile"：
文件：src/api/user.ts
  - 第55行第10列至第55行第21列：“fetchUserProfile”
文件：src/services/auth.ts
  - 第123行第15列至第123行第26列：“fetchUserProfile”
... （共12个文件）

当有多个符号匹配时：

Claude：我要把 `data` 变量重命名为 `userData`
> 使用 cclsp.rename_symbol，参数为 symbol_name="data", new_name="userData"

结果：找到多个与 "data" 匹配的符号。请使用 rename_symbol_strict 并指定以下位置之一：
- data（变量）位于第45行第10列
- data（参数）位于第89行第25列
- data（属性）位于第112行第5列

> 使用 cclsp.rename_symbol_strict，参数为 line=45, character=10, new_name="userData"

结果：成功将第45行第10列处的符号重命名为 "userData"。

修改的文件：
- src/utils/parser.ts

检查文件诊断信息

在分析代码质量时：

Claude：让我检查一下这个文件有没有错误或警告
> 使用 cclsp.get_diagnostics

结果：发现3条诊断信息：
- 错误 [TS2304]：无法找到名称 'undefinedVar'（第10行第5列）
- 警告 [no-unused-vars]：'config' 已定义但从未使用过（第25行第10列）
- 提示：建议使用 const 而不是 let（第30行第1列）

重启 LSP 服务器

当 LSP 服务器无响应或配置发生更改时：

Claude：TypeScript 服务器似乎没有响应，我来重启它吧
> 使用 cclsp.restart_server，参数为 extensions ["ts", "tsx"]

结果：成功重启了1个 LSP 服务器
重启的服务器：
• typescript-language-server --stdio (ts, tsx)

或者重启所有服务器：

Claude：我要重启所有的 LSP 服务器，以确保它们正常工作
> 使用 cclsp.restart_server

结果：成功重启了2个 LSP 服务器
重启的服务器：
• typescript-language-server --stdio (ts, tsx)
• pylsp (py)

🔍 故障排除

已知问题

{
  "servers": [
    {
      "extensions": ["py", "pyi"],
      "command": ["pylsp"],
      "restartInterval": 5
    }
  ]
}

常见问题

# 对于 TypeScript
npm install -g typescript-language-server

# 对于 Python
pip install python-lsp-server

# 对于 Go
go install golang.org/x/tools/gopls@latest

🤝 贡献

我们欢迎您的贡献！以下是您可以帮助的方式：

报告问题

发现 bug 或有功能需求？请在 GitHub 上提交一个问题，内容包括：

• 清晰的问题描述
• 复现步骤
• 预期行为与实际行为的对比
• 您的环境信息（操作系统、Node.js 版本等）

添加语言支持

想为新语言添加支持吗？

1. 找到您所需语言的 LSP 服务器
2. 在本地测试配置
3. 提交一个 PR，包含：
   • 更新后的 README 示例
   • 如果可能，提供测试文件
   • 配置文档

代码贡献

1. 分支仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 进行更改
4. 运行测试：bun test
5. 提交：git commit -m '✨ feat: add amazing feature'
6. 推送：git push origin feature/amazing-feature
7. 打开一个拉取请求

📄 许可证

MIT

cclsp 快速上手指南

cclsp 是一个模型上下文协议（MCP）服务器，旨在将基于大语言模型（LLM）的编程助手（如 Claude）与语言服务器协议（LSP）无缝集成。它解决了 AI 在提供准确的行/列号时容易出错的问题，通过智能尝试多种位置组合，实现稳健的代码符号解析、跳转定义、查找引用和安全重命名。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 运行时环境：Node.js 18+ 或 Bun。
• 语言服务器：您需要为目标编程语言安装对应的 LSP 服务器（例如 TypeScript 需要 typescript-language-server，Python 需要 python-lsp-server 等）。cclsp 本身不包含这些服务器，需单独安装。
• MCP 客户端：已配置好 MCP 功能的 AI 编程助手（如 Claude Code）。

安装步骤

推荐使用交互式设置向导，它可以自动检测项目语言、安装必要的 LSP 服务器并生成配置文件。

1. 运行交互式设置向导

无需全局安装，直接使用 npx 运行最新版本的设置向导：

# 针对当前项目创建配置 (.claude/cclsp.json)
npx cclsp@latest setup

# 或者创建全局用户配置 (~/.config/claude/cclsp.json)
npx cclsp@latest setup --user

向导将自动执行以下操作：

1. 扫描项目文件，自动检测使用的编程语言。
2. 预选对应的 LSP 服务器。
3. 显示安装指南，并询问是否自动安装缺失的 LSP 服务器。
4. 询问是否将配置添加到 Claude MCP 中。
5. 验证设置并展示可用的工具。

2. 手动安装语言服务器（可选）

如果向导未自动安装，或您偏好手动管理，可根据需要安装常见的语言服务器：

# TypeScript/JavaScript
npm install -g typescript-language-server typescript

# Python
pip install "python-lsp-server[all]"

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer

# C/C++ (Ubuntu/Debian)
sudo apt install clangd

3. 配置 MCP 客户端

如果您使用交互式向导并确认了添加选项，配置会自动完成。若需手动配置，请在您的 MCP 配置文件（如 claude_desktop_config.json 或项目级配置）中添加以下内容：

{
  "mcpServers": {
    "cclsp": {
      "command": "npx",
      "args": ["cclsp@latest"],
      "env": {
        "CCLSP_CONFIG_PATH": "/path/to/your/cclsp.json" 
      }
    }
  }
}

注意：请将 /path/to/your/cclsp.json 替换为实际生成的配置文件路径。如果是全局配置，通常位于 ~/.config/claude/cclsp.json。

基本使用

配置完成后，重启您的 AI 编程助手。cclsp 会自动加载，您可以在对话中直接使用自然语言指令调用其功能，无需记忆复杂的命令。

使用示例

在支持 MCP 的聊天窗口中，您可以尝试以下指令：

1. 跳转定义 (Find Definition)

“帮我找到 calculateTotal 函数的定义在哪里。” 底层调用工具：find_definition

2. 查找所有引用 (Find References)

“列出项目中所有使用 UserService 类的地方。” 底层调用工具：find_references

3. 安全重命名 (Rename Symbol)

“把 oldVariableName 重命名为 newVariableName，并应用到所有相关文件。” 底层调用工具：rename_symbol 注：默认情况下会修改所有受影响的文件并创建 .bak 备份文件。

4. 获取诊断信息 (Get Diagnostics)

“检查当前文件有什么错误或警告？” 底层调用工具：get_diagnostics

cclsp 会自动处理文件路径和符号位置的复杂性，即使 AI 对行号的计算有细微偏差，它也能通过智能匹配准确定位代码符号。