### Run cclsp Interactive Setup (npx)

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Initiates the interactive setup process for cclsp using npx. This is recommended for a one-time setup and guides through language server selection and configuration generation.

```bash
npx cclsp@latest setup
```

--------------------------------

### Run cclsp Interactive Setup (global)

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Initiates the interactive setup process for cclsp when the package is installed globally. This command guides through language server selection and configuration generation.

```bash
cclsp setup
```

--------------------------------

### Run the cclsp setup wizard

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Use these commands to initiate the interactive setup process for project-specific or global configurations.

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

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

--------------------------------

### Install C/C++ Language Server (clangd)

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the clangd language server for C/C++ development. Installation methods vary by operating system.

```bash
# Ubuntu/Debian
sudo apt install clangd

# macOS
brew install llvm

# Windows: Download from LLVM releases
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using Bun. This command should be run after cloning the repository.

```bash
bun install
```

--------------------------------

### Install Go Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the Go language server (gopls) using the go command. Ensure you have Go installed and configured.

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

--------------------------------

### Configure cclsp using local installation

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Example JSON configuration for cclsp when using a local installation as an MCP server. Specifies the command, arguments, and environment variables.

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

--------------------------------

### Install PHP Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the intelephense language server for PHP development using npm.

```bash
npm install -g intelephense
```

--------------------------------

### Run cclsp setup wizard

Source: https://context7.com/ktnyt/cclsp/llms.txt

Use the interactive wizard to configure cclsp for the current project or globally.

```bash
# Run interactive setup wizard (project-level configuration)
npx cclsp@latest setup

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

--------------------------------

### Install Python Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the Python language server using pip. You can choose a basic installation or one with all features.

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

--------------------------------

### Run cclsp Interactive Setup (development)

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Initiates the interactive setup process for cclsp using the development version. This command is useful for testing or when running directly from a cloned repository.

```bash
bun run setup
```

--------------------------------

### Run the Development Server

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Start the development server to test your changes manually. This command is useful for interactive testing during development.

```bash
bun run dev
```

--------------------------------

### Install Python Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Install the Python language server using pip. This is necessary for Python support.

```bash
pip install python-lsp-server
```

--------------------------------

### Install cclsp and language servers

Source: https://context7.com/ktnyt/cclsp/llms.txt

Install the cclsp package and necessary language servers for various programming languages.

```bash
# Install globally via npm
npm install -g cclsp

# Install required language servers
npm install -g typescript-language-server typescript  # TypeScript/JavaScript
pip install "python-lsp-server[all]"                  # Python
go install golang.org/x/tools/gopls@latest            # Go
rustup component add rust-analyzer rust-src           # Rust
```

--------------------------------

### Install cclsp Globally

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the cclsp package globally using npm. This command is part of the manual setup process.

```bash
npm install -g cclsp
```

--------------------------------

### Install Ruby Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the Solargraph language server for Ruby development using the gem command.

```bash
gem install solargraph
```

--------------------------------

### Install TypeScript/JavaScript Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the TypeScript and JavaScript language server using npm. This is a common language server that can be installed manually.

```bash
npm install -g typescript-language-server typescript
```

--------------------------------

### Additional Language Server Examples for CCLSP Configuration

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Provides examples of `cclsp.json` configurations for various programming languages including Go, Rust, C/C++, Java, Ruby, PHP, C#, and Swift.

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

--------------------------------

### Configure cclsp using npm package

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Example JSON configuration for cclsp when using the globally installed npm package as an MCP server. Specifies the command and environment variables.

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

--------------------------------

### Define LSP Server Configuration

Source: https://github.com/ktnyt/cclsp/blob/main/CLAUDE.md

Example configuration file structure for mapping file extensions to specific LSP server commands and restart intervals.

```json
{
  "servers": [
    {
      "extensions": ["py"],
      "command": ["pylsp"],
      "restartInterval": 5
    },
    {
      "extensions": ["ts", "tsx", "js", "jsx"],
      "command": ["typescript-language-server", "--stdio"],
      "restartInterval": 10
    }
  ]
}
```

--------------------------------

### Install Rust Language Server Components

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Installs the rust-analyzer component and source code for Rust development. This requires the rustup toolchain manager.

```bash
rustup component add rust-analyzer
rustup component add rust-src
```

