code-yeongyu/oh-my-openagent/lsp-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 (user config only), or disable a server.

Config files per harness, identical JSON shape. Each harness reads the first project file that exists, plus one user file:

A standalone lsp-tools-mcp launch reads the paths in LSP_TOOLS_MCP_PROJECT_CONFIG / LSP_TOOLS_MCP_USER_CONFIG instead.

{
  "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 an entry whose id is a builtin server inherits

command automatically — you only override extensions / priority / initialization / disabled. Its env is dropped, and a non-builtin id in a project config is ignored.

• To set env, or to define a fully custom (non-builtin) server with its

own command, put it in the user config from the table above, where command + extensions + env are honored.

• Project entries win over user entries; both win over builtin defaults. A user

entry is skipped when an enabled project entry has the same id, so keep an id that needs env out of the project config.

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.