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.

• 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
  • get_diagnostics
  • get_class_members
  • get_method_signature
• 💡 Real-world Examples
  • Finding Function Definitions
  • Finding All References
  • Renaming Symbols
• 🔍 Troubleshooting
• 🤝 Contributing
• 📄 License

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

• Go to Definition: Find where symbols are defined
• Find References: Locate all references to a symbol
• Class Exploration: List all members of a class with their types
• Method Signatures: Get full method signatures with parameters and return types
• Code Diagnostics: Get errors, warnings, and hints for your code
• 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

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

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

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

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

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

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

npm install -g typescript-language-server typescript

pip install "python-lsp-server[all]"
# Or basic installation: 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: Download from LLVM releases

gem install solargraph

npm install -g intelephense

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

{
  "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"
      }
    }
  }
}

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

Alternatively, create an cclsp.json configuration file manually:

{
  "servers": [
    {
      "extensions": ["py", "pyi"],
      "command": ["uvx", "--from", "python-lsp-server", "pylsp"],
      "rootDir": "."
    },
    {
      "extensions": ["js", "ts", "jsx", "tsx"],
      "command": ["npx", "--", "typescript-language-server", "--stdio"],
      "rootDir": "."
    }
  ]
}

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

# 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

The server exposes these MCP tools:

Find the definition of a symbol at a specific position. Returns line/character numbers as 1-based for human readability.

Parameters:

• file_path: Absolute path to the file
• line: Line number (1-indexed by default; set use_zero_index to use 0-based indexing)
• character: Character position (0-based)
• use_zero_index: If true, use line number as-is (0-indexed); otherwise subtract 1 for 1-indexed input (optional, default: false)

Find all references to a symbol at a specific position. Returns line/character numbers as 1-based for human readability.

Parameters:

• file_path: Absolute path to the file
• line: Line number (1-indexed by default; set use_zero_index to use 0-based indexing)
• character: Character position (0-based)
• include_declaration: Whether to include the declaration (optional, default: true)
• use_zero_index: If true, use line number as-is (0-indexed); otherwise subtract 1 for 1-indexed input (optional, default: false)

Rename a symbol at a specific position in a file. Returns the file changes needed to rename the symbol across the codebase.

Parameters:

• file_path: Absolute path to the file
• line: Line number (1-indexed by default; set use_zero_index to use 0-based indexing)
• character: Character position (0-based)
• new_name: The new name for the symbol
• use_zero_index: If true, use line number as-is (0-indexed); otherwise subtract 1 for 1-indexed input (optional, default: false)

Get language diagnostics (errors, warnings, hints) for a file. Supports both pull-based (textDocument/diagnostic) and push-based (textDocument/publishDiagnostics) diagnostic reporting for maximum compatibility with different LSP servers.

Parameters:

• file_path: The path to the file

List all properties and methods of a class. Returns members with their types and signatures using LSP hover information, including namespace/package information and detailed parameter types.

Parameters:

• file_path: The path to the file containing the class
• class_name: The name of the class

Enhanced Response Includes:

• Full type signatures with documentation
• Namespace and package information for imported types
• Parameter details including names, types, optional flags, and default values
• Return type information for methods

Show full method definition with parameters and return type using LSP hover information. Particularly useful for understanding API methods and their expected parameters.

Parameters:

• file_path: The path to the file containing the method
• method_name: The name of the method
• class_name: Optional - The name of the class containing the method (helps narrow results)

Enhanced Response Includes:

• Complete method signature with all type information
• Parsed parameter details with types and default values
• Namespace/package information for complex types
• Documentation comments when available

When Claude needs to understand how a function works:

Claude: Let me find the definition of the `processRequest` function
> Using cclsp.find_definition at line 42, character 15

Result: Found definition at src/handlers/request.ts:127

When refactoring or understanding code impact:

Claude: I'll find all places where `CONFIG_PATH` is used
> Using cclsp.find_references at line 10, character 20

Results: Found 5 references:
- src/config.ts:10 (declaration)
- src/index.ts:45
- src/utils/loader.ts:23
- tests/config.test.ts:15
- tests/config.test.ts:89

Safe refactoring across the entire codebase:

Claude: I'll rename `getUserData` to `fetchUserProfile`
> Using cclsp.rename_symbol at line 55, character 10

Result: 12 files will be updated with the new name

When analyzing code quality:

Claude: Let me check for any errors or warnings in this file
> Using cclsp.get_diagnostics

Results: Found 3 diagnostics:
- Error [TS2304]: Cannot find name 'undefinedVar' (Line 10, Column 5)
- Warning [no-unused-vars]: 'config' is defined but never used (Line 25, Column 10)
- Hint: Consider using const instead of let (Line 30, Column 1)

When understanding API architecture:

Claude: Let me explore the ApiService class structure
> Using cclsp.get_class_members for class "ApiService"

Results: Found 8 members in class "ApiService":
• constructor (constructor) at src/services/api.ts:10:3
• baseUrl (property) at src/services/api.ts:12:3
  private baseUrl: string
  Type: string
• request (method) at src/services/api.ts:20:3
  async request<T>(endpoint: string, options?: RequestOptions): Promise<T>
  Parameters:
    - endpoint: string
    - options?: RequestOptions
  Returns: Promise<T>
• get (method) at src/services/api.ts:35:3
  async get<T>(endpoint: string): Promise<T>
  Parameters:
    - endpoint: string
  Returns: Promise<T>
• post (method) at src/services/api.ts:40:3
  async post<T>(endpoint: string, data: unknown): Promise<T>
  Parameters:
    - endpoint: string
    - data: unknown
  Returns: Promise<T>

When understanding function APIs:

Claude: I need to understand the formatDate method signature
> Using cclsp.get_method_signature for method "formatDate"

Method: formatDate at src/utils/date.ts:15:10
formatDate(date: Date | string, format?: string): string

Type Details:
  Parameters:
    - date: Date | string
    - format?: string = "YYYY-MM-DD"
  Returns: string

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

# For TypeScript
npm install -g typescript-language-server

# For Python
pip install python-lsp-server

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

We welcome contributions! Here's how you can help:

Found a bug or have a feature request? Open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Your environment (OS, Node version, etc.)

Want to add support for a new language?

1. Find the LSP server for your language
2. Test the configuration locally
3. Submit a PR with:
   • Updated README examples
   • Test files if possible
   • Configuration documentation

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: bun test
5. Commit: git commit -m '✨ feat: add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

MIT