cclsp - LLM-LSP Bridge (Model Context Protocol Server)

0.7.0 · active · verified Sun Apr 19

cclsp is a Model Context Protocol (MCP) server designed to bridge the gap between Large Language Model (LLM)-based coding agents and traditional Language Server Protocol (LSP) servers. It specifically addresses common frustrations where LLMs struggle with precise line/column numbers in LSP requests, employing intelligent position resolution and robust symbol handling to ensure accurate code navigation and refactoring. The current stable version is 0.7.0, indicating active development. While no explicit release cadence is provided, its iteration suggests regular updates. Key differentiators include its specialized handling of LLM positional ambiguities, an AI-friendly interface for MCP, and broad language support through configurable LSP servers (e.g., `typescript-language-server`, `pylsp`, `gopls`). It requires Node.js 18+ and a compatible TypeScript peer dependency for full functionality.

Common errors

```
Error: Language server '...' not found for file type '...'
```
cause The required LSP server for the specific language (e.g., 'typescript-language-server' for TypeScript) is not installed or not accessible in the system's PATH.

fix Install the missing language server (e.g., `npm install -g typescript-language-server`) and ensure it's in your system's PATH.
```
Error: Cannot find module 'typescript'
```
cause The 'typescript' peer dependency is missing from your project or global environment.

fix Install 'typescript' as a dependency: `npm install typescript` or `npm install -g typescript`.
```
SyntaxError: Unexpected token '...' (related to Node.js version)
```
cause You are running cclsp with an outdated Node.js version that does not support the JavaScript syntax or features used by the package.

fix Upgrade your Node.js installation to version 18 or higher.
```
MCP Request Error: Invalid JSON payload
```
cause The client (e.g., LLM agent) sent an MCP request that was not valid JSON or did not conform to the expected MCP message structure.

fix Verify that the MCP request payload is well-formed JSON and adheres to the required fields and types for the specific MCP method being called.

Warnings

gotcha cclsp requires Node.js 18 or newer. Running with older Node.js versions will lead to failures or unexpected behavior due to modern JavaScript features and API usage.
Fix: Upgrade your Node.js installation to version 18 or higher (e.g., using `nvm install 18` and `nvm use 18`).
gotcha cclsp acts as an LSP adapter but does not bundle the language servers themselves. You must separately install the necessary LSP servers (e.g., `typescript-language-server`, `pylsp`, `gopls`) for the languages you intend to use. These must be accessible in your system's PATH or explicitly configured.
Fix: Install the required language servers using their respective package managers (e.g., `npm install -g typescript-language-server`, `pip install 'python-lsp-server[all]'`).
gotcha For full TypeScript support and accurate type inference, a compatible version of `typescript` (as specified in the package's peer dependencies, e.g., `^5.8.3`) must be installed. This can be a project dependency or a global installation.
Fix: Install TypeScript: `npm install typescript@^5.8.3` in your project or `npm install -g typescript@^5.8.3` globally.
gotcha While cclsp handles positional inaccuracies from LLMs, the LLM agent is still responsible for constructing valid Model Context Protocol (MCP) requests. Incorrect MCP message structure (e.g., missing required fields, malformed JSON) will result in errors, regardless of positional adjustments.
Fix: Ensure your LLM or client generates MCP requests strictly according to the MCP specification expected by cclsp. Refer to the 'MCP Tools' section in the documentation.

Install

npm install cclsp npm
yarn add cclsp yarn
pnpm add cclsp pnpm

Imports

startCclspServer
wrong:
```
const { startCclspServer } = require('cclsp');
```
correct:
```
import { startCclspServer } from 'cclsp';
```
ESM-only since Node.js 18+ is required. This function starts the cclsp MCP server programmatically.
CclspConfig
```
import type { CclspConfig } from 'cclsp';
```
This type defines the configuration options for the cclsp server. Useful for programmatic configuration.
McpMessage
```
import type { McpMessage } from 'cclsp/types';
```
Represents the base interface for Model Context Protocol messages. Essential for building custom MCP clients or understanding server responses.

Quickstart

Initializes cclsp with an interactive setup wizard and demonstrates how to start the MCP server ready for requests.

npx cclsp@latest setup

# After setup, you can start the server (it will listen for MCP requests, usually via stdin/stdout)
# and then use an MCP tool to interact with it.
npx cclsp

# Example of sending an MCP request to the running server (conceptually):
# This shows how an AI agent might request a definition after the server is running.
# In practice, this would be sent over stdin/stdout or a socket by an MCP client.
# (Example: find definition for 'myFunction' in 'src/index.ts' at line 10, column 5)
# echo '{"jsonrpc":"2.0","method":"find_definition","params":{"uri":"file:///path/to/project/src/index.ts","position":{"line":10,"character":5},"symbolName":"myFunction"},"id":1}' | npx cclsp

# A more typical interactive usage with a client might be:
# npx cclsp setup --interactive
# # ... follow prompts ...
# npx cclsp # This starts the MCP server, waiting for input.

view raw JSON →