--------------------------------

### Install TypeScript Language Server

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Install the TypeScript language server globally using npm. This is required for TypeScript support.

```bash
npm install -g typescript-language-server
```

--------------------------------

### Execute Development Commands

Source: https://github.com/ktnyt/cclsp/blob/main/CLAUDE.md

Standard commands for managing the development lifecycle, including dependency installation, building, and quality assurance.

```bash
# Install dependencies
bun install

# Development with hot reload
bun run dev

# Build for production
bun run build

# Run the built server
bun run start
# or directly
node dist/index.js

# Run setup wizard to configure LSP servers
cclsp setup

# Quality assurance
bun run lint         # Check code style and issues
bun run lint:fix     # Auto-fix safe issues
bun run format       # Format code with Biome
bun run typecheck    # Run TypeScript type checking
bun run test         # Run unit tests
bun run test:manual  # Run manual MCP client test

# Full pre-publish check
npm run prepublishOnly  # build + test + typecheck
```

--------------------------------

### Manual CCLSP Configuration with Python and JavaScript Servers

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Manually configure CCLSP by creating a `cclsp.json` file. This example shows settings for Python (pylsp) with detailed plugin options and a JavaScript/TypeScript server.

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

--------------------------------

### Example Conventional Commit Message

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

An example of a conventional commit message using gitmoji for a new feature. This format helps in understanding the nature of changes at a glance.

```git
✨ feat: add support for Ruby language server

- Add configuration for solargraph
- Test go to definition and find references
- Update README with Ruby examples
```

--------------------------------

### Prepare Call Hierarchy MCP Tool Request and Response

Source: https://context7.com/ktnyt/cclsp/llms.txt

Example of an MCP tool call to prepare call hierarchy at a specific file location and the corresponding text-based response.

```json
// MCP Tool Call
{
  "name": "prepare_call_hierarchy",
  "arguments": {
    "file_path": "src/services/PaymentService.ts",
    "line": 45,
    "character": 10
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Call hierarchy item(s) at src/services/PaymentService.ts:45:10:\n\n• processPayment (Function) at src/services/PaymentService.ts:45:3 - PaymentService"
    }
  ]
}
```

--------------------------------

### Get Hover Information

Source: https://context7.com/ktnyt/cclsp/llms.txt

Use `get_hover` to get documentation and type information for a symbol at a specific position, similar to IDE hover behavior. It retrieves type signatures and documentation.

```typescript
// MCP Tool Call
{
  "name": "get_hover",
  "arguments": {
    "file_path": "src/api/client.ts",
    "line": 25,       // 1-indexed
    "character": 15   // 1-indexed
  }
}

// Response - Function with documentation
{
  "content": [
    {
      "type": "text",
      "text": "Hover information at src/api/client.ts:25:15:\n\n```typescript\n(method) ApiClient.fetchData<T>(endpoint: string, options?: RequestOptions): Promise<T>\n```\n\nFetches data from the specified API endpoint.\n\n@param endpoint - The API endpoint path\n@param options - Optional request configuration\n@returns Promise resolving to the typed response data"
    }
  ]
}

// Example: Getting type information for a variable
{
  "name": "get_hover",
  "arguments": {
    "file_path": "src/utils/config.ts",
    "line": 10,
    "character": 8
  }
}

// Response - Variable type info
{
  "content": [
    {
      "type": "text",
      "text": "Hover information at src/utils/config.ts:10:8:\n\n```typescript\nconst config: {\n  apiUrl: string;\n  timeout: number;\n  retries: number;\n}\n```"
    }
  ]
}
```

--------------------------------

### LspOperations Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Orchestrates LSP requests by getting servers, opening documents, and transforming responses without I/O or lifecycle logic.

