cclsp

The project is undergoing a refactoring process divided into two main phases to improve modularity, stability, and observability.

Phase 1: Structural Refactoring

Focuses on decomposing the monolithic lsp-client.ts into specialized modules while preserving existing behavior. Key modules being extracted include:

• src/lsp/types.ts: Centralized LSP and internal types.
• src/lsp/json-rpc.ts: Message framing and ID correlation.
• src/lsp/config.ts: Configuration loading and validation.
• src/lsp/document-manager.ts: Tracking didOpen, didChange, and didClose events.
• src/lsp/server-manager.ts: Server lifecycle (spawn, restart) and adapter integration.
• src/lsp/diagnostics.ts: Diagnostics caching.
• src/lsp/operations.ts: Orchestration of LSP operations.
• src/tools/registry.ts: Declarative tool definitions.

Phase 2: Quality Improvements

Focuses on enhancing the developer and user experience:

• Logging: Adding a structured logger controlled by the CCLSP_LOG_LEVEL environment variable.
• Adapter Interface: Cleaning up the adapter interface and implementing customizeInitializeParams.
• Resilience: Implementing graceful degradation so individual server failures do not crash the entire MCP process.
• Version Accuracy: Ensuring the MCP server version matches package.json.

cclsp is an MCP server that integrates LLM-based coding agents with LSP servers. You can set it up using an automated interactive wizard or manually.

Automated Setup (Recommended)

Run the interactive wizard to auto-detect languages, install required LSPs, and configure Claude MCP.

• Project-specific configuration: Creates .claude/cclsp.json in the current directory.
• User-wide configuration: Creates a global config in ~/.config/claude/cclsp.json using the --user flag.

# Project-specific setup
npx cclsp@latest setup

# Global user-wide setup
npx cclsp@latest setup --user

Manual Setup

1. Install cclsp globally: npm install -g cclsp.
2. Install the required language servers for your target languages (e.g., gopls for Go, typescript-language-server for TS).
3. Create a configuration file (see Manual Configuration).
4. Add to Claude MCP:

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

The ServerState interface represents the internal state of a running LSP server process. It manages the underlying ChildProcess, the communication transport, the documentManager for file lifecycle, and a diagnosticsCache for managing errors and warnings.

Note: This is an internal interface used by the core engine to track server health, initialization status, and document versions. It is not intended for direct user extension.

export interface ServerState {
  process: ChildProcess;
  transport: {
    sendRequest(method: string, params: unknown, timeout?: number): Promise<unknown>;
    sendMessage(message: LSPMessage): void;
    sendNotification(method: string, params: unknown): void;
    rejectAllPending(reason: string): void;
  };
  documentManager: {
    ensureOpen(filePath: string): Promise<boolean>;
    sendChange(filePath: string, text: string): void;
    isOpen(filePath: string): boolean;
    getVersion(filePath: string): number;
  };
  initialized: boolean;
  initializationPromise: Promise<void>;
  startTime: number;
  config: LSPServerConfig;
  restartTimer?: NodeJS.Timeout;
  initializationResolve?: () => void;
  diagnosticsCache: {
    update(uri: string, items: Diagnostic[], version?: number): void;
    get(uri: string): Diagnostic[] | undefined;
    waitForIdle(
      uri: string,
      options?: {
        maxWaitTime?: number;
        idleTime?: number;
        checkInterval?: number;
      }
    ): Promise<void>;
  };
  adapter?: ServerAdapter;
}

cclsp uses a JSON configuration file to map file extensions to specific LSP server commands. You can generate this file using the interactive setup command or create it manually.

Configuration Schema

Each object in the servers array supports:

• extensions: (Array) File extensions this server handles (e.g., ["py", "pyi"]).
• command: (Array) The command and arguments used to spawn the LSP server.
• rootDir: (String, optional) Working directory for the LSP server. Defaults to ".".
• restartInterval: (Number, optional) Auto-restart interval in minutes.
• initializationOptions: (Object, optional) LSP server initialization options, used for passing specific settings (like pylsp plugins) to the underlying server.

Example: Python (pylsp) with plugins

{
  "servers": [
    {
      "extensions": ["py", "pyi"],
      "command": ["uvx", "--from", "python-lsp-server", "pylsp"],
      "rootDir": ".",
      "initializationOptions": {
        "settings": {
          "pylsp": {
            "plugins": {
              "jedi_completion": { "enabled": true },
              "pylint": { "enabled": false }
            }
          }
        }
      }
    }
  ]
}

{
  "servers": [
    {
      "extensions": ["js", "ts", "jsx", "tsx"],
      "command": ["npx", "--", "typescript-language-server", "--stdio"],
      "rootDir": "."
    }
  ]
}