Configuração do LSP

Configure o Language Server correto para um projeto para que as ferramentas MCP lsp (diagnostics, goto_definition, find_references, symbols, rename) funcionem de verdade. Essa habilidade é um índice: detecta o que um projeto precisa, instala o servidor, escreve a configuração e, em seguida, verifica com um roundtrip real.

A lista de servidores que fornecemos como embutidos é a fonte da verdade em packages/lsp-tools-mcp/src/lsp/server-definitions.ts (BUILTIN_SERVERS + LSP_INSTALL_HINTS). As referências por idioma abaixo a espelham.

FASE 0 — GATE DE IDIOMA (execute primeiro)

Identifique o idioma pela extensão do arquivo e, em seguida, leia a referência correspondente antes de instalar ou configurar qualquer coisa.

FLUXO DE TRABALHO — detectar → instalar → configurar → verificar

1. Detectar

Escaneie o projeto para ver quais idiomas estão presentes e se cada servidor está instalado e configurado:

bun scripts/detect-lsp.ts <projectDir>      # human report (default: cwd)
bun scripts/detect-lsp.ts <projectDir> --json

Para cada idioma detectado, ele imprime o ID do servidor embutido, o executável que ele precisa no PATH, se esse executável está instalado, uma dica de instalação e se um arquivo de configuração do projeto já o referencia.

2. Instalar

Abra references/<language>/README.md e execute o comando de instalação para o seu sistema operacional. Em seguida, confirme se o executável é resolvido:

command -v <server-executable>   # e.g. typescript-language-server, gopls, rust-analyzer

3. Configurar

A maioria dos servidores embutidos não precisa de configuração — eles são resolvidos automaticamente por extensão de arquivo. Escreva a configuração apenas para: escolher entre servidores concorrentes, definir um priority, passar opções de initialization, substituir extensions, definir env ou disable um servidor.

Dois arquivos de configuração com escopo de projeto, forma JSON idêntica:

• Harness do Codex → .codex/lsp-client.json (usuário: ~/.codex/lsp-client.json)
• Harness do OpenCode/omo → .opencode/lsp.json (também .omo/lsp.json)

{
  "lsp": {
    "<server-id>": {
      "command": ["<bin>", "<args>"],   // optional for builtin ids (supplied automatically)
      "extensions": [".ext"],            // optional override
      "priority": 100,                    // higher wins when several servers match an extension
      "initialization": { },              // server-specific initializationOptions
      "env": { "KEY": "value" },          // optional
      "disabled": false                   // set true to turn a server off
    }
  }
}

Regras aplicadas pelo config-loader.ts:

• Em uma configuração de projeto (.codex/lsp-client.json, .opencode/lsp.json), uma entrada cujo ID é um servidor embutido herda command automaticamente — você apenas substitui extensions / priority / initialization. Um ID não embutido em uma configuração de projeto é ignorado.
• Para definir um servidor totalmente personalizado (não embutido) com seu próprio command, coloque-o na configuração do usuário (~/.codex/lsp-client.json, ou o caminho definido por LSP_TOOLS_MCP_USER_CONFIG), onde command + extensions são respeitados.
• Entradas de projeto têm precedência sobre entradas de usuário; ambas têm precedência sobre os padrões embutidos.

Cada referência de idioma fornece um trecho pronto para colar.

4. Verificar

Execute um roundtrip de diagnóstico real contra um arquivo de origem. Isso inicia o servidor, abre o arquivo, solicita diagnósticos e relata OK/FAIL:

bun scripts/verify-lsp.ts <path/to/file.ext>
bun scripts/verify-lsp.ts <file> --timeout=90000

…