```typescript
interface LspOperations {
  findDefinition(file: string, position: Position): Promise<Location[]>;
  findReferences(file: string, position: Position): Promise<Location[]>;
  findImplementations(file: string, position: Position): Promise<Location[]>;
  hover(file: string, position: Position): Promise<HoverResult | null>;
  getDocumentSymbols(file: string): Promise<DocumentSymbol[]>;
  findSymbolsByName(query: string, file?: string): Promise<SymbolInformation[]>;
  prepareCallHierarchy(file: string, position: Position): Promise<CallHierarchyItem[]>;
  incomingCalls(item: CallHierarchyItem): Promise<CallHierarchyIncomingCall[]>;
  outgoingCalls(item: CallHierarchyItem): Promise<CallHierarchyOutgoingCall[]>;
  rename(file: string, position: Position, newName: string): Promise<WorkspaceEdit>;
  getDiagnostics(file: string): Promise<Diagnostic[]>;
  syncFileContent(filePath: string): Promise<void>;
  preloadServers(debug?: boolean): Promise<void>;
}
```

--------------------------------

### Get Language Diagnostics

Source: https://context7.com/ktnyt/cclsp/llms.txt

Use `get_diagnostics` to retrieve errors, warnings, and hints for a given file using the LSP `textDocument/diagnostic` method. This helps identify code issues.

```typescript
// MCP Tool Call
{
  "name": "get_diagnostics",
  "arguments": {
    "file_path": "src/components/Dashboard.tsx"
  }
}

// Response - File with issues
{
  "content": [
    {
      "type": "text",
      "text": "Found 3 diagnostics in src/components/Dashboard.tsx:\n\n• Error [TS2304] (typescript): Cannot find name 'undefinedVar'\n  Location: Line 10, Column 5 to Line 10, Column 17\n
• Warning [no-unused-vars] (eslint): 'config' is defined but never used\n  Location: Line 25, Column 10 to Line 25, Column 16\n
• Hint (typescript): Consider using const instead of let\n  Location: Line 30, Column 1 to Line 30, Column 15"
    }
  ]
}

// Response - Clean file
{
  "content": [
    {
      "type": "text",
      "text": "No diagnostics found for src/utils/helpers.ts. The file has no errors, warnings, or hints."
    }
  ]
}

// Example: Checking Python file for errors
{
  "name": "get_diagnostics",
  "arguments": {
    "file_path": "src/main.py"
  }
}
```

--------------------------------

### Run the Test Suite

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Execute the project's test suite using Bun to ensure all tests pass. This should be done after making code changes.

```bash
bun test
```

--------------------------------

### Manual Configuration with cclsp.json

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Manually create a `cclsp.json` file to configure language servers, their commands, root directories, and initialization options.

```APIDOC
## Manual Configuration

Alternatively, create an `cclsp.json` configuration file manually:

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

**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.

<details>
<summary>📋 More Language Server Examples</summary>

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

</details>
```

--------------------------------

### Clone the cclsp Repository

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine and navigate into the project directory. This is the first step in setting up your development environment.

```bash
git clone https://github.com/your-username/cclsp.git
cd cclsp
```

--------------------------------

### ConfigLoader API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Handles configuration file discovery and validation.

```APIDOC
## ConfigLoader

### Description
Handles CCLSP_CONFIG_PATH env var, cclsp.json file discovery, and schema validation.

### Methods
- **load()**: Loads the configuration.
- **validate(config: unknown)**: Validates the configuration object.
```

--------------------------------

### Run Quality Assurance Pipeline

Source: https://github.com/ktnyt/cclsp/blob/main/CLAUDE.md

Combined command to execute linting, formatting, type checking, and testing before committing code.

```bash
bun run lint:fix && bun run format && bun run typecheck && bun run test
```

--------------------------------

### Define cclsp configuration file

Source: https://context7.com/ktnyt/cclsp/llms.txt

Create a cclsp.json file to map file extensions to specific language server commands and initialization options.

```json
{
  "servers": [
    {
      "extensions": ["js", "ts", "jsx", "tsx"],
      "command": ["npx", "--", "typescript-language-server", "--stdio"],
      "rootDir": "."
    },
    {
      "extensions": ["py", "pyi"],
      "command": ["uvx", "--from", "python-lsp-server", "pylsp"],
      "rootDir": ".",
      "restartInterval": 5,
      "initializationOptions": {
        "settings": {
          "pylsp": {
            "plugins": {
              "jedi_completion": { "enabled": true },
              "jedi_definition": { "enabled": true },
              "jedi_hover": { "enabled": true },
              "jedi_references": { "enabled": true },
              "pylint": { "enabled": false },
              "pycodestyle": { "enabled": false }
            }
          }
        }
      }
    },
    {
      "extensions": ["go"],
      "command": ["gopls"],
      "rootDir": "."
    },
    {
      "extensions": ["rs"],
      "command": ["rust-analyzer"],
      "rootDir": "."
    },
    {
      "extensions": ["vue"],
      "command": ["npx", "--", "vue-language-server", "--stdio"],
      "rootDir": "."
    }
  ]
}
```

