# Codex LSP Bridge Architecture
## Goal
Expose IDE-grade semantic code intelligence (Language Server Protocol) to Codex CLI (and any MCP client) via a single **MCP Streamable HTTP** endpoint.
## High-level data flow
```
Codex CLI
│ (MCP tool calls over Streamable HTTP)
▼
MCP Server (FastMCP)
│ (route tool call → language server)
▼
LSP Manager
│ (choose server + workspace root)
▼
LSP Client Pool
│ (JSON-RPC over stdio)
▼
Language Servers
• basedpyright / pyright
• rust-analyzer
• clangd
• typescript-language-server
• vscode-html-language-server
• vscode-css-language-server
```
## Core components
### MCP Server
* Transport: **http** (Streamable HTTP) → endpoint: `/mcp`.
* Exposes tools that map cleanly onto LSP requests:
* `go_to_definition`
* `find_references`
* `hover`
* `document_symbols`
* `workspace_symbols`
* `diagnostics`
* `rename_symbol`
### LSP Manager
* Resolves relative paths against `default_root` (config) or current working directory.
* Detects workspace root by walking up the filesystem for common markers (`.git`, `pyproject.toml`, `package.json`, `Cargo.toml`, etc.).
* Starts language servers lazily (first use) and keeps a pool keyed by `(language, workspace_root)`.
### LSP Client
* Starts a language server process with stdio pipes.
* Implements LSP framing: `Content-Length: ...\r\n\r\n{json}`.
* Performs the `initialize` / `initialized` handshake.
* Maintains per-document state:
* `didOpen` on first use
* `didChange` (full text) on subsequent uses
* Captures diagnostics from `textDocument/publishDiagnostics`.
## Deployment modes
### Local (recommended)
* Run the MCP server on `127.0.0.1:8000`.
* Codex connects to `http://127.0.0.1:8000/mcp`.
* Pros: no code leaves the machine; language servers can see your repo + dependencies.
### Remote (advanced)
* Works only if the remote host has access to the same repository files (e.g., mounted volume, shared filesystem, or the bridge is co-located with the repo).
* Add bearer token auth in front (reverse proxy) and configure Codex to send it.
## Known limitations (and easy next upgrades)
* Multiple servers per file (e.g., TS + ESLint) is not yet merged at the bridge layer.
* Unsaved editor buffers aren't visible unless Codex writes changes to disk before calling tools.
* Some LSP features require additional client support (e.g., code actions, semantic tokens).
