LSP Configuration Skill

Provides guidance for configuring Language Server Protocol (LSP) servers in Claude Code using the lspctl plugin.

Overview

The lspctl plugin enables Mason-like LSP management for Claude Code:

1. Define servers in a Lua config file (compatible with Neovim)
2. Generate a marketplace with individual LSP plugins
3. Install binaries and plugins as needed

Quick Start

1. Create Config File

Create ~/.claude/lsp-config.lua (user-level) or .claude/lsp-config.lua (project-level):

return {
  ensure_installed = {
    "lua_ls",      -- Lua
    "pylsp",       -- Python (with ruff/isort)
    "pyright",     -- Python (type checking)
    "ts_ls",       -- TypeScript/JavaScript
    "rust_analyzer", -- Rust
    "gopls",       -- Go
  },
  servers = {
    pylsp = {
      settings = {
        pylsp = {
          plugins = {
            ruff = { enabled = true, lineLength = 80 },
            isort = { enabled = true, profile = "black" }
          }
        }
      }
    },
    rust_analyzer = {
      settings = {
        ["rust-analyzer"] = {
          checkOnSave = { command = "clippy" }
        }
      }
    }
  }
}

2. Generate Marketplace

/lspctl:sync

This creates a marketplace at ~/.claude/generated-lsp-marketplace/ (or project-level).

3. Install Plugins

/plugin install lsp-python-pylsp@generated-lsp
/plugin install lsp-rust@generated-lsp

Or install all:

/lspctl:install-all

Available Commands

Command	Description
/lspctl:list	Show available servers and status
/lspctl:sync	Generate marketplace from config
/lspctl:install <server>	Install specific server
/lspctl:install-all	Install all configured servers
/lspctl:uninstall <server>	Uninstall server plugin
/lspctl:uninstall --all	Remove all and deregister marketplace

Supported LSP Servers

Server	Language	Binary
lua_ls	Lua	lua-language-server
pylsp	Python	pylsp
pyright	Python	pyright-langserver
ts_ls	TypeScript/JS	typescript-language-server
rust_analyzer	Rust	rust-analyzer
gopls	Go	gopls
clangd	C/C++	clangd
jsonls	JSON	vscode-json-language-server
yamlls	YAML	yaml-language-server
bashls	Bash	bash-language-server

Server Settings Reference

Python (pylsp with ruff)

pylsp = {
  settings = {
    pylsp = {
      plugins = {
        ruff = { enabled = true, lineLength = 80 },
        isort = { enabled = true, profile = "black" },
        pycodestyle = { enabled = false },
        pyflakes = { enabled = false },
        mccabe = { enabled = false }
      }
    }
  }
}

Python (pyright)

pyright = {
  settings = {
    python = {
      analysis = {
        typeCheckingMode = "basic",  -- "off", "basic", "standard", "strict"
        autoSearchPaths = true,
        useLibraryCodeForTypes = true
      }
    }
  }
}

Lua

lua_ls = {
  settings = {
    Lua = {
      diagnostics = { globals = { "vim" } },
      runtime = { version = "LuaJIT" },
      workspace = { checkThirdParty = false }
    }
  }
}

Rust

rust_analyzer = {
  settings = {
    ["rust-analyzer"] = {
      checkOnSave = { command = "clippy" },
      files = { excludeDirs = { ".git", "target" } }
    }
  }
}

TypeScript

ts_ls = {
  settings = {
    typescript = {
      preferences = {
        quoteStyle = "single"
      }
    }
  }
}

Troubleshooting

LSP not starting

1. Check if binary is installed:

   which <command>
   

2. Run with debug logging:

   claude --enable-lsp-logging
   

3. Check logs in ~/.claude/debug/

Config not parsing

1. Validate Lua syntax:

   lua -c ~/.claude/lsp-config.lua
   

2. Test parser:

   lua ${CLAUDE_PLUGIN_ROOT}/scripts/parse-lua-config.lua ~/.claude/lsp-config.lua
   

Plugin not found

1. Ensure marketplace was generated:

   /lspctl:sync
   

2. Check marketplace was added to settings:

   cat ~/.claude/settings.json | grep generated-lsp
   

Migrating from Neovim

Your Neovim LSP config uses lspconfig server names (e.g., lua_ls, pylsp). The lspctl plugin uses the same naming convention.

To migrate:

1. Copy ensure_installed array from your mason-lspconfig setup
2. Copy server settings from your vim.lsp.config() calls
3. Run /lspctl:sync