--------------------------------

### Configure Python LSP Auto-restart

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Add a restart interval to the server configuration to mitigate performance degradation.

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

--------------------------------

### Run Linting and Formatting Checks

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Execute linting, formatting, and TypeScript type checking using Bun. These commands help maintain code quality and consistency.

```bash
bun run lint
```

```bash
bun run format
```

```bash
bun run typecheck
```

--------------------------------

### ServerManager Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Handles spawning, restart intervals, adapter detection, and initialization handshake.

```typescript
interface ServerManager {
  getServer(extension: string): Promise<ManagedServer>;
  restartServer(extension: string): Promise<void>;
  restartAll(): Promise<void>;
  getStatus(): ServerStatusMap;
  shutdown(): Promise<void>;
}

interface ManagedServer {
  transport: JsonRpcTransport;
  rootDir: string;
  adapter: ServerAdapter | null;
  state: ServerState;
}
```

--------------------------------

### Configure MCP client for cclsp

Source: https://context7.com/ktnyt/cclsp/llms.txt

Add cclsp to the MCP client configuration file or use the CLI to register it.

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

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

--------------------------------

### ConfigLoader Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Handles environment variable loading, file discovery, and schema validation, throwing errors on invalid configurations.

```typescript
interface ConfigLoader {
  load(): Config;
  validate(config: unknown): config is Config;
}
```

--------------------------------

### ServerManager API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Handles server lifecycle management including spawning, restarting, and status tracking.

```APIDOC
## ServerManager

### Description
Handles spawning, restart intervals, adapter detection, and initialization handshake for managed servers.

### Methods
- **getServer(extension: string)**: Returns a Promise for a ManagedServer.
- **restartServer(extension: string)**: Restarts a specific server.
- **restartAll()**: Restarts all managed servers.
- **getStatus()**: Returns the current ServerStatusMap.
- **shutdown()**: Shuts down all servers.
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/ktnyt/cclsp/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bug fix. Replace 'your-feature-name' with a descriptive name for your changes.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Restart LSP Servers

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Restart unresponsive LSP servers, either by specific file extensions or all servers.

```text
Claude: The TypeScript server seems unresponsive, let me restart it
> Using cclsp.restart_server with extensions ["ts", "tsx"]

Result: Successfully restarted 1 LSP server(s)
Restarted servers:
• typescript-language-server --stdio (ts, tsx)
```

```text
Claude: I'll restart all LSP servers to ensure they're working properly
> Using cclsp.restart_server

Result: Successfully restarted 2 LSP server(s)
Restarted servers:
• typescript-language-server --stdio (ts, tsx)
• pylsp (py)
```

--------------------------------

### CCLSP Development and Build Commands

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Common commands for developing and maintaining the CCLSP project, including running in development mode, executing tests, linting, formatting, and type checking.

```bash
# Run in development mode
bun run dev
```

```bash
# Run tests
bun test
```

```bash
# Run manual integration test
bun run test:manual
```

```bash
# Lint code
bun run lint
```

```bash
# Format code
bun run format
```

```bash
# Type check
bun run typecheck
```

--------------------------------

### Create Feature Branch

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Create a new branch for developing a feature. Use a descriptive name for the branch.

```bash
git checkout -b feature/amazing-feature
```

--------------------------------

### Check File Diagnostics

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Retrieve errors, warnings, and hints for a specific file.

```text
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)
```

--------------------------------

### LSPClient Facade API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

The LSPClient acts as a thin facade over internal modules, providing a stable API for tool handlers to perform LSP operations.

```APIDOC
## LSPClient API

### Description
The LSPClient provides methods to interact with language servers, abstracting the complexity of internal modules like ServerManager and LspOperations.

