lsp-sidecar

codex-lsp-sidecar runs a stdio MCP server that gives Codex four local language-server tools:

• lsp_diagnostics
• lsp_definition
• lsp_hover
• lsp_workspace_symbol

install

npm install -g @codex-modules/lsp-sidecar

Or from source:

npm install
npm run build

The package uses the official Model Context Protocol TypeScript SDK for its MCP transport and lifecycle. Language servers are discovered from the target workspace, this module’s node_modules/.bin, or PATH.

usage

Check a workspace first:

codex-lsp-sidecar doctor --root /path/to/repo

Run the MCP server:

codex-lsp-sidecar serve --root /path/to/repo

Register directly with Codex:

codex mcp add lsp -- codex-lsp-sidecar serve --root /path/to/repo

Or register through this repo’s MCP manager module:

codex-mcp-manager add \
  --name lsp \
  --command codex-lsp-sidecar \
  --arg serve \
  --arg --root \
  --arg /path/to/repo

The file-position tools use 1-based line and character values, matching editor coordinates.

how it works

The sidecar reserves stdout for newline-delimited MCP messages and writes logs to stderr. The official MCP TypeScript SDK owns protocol negotiation, lifecycle, request validation, and cancellation. LSP subprocesses use their separate Content-Length-framed protocol.

Every requested file must remain inside the configured root after resolving symlinks. Requests that resolve outside the root return LSP_INPUT_ERROR. LSP requests have bounded timeouts and send $/cancelRequest when the MCP caller cancels or a timeout expires.

LSP stdio parsing also bounds header, body, and aggregate buffer sizes. Malformed or oversized frames close that LSP connection without writing protocol errors to MCP stdout. Closing MCP stdin, including EOF, shuts down the service and reaps active or initializing LSP process trees. POSIX launches use a detached process group; Windows cleanup verifies taskkill /T and escalates with /F when needed.

LSP servers are started lazily on the first relevant tool call. The sidecar never downloads language servers, installs packages, or edits Codex configuration. It currently knows how to discover TypeScript, Biome, and optional ESLint servers:

• TypeScript needs typescript-language-server plus a resolvable typescript/lib/tsserver.js.
• Biome needs a biome binary.
• ESLint needs a resolvable eslint package plus vscode-eslint-language-server.

All four tools are always listed. If no matching server is available for a call, the tool returns isError: true with structured content containing code: "LSP_SERVER_UNAVAILABLE".

Idle LSP clients are shut down after 10 minutes by default. Use --idle-ms 0 to disable idle shutdown while debugging.

Attribution

Portions of the LSP implementation are adapted from the MIT-licensed OpenCode project by SST: https://github.com/sst/opencode

uninstall-rollback

Remove the npm package:

npm uninstall -g @codex-modules/lsp-sidecar

Removing the package does not edit Codex MCP configuration. Remove the MCP registration separately:

codex mcp remove lsp

Or through this repo’s MCP manager module:

codex-mcp-manager remove lsp