cclsp

cclsp - not your average LSP adapter

cclsp is a Model Context Protocol (MCP) server that seamlessly integrates LLM-based coding agents with Language Server Protocol (LSP) servers. LLM-based coding agents often struggle with providing accurate line/column numbers, which makes naive attempts to integrate with LSP servers fragile and frustrating. cclsp solves this by intelligently trying multiple position combinations and providing robust symbol resolution that just works, no matter how your AI assistant counts lines.

Setup & Usage Demo

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

Table of Contents

• Why cclsp?
• Features
• 📋 Prerequisites
• ⚡ Setup
  • Automated Setup (Recommended)
  • Claude Code Quick Setup
  • Manual Setup
  • Language Server Installation
  • Verification
• 🚀 Usage
  • As MCP Server
  • Configuration
• 🛠️ Development
• 🔧 MCP Tools
  • find_definition
  • find_references
  • rename_symbol
  • rename_symbol_strict
  • get_diagnostics
  • restart_server
• 💡 Real-world Examples
  • Finding Function Definitions
  • Finding All References
  • Renaming Symbols
• 🔍 Troubleshooting
• 🤝 Contributing
• 📄 License

Why cclsp?

When using AI-powered coding assistants like Claude, you often need to navigate codebases to understand symbol relationships. cclsp bridges the gap between Language Server Protocol capabilities and Model Context Protocol, enabling:

• 🔍 Instant symbol navigation - Jump to definitions without manually searching
• 📚 Complete reference finding - Find all usages of functions, variables, and types
• ✏️ Safe symbol renaming - Rename across entire codebases with confidence
• 🌍 Universal language support - Works with any LSP-compatible language server
• 🤖 AI-friendly interface - Designed for LLMs to understand and use effectively

Features

• Go to Definition: Find where symbols are defined
• Find References: Locate all references to a symbol
• Multi-language Support: Configurable LSP servers for different file types
• TypeScript: Built-in support via typescript-language-server
• Python: Support via python-lsp-server (pylsp)
• Go: Support via gopls
• And many more: Extensive language server configurations

📋 Prerequisites

• Node.js 18+ or Bun runtime
• Language servers for your target languages (installed separately)

⚡ Setup

cclsp provides an interactive setup wizard that automates the entire configuration process. Choose your preferred method:

Automated Setup (Recommended)

Run the interactive setup wizard:

# One-time setup (no installation required)
npx cclsp@latest setup

# For user-wide configuration
npx cclsp@latest setup --user

The setup wizard will:

1. 🔍 Auto-detect languages in your project by scanning files
2. 📋 Show pre-selected LSP servers based on detected languages
3. 📦 Display installation requirements with detailed guides
4. ⚡ Install LSPs automatically (optional, with user confirmation)
5. 🔗 Add to Claude MCP (optional, with user confirmation)
6. ✅ Verify setup and show available tools

Setup Options

• Project Configuration (default): Creates .claude/cclsp.json in current directory
• User Configuration (--user): Creates global config in ~/.config/claude/cclsp.json

Manual Setup

If you prefer manual configuration:

1. Install cclsp:

   npm install -g cclsp
   

2. Install language servers (see Language Server Installation)

3. Create configuration file:

   # Use the interactive generator
   cclsp setup
   
   # Or create manually (see Configuration section)
   

4. Add to Claude MCP:

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

Language Server Installation

The setup wizard shows installation commands for each LSP, but you can also install them manually:

TypeScript/JavaScript

npm install -g typescript-language-server typescript

Python

pip install "python-lsp-server[all]"
# Or basic installation: pip install python-lsp-server

Go

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

Rust

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

C/C++

# Ubuntu/Debian
sudo apt install clangd

# macOS
brew install llvm

# Windows: Download from LLVM releases

Ruby

gem install solargraph

PHP

npm install -g intelephense

For more languages and detailed instructions, run npx cclsp@latest setup and select "Show detailed installation guides".

🚀 Usage

As MCP Server

Configure in your MCP client (e.g., Claude Code):

Using npm package (after global install)

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

Using local installation

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

Configuration

Interactive Configuration Generator

For easy setup, use the interactive configuration generator:

# Using npx (recommended for one-time setup)
npx cclsp@latest setup

# If installed globally
cclsp setup

# Or run directly with the development version
bun run setup

The interactive tool will:

• Show you all available language servers
• Let you select which ones to configure with intuitive controls:
  • Navigation: ↑/↓ arrow keys or Ctrl+P/Ctrl+N (Emacs-style)
  • Selection: Space to toggle, A to toggle all, I to invert selection
  • Confirm: Enter to proceed
• Display installation instructions for your selected languages
• Generate the configuration file automatically
• Show you the final configuration

Manual Configuration

Alternatively, create an cclsp.json configuration file manually:

{
  "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": "."
    }
  ]
}

Configuration Options:

• extensions: Array of file extensions this server handles
• command: Command array to spawn the LSP server
• rootDir: Working directory for the LSP server (optional, defaults to ".")
• restartInterval: Auto-restart interval in minutes (optional)
• initializationOptions: LSP server initialization options (optional)

The initializationOptions field allows you to customize how each LSP server initializes. This is particularly useful for servers like pylsp (Python) that have extensive plugin configurations, or servers like devsense-php-ls that require specific settings.

{
  "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": "."
    }
  ]
}

🛠️ Development

# Run in development mode
bun run dev

# Run tests
bun test

# Run manual integration test
bun run test:manual

# Lint code
bun run lint

# Format code
bun run format

# Type check
bun run typecheck

🔧 MCP Tools

The server exposes these MCP tools:

find_definition

Find the definition of a symbol by name and kind in a file. Returns definitions for all matching symbols.

Parameters:

• file_path: The path to the file
• symbol_name: The name of the symbol
• symbol_kind: The kind of symbol (function, class, variable, method, etc.) (optional)

find_references

Find all references to a symbol across the entire workspace. Returns references for all matching symbols.

Parameters:

• file_path: The path to the file where the symbol is defined
• symbol_name: The name of the symbol
• symbol_kind: The kind of symbol (function, class, variable, method, etc.) (optional)
• include_declaration: Whether to include the declaration (optional, default: true)

rename_symbol

Rename a symbol by name and kind in a file. This tool now applies the rename to all affected files by default. If multiple symbols match, returns candidate positions and suggests using rename_symbol_strict.

Parameters:

• file_path: The path to the file
• symbol_name: The name of the symbol
• symbol_kind: The kind of symbol (function, class, variable, method, etc.) (optional)
• new_name: The new name for the symbol
• dry_run: If true, only preview the changes without applying them (optional, default: false)

Note: When dry_run is false (default), the tool will:

• Apply the rename to all affected files
• Create backup files with .bak extension
• Return the list of modified files

rename_symbol_strict

Rename a symbol at a specific position in a file. Use this when rename_symbol returns multiple candidates. This tool now applies the rename to all affected files by default.

Parameters:

• file_path: The path to the file
• line: The line number (1-indexed)