### Methods
- **findDefinition(file: string, position: Position)**: Returns Promise<Location[]>
- **findReferences(file: string, position: Position)**: Returns Promise<Location[]>
- **findImplementations(file: string, position: Position)**: Returns Promise<Location[]>
- **hover(file: string, position: Position)**: Returns Promise<HoverResult | null>
- **getDocumentSymbols(file: string)**: Returns Promise<DocumentSymbol[]>
- **findSymbolsByName(query: string, file?: string)**: Returns Promise<SymbolInformation[]>
- **prepareCallHierarchy(file: string, position: Position)**: Returns Promise<CallHierarchyItem[]>
- **incomingCalls(item: CallHierarchyItem)**: Returns Promise<CallHierarchyIncomingCall[]>
- **outgoingCalls(item: CallHierarchyItem)**: Returns Promise<CallHierarchyOutgoingCall[]>
- **rename(file: string, position: Position, newName: string)**: Returns Promise<WorkspaceEdit>
- **getDiagnostics(file: string)**: Returns Promise<Diagnostic[]>
- **syncFileContent(filePath: string)**: Returns Promise<void>
- **preloadServers(debug?: boolean)**: Returns Promise<void>
- **restartServers()**: Returns Promise<void>
```

--------------------------------

### Development Commands

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Common commands for running CCLSP in development mode, executing tests, linting, formatting, and type checking.

```APIDOC
## 🛠️ Development

```bash
# 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
```
```

--------------------------------

### Add cclsp to Claude MCP

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Adds cclsp as a server to Claude MCP using the command line. Ensure the CCLSP_CONFIG_PATH environment variable is set correctly.

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

--------------------------------

### Find Symbol References

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Identify all locations where a specific symbol is referenced or declared.

```text
Claude: I'll find all places where `CONFIG_PATH` is used
> Using cclsp.find_references with symbol_name="CONFIG_PATH"

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

--------------------------------

### DocumentManager API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Tracks open document state and version numbers for LSP synchronization.

```APIDOC
## DocumentManager

### Description
Tracks open document state and version numbers. Delegates actual textDocument/* notifications to the transport.

### Methods
- **open(uri: string, languageId: string, text: string)**: Opens a document.
- **change(uri: string, text: string)**: Updates document content.
- **close(uri: string)**: Closes a document.
- **isOpen(uri: string)**: Checks if a document is open.
- **getVersion(uri: string)**: Returns the current version number of a document.
```

--------------------------------

### LSPClient Facade Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

The public API for the LSP client, composed of internal modules. This facade provides a stable interface to tool handlers, abstracting away internal module changes.

```typescript
class LSPClient {
  // Composed from internal modules (not exposed to tools)
  private transport: JsonRpcTransport;
  private serverManager: ServerManager;
  private documentManager: DocumentManager;
  private operations: LspOperations;
  private diagnosticsCache: DiagnosticsCache;
  private config: ConfigLoader;

  // Public API consumed by tool handlers
  findDefinition(file: string, position: Position): Promise<Location[]>;
  findReferences(file: string, position: Position): Promise<Location[]>;
  findImplementations(file: string, position: Position): Promise<Location[]>;
  hover(file: string, position: Position): Promise<HoverResult | null>;
  getDocumentSymbols(file: string): Promise<DocumentSymbol[]>;
  findSymbolsByName(query: string, file?: string): Promise<SymbolInformation[]>;
  prepareCallHierarchy(file: string, position: Position): Promise<CallHierarchyItem[]>;
  incomingCalls(item: CallHierarchyItem): Promise<CallHierarchyIncomingCall[]>;
  outgoingCalls(item: CallHierarchyItem): Promise<CallHierarchyOutgoingCall[]>;
  rename(file: string, position: Position, newName: string): Promise<WorkspaceEdit>;
  getDiagnostics(file: string): Promise<Diagnostic[]>;
  syncFileContent(filePath: string): Promise<void>;
  preloadServers(debug?: boolean): Promise<void>;
  restartServers(): Promise<void>;
}

```

--------------------------------

### Restart LSP Servers

Source: https://context7.com/ktnyt/cclsp/llms.txt

Manually restart Language Server Protocol (LSP) servers to resolve unresponsiveness or apply configuration changes. You can restart servers for specific file extensions or all running servers.

