Lsp Diagnostic Setup

LSP Setup

Configure the right Language Server for a project so the lsp MCP tools (diagnostics, goto_definition, find_references, symbols, rename) actually work. This skill is an index: detect what a project needs, install the server, write the config, then verify with a real roundtrip.

The list of servers we ship as builtin is the source of truth in packages/lsp-tools-mcp/src/lsp/server-definitions.ts (BUILTIN_SERVERS + LSP_INSTALL_HINTS). The per-language references below mirror it.

PHASE 0 — LANGUAGE GATE (run first)

Identify the language from the file extension, then read the matching reference before installing or configuring anything.

WORKFLOW — detect → install → configure → verify

1. Detect

Scan the project to see which languages are present and whether each server is installed and configured:

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

For each detected language it prints the builtin server id, the executable it needs on PATH, whether that executable is installed, an install hint, and whether a project config file already references it.

2. Install

Open references/<language>/README.md and run the install command for your OS. Then confirm the executable resolves:

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

3. Configure

Most builtin servers need no config — they are resolved automatically by file extension. Write config only to: pick between competing servers, set a priority, pass initialization options, override extensions, set env, or disable a server.

Two project-scoped config files, identical JSON shape:

• Codex harness → .codex/lsp-client.json (user: ~/.codex/lsp-client.json)
• OpenCode/omo harness → .opencode/lsp.json (also .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
    }
  }
}

Rules enforced by config-loader.ts:

• In a project config (.codex/lsp-client.json, .opencode/lsp.json) an entry whose id is a builtin server inherits command automatically — you only override extensions / priority / initialization. A non-builtin id in a project config is ignored.
• To define a fully custom (non-builtin) server with its own command, put it in the user config (~/.codex/lsp-client.json, or the path set by LSP_TOOLS_MCP_USER_CONFIG), where command + extensions are honored.
• Project entries win over user entries; both win over builtin defaults.

Each language reference gives a ready-to-paste snippet.

4. Verify

Run a real diagnostics roundtrip against a source file. This spawns the server, opens the file, requests diagnostics, and reports OK/FAIL:

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

OK = the server started and answered. FAIL: language server not installed = go back to step 2. Other FAIL text carries the server/startup error. SKIP = the engine source could not be located; run from inside the omo repo/worktree, or call the lsp MCP diagnostics tool directly.

Scripts

Run with Bun: curl -fsSL https://bun.sh/install | bash.