```typescript
// MCP Tool Call - Restart specific language server
{
  "name": "restart_server",
  "arguments": {
    "extensions": ["ts", "tsx"]
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Successfully restarted 1 LSP server(s)\n\nRestarted servers:\n• typescript-language-server --stdio (ts, tsx)"
    }
  ]
}

// MCP Tool Call - Restart all servers
{
  "name": "restart_server",
  "arguments": {}
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Successfully restarted 3 LSP server(s)\n\nRestarted servers:\n• typescript-language-server --stdio (ts, tsx, js, jsx)
• pylsp (py, pyi)
• gopls (go)"
    }
  ]
}

// Example: Restart Python server after pip install
{
  "name": "restart_server",
  "arguments": {
    "extensions": ["py"]
  }
}
```

--------------------------------

### MCP Tools - find_definition

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Finds the definition of a symbol by name and kind within a specified file. Returns definitions for all matching symbols.

```APIDOC
### `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)
```

--------------------------------

### LspOperations API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Orchestrates LSP requests by interacting with servers and document managers.

```APIDOC
## LspOperations

### Description
Orchestrates LSP operations: get server -> open document -> send LSP request -> transform response.

### Methods
- **findDefinition(file: string, position: Position)**: Finds definitions.
- **findReferences(file: string, position: Position)**: Finds references.
- **findImplementations(file: string, position: Position)**: Finds implementations.
- **hover(file: string, position: Position)**: Gets hover information.
- **getDocumentSymbols(file: string)**: Gets symbols for a document.
- **findSymbolsByName(query: string, file?: string)**: Searches symbols by name.
- **rename(file: string, position: Position, newName: string)**: Performs a rename operation.
- **getDiagnostics(file: string)**: Retrieves diagnostics for a file.
```

--------------------------------

### Search Workspace Symbols

Source: https://context7.com/ktnyt/cclsp/llms.txt

Use this tool to find symbols like functions, classes, or variables across your entire project when the file location is unknown. Provide a query string to match symbol names.

```typescript
// MCP Tool Call
{
  "name": "find_workspace_symbols",
  "arguments": {
    "query": "User"
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Found 8 symbol(s) matching \"User\":\n\n• User (Class) at src/models/User.ts:10:1
• UserService (Class) at src/services/UserService.ts:15:1
• UserRepository (Class) at src/repositories/UserRepository.ts:8:1
• UserController (Class) at src/controllers/UserController.ts:12:1
• createUser (Function) at src/api/users.ts:25:1
• updateUser (Function) at src/api/users.ts:45:1
• deleteUser (Function) at src/api/users.ts:67:1
• UserRole (Enum) at src/types/enums.ts:5:1"
    }
  ]
}

// Example: Searching for configuration-related symbols
{
  "name": "find_workspace_symbols",
  "arguments": {
    "query": "Config"
  }
}
```

--------------------------------

### Find implementations with find_implementation

Source: https://context7.com/ktnyt/cclsp/llms.txt

Navigates to concrete implementations of interfaces or abstract methods using exact file coordinates.

```json
// MCP Tool Call
{
  "name": "find_implementation",
  "arguments": {
    "file_path": "src/interfaces/Repository.ts",
    "line": 5,        // 1-indexed line number
    "character": 10   // 1-indexed character position
  }
}
```

```json
// Response
{
  "content": [
    {
      "type": "text",
      "text": "Found 3 implementation(s):\n\n• src/repositories/UserRepository.ts:15:1\n• src/repositories/ProductRepository.ts:12:1\n• src/repositories/OrderRepository.ts:18:1"
    }
  ]
}
```

```json
// Example: Finding implementations of an interface method
{
  "name": "find_implementation",
  "arguments": {
    "file_path": "src/services/ILogger.ts",
    "line": 8,
    "character": 3
  }
}
```

--------------------------------

### Prepare Call Hierarchy

Source: https://context7.com/ktnyt/cclsp/llms.txt

Retrieves call hierarchy items at a specific position for detailed call graph analysis. This is a lower-level tool; prefer `get_incoming_calls` or `get_outgoing_calls` for most use cases.

```APIDOC
## POST /prepare_call_hierarchy

### Description
Get call hierarchy items at a position, preparing for incoming or outgoing call analysis. This is a lower-level tool that returns call hierarchy items which can be used for detailed call graph analysis. Most users should prefer `get_incoming_calls` or `get_outgoing_calls` which use this internally.

### Method
POST

### Endpoint
/prepare_call_hierarchy

### Parameters
#### Request Body
- **file_path** (string) - Required - The path to the file.
- **line** (integer) - Required - The line number.
- **character** (integer) - Required - The character number.

### Request Example
```json
{
  "name": "prepare_call_hierarchy",
  "arguments": {
    "file_path": "src/services/PaymentService.ts",
    "line": 45,
    "character": 10
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - An array of call hierarchy items.
  - **type** (string) - The type of the content item (e.g., "text").
  - **text** (string) - The textual representation of the call hierarchy item.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "Call hierarchy item(s) at src/services/PaymentService.ts:45:10:\n\n• processPayment (Function) at src/services/PaymentService.ts:45:3 - PaymentService"
    }
  ]
}
```
```

--------------------------------

### MCP Tool: find_definition

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Locates the definition of a symbol at a given file path and position.

```APIDOC
## find_definition

### Description
Finds the definition of a symbol in the codebase.

### Parameters
- **path** (string) - Required - The file path containing the symbol.
- **line** (number) - Required - The line number of the symbol.
- **character** (number) - Required - The character offset of the symbol.
```

--------------------------------

### MCP Tool: get_diagnostics

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Retrieves diagnostics (errors/warnings) for a specific file.

```APIDOC
## get_diagnostics

### Description
Fetches current LSP diagnostics for a file.

### Parameters
- **path** (string) - Required - The file path to check for diagnostics.
```

--------------------------------

### MCP Tools - find_references

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

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

```APIDOC
### `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)
```

--------------------------------

### DiagnosticsCache Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Stores pushed diagnostics from servers, queryable by URI.

```typescript
interface DiagnosticsCache {
  update(uri: string, diagnostics: Diagnostic[]): void;
  get(uri: string): Diagnostic[];
  clear(uri?: string): void;
}
```

--------------------------------

### MCP Tool: find_references

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Finds all references to a symbol at a given file path and position.

```APIDOC
## find_references

### Description
Locates all usages of a specific symbol.

### Parameters
- **path** (string) - Required - The file path containing the symbol.
- **line** (number) - Required - The line number of the symbol.
- **character** (number) - Required - The character offset of the symbol.
```

--------------------------------

### Use find_definition tool

Source: https://context7.com/ktnyt/cclsp/llms.txt

Call the find_definition tool to locate symbol definitions within a codebase.

```typescript
// MCP Tool Call
{
  "name": "find_definition",
  "arguments": {
    "file_path": "src/utils/parser.ts",
    "symbol_name": "parseJSON",
    "symbol_kind": "function"  // optional: function, class, variable, method, etc.
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Results for parseJSON (Function) at src/utils/parser.ts:15:1:\n• src/utils/parser.ts:15:1"
    }
  ]
}

// Example: Finding a class definition
{
  "name": "find_definition",
  "arguments": {
    "file_path": "src/models/User.py",
    "symbol_name": "UserService",
    "symbol_kind": "class"
  }
}

// Response shows the class definition location
{
  "content": [
    {
      "type": "text",
      "text": "Results for UserService (Class) at src/models/User.py:25:1:\n• src/services/user_service.py:10:1"
    }
  ]
}
```

--------------------------------

### Find Incoming Calls

Source: https://context7.com/ktnyt/cclsp/llms.txt

Identify all functions or methods that call a specific function at a given file path and line number. This is useful for impact analysis and understanding code dependencies.

```typescript
// MCP Tool Call
{
  "name": "get_incoming_calls",
  "arguments": {
    "file_path": "src/utils/validation.ts",
    "line": 15,       // 1-indexed position of the function
    "character": 10
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Found 5 incoming call(s):\n\n• handleSubmit (Function) at src/components/Form.tsx:45:3
• validateInput (Function) at src/api/handlers.ts:23:5
• processData (Function) at src/services/DataService.ts:67:8
• createUser (Function) at src/controllers/UserController.ts:34:10
• updateProfile (Method) at src/models/User.ts:89:5"
    }
  ]
}

// Example: Finding callers of a method
{
  "name": "get_incoming_calls",
  "arguments": {
    "file_path": "src/services/AuthService.ts",
    "line": 50,
    "character": 8
  }
}
```

--------------------------------

### ToolDefinition Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Defines the structure for tools, including their name, description, input schema, and handler function. Tools are registered declaratively.

```typescript
interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
  handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
}

interface ToolContext {
  client: LSPClient; // Thin facade over internal modules
}

type ToolResult = {
  content: Array<{ type: 'text'; text: string }>;
  isError?: boolean;
};

```

--------------------------------

### Find Function Definition

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Locate the definition of a specific function symbol within the codebase.

```text
Claude: Let me find the definition of the `processRequest` function
> Using cclsp.find_definition with symbol_name="processRequest", symbol_kind="function"

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

--------------------------------

### DiagnosticsCache API

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Stores and retrieves diagnostics pushed from servers.

```APIDOC
## DiagnosticsCache

### Description
Stores pushed diagnostics from servers, queryable by URI.

### Methods
- **update(uri: string, diagnostics: Diagnostic[])**: Updates cache for a URI.
- **get(uri: string)**: Gets diagnostics for a URI.
- **clear(uri?: string)**: Clears cache entries.
```

--------------------------------

### Commit Changes

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Commit your staged changes with a clear and concise message. Use conventional commit format for feature additions.

```bash
git commit -m '✨ feat: add amazing feature'
```

--------------------------------

### DocumentManager Interface

Source: https://github.com/ktnyt/cclsp/blob/main/docs/architecture-proposal.md

Tracks open document state and version numbers, delegating textDocument notifications to the transport.

```typescript
interface DocumentManager {
  open(uri: string, languageId: string, text: string): Promise<void>;
  change(uri: string, text: string): Promise<void>;
  close(uri: string): Promise<void>;
  isOpen(uri: string): boolean;
  getVersion(uri: string): number;
}
```

--------------------------------

### find_definition

Source: https://context7.com/ktnyt/cclsp/llms.txt

Finds the definition of a symbol within a file, handling position resolution automatically.

```APIDOC
## find_definition

### Description
Find where a symbol is defined by searching for the symbol name in a file. This tool handles the complexity of position resolution automatically, making it reliable even when line/column numbers are imprecise. Returns definitions for all matching symbols of the specified kind.

### Parameters
#### Request Body
- **file_path** (string) - Required - The path to the file containing the symbol.
- **symbol_name** (string) - Required - The name of the symbol to search for.
- **symbol_kind** (string) - Optional - The kind of symbol (e.g., function, class, variable, method).

### Request Example
{
  "name": "find_definition",
  "arguments": {
    "file_path": "src/utils/parser.ts",
    "symbol_name": "parseJSON",
    "symbol_kind": "function"
  }
}

### Response
#### Success Response (200)
- **content** (array) - A list of results containing the type and text description of the symbol location.

#### Response Example
{
  "content": [
    {
      "type": "text",
      "text": "Results for parseJSON (Function) at src/utils/parser.ts:15:1:\n• src/utils/parser.ts:15:1"
    }
  ]
}
```

--------------------------------

### Push Feature Branch

Source: https://github.com/ktnyt/cclsp/blob/main/README.md

Push your local feature branch to the remote repository. This makes your changes available for a pull request.

```bash
git push origin feature/amazing-feature
```

--------------------------------

### Find Outgoing Calls

Source: https://context7.com/ktnyt/cclsp/llms.txt

Determine all functions or methods that are called by a specific function at a given file path and line number. This helps in understanding a function's internal dependencies.

```typescript
// MCP Tool Call
{
  "name": "get_outgoing_calls",
  "arguments": {
    "file_path": "src/services/OrderService.ts",
    "line": 30,       // 1-indexed position of the function
    "character": 8
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Found 4 outgoing call(s):\n\n• validateOrder (Function) at src/utils/validation.ts:15:1
• calculateTotal (Function) at src/utils/pricing.ts:23:1
• saveToDatabase (Method) at src/repositories/OrderRepository.ts:45:3
• sendNotification (Function) at src/services/NotificationService.ts:12:1"
    }
  ]
}

// Example: Analyzing a complex function's dependencies
{
  "name": "get_outgoing_calls",
  "arguments": {
    "file_path": "src/api/checkout.ts",
    "line": 100,
    "character": 5
  }
}
```