## Deliverables
* **Presentation (PPTX):** [Download](sandbox:/mnt/data/codex-lsp-bridge-presentation.pptx)
* **Complete project (code + configs + docs, ZIP):** [Download](sandbox:/mnt/data/codex-lsp-bridge.zip)
* Your existing HTML deck (reference):
---
## Research: which LSP servers to use (Python, Rust, C/C++, Node/TS/JS, HTML/CSS, React)
### Recommended “default stack” (practical + widely supported)
| Area | Recommended LSP server | Install | Notes / gotchas |
| ---------------------------------- | --------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Python** | **basedpyright-langserver** (or pyright-langserver) | `pip install basedpyright` | Basedpyright ships as a PyPI package (no Node required), and includes the language server. |
| | **python-lsp-server (pylsp)** (alternative) | `pip install python-lsp-server` | Plugin-based; Jedi-based defs/hover/symbols; extra features via optional deps (rope, black, ruff, etc.). |
| **Rust** | **rust-analyzer** | `rustup component add rust-analyzer` (common) | De-facto Rust LSP, “IDE functionality for Rust programs”. |
| **C / C++** | **clangd** | install via LLVM packages | For accurate results it needs your build flags, typically via `compile_commands.json` (CMake can generate it). clangd searches parent dirs and `build/` dirs. |
| **TypeScript / JavaScript / Node** | **typescript-language-server** | `npm i -g typescript typescript-language-server` | It’s an LSP wrapper around `tsserver` and requires `tsserver` (from `typescript`) on PATH; run with `--stdio`. |
| **React (JSX/TSX)** | **typescript-language-server** (same server) | same as above | Works via `javascriptreact` / `typescriptreact` language IDs (important for correct JSX/TSX behavior). |
| **HTML / CSS** | **vscode-langservers-extracted** | `npm i -g vscode-langservers-extracted` | Provides `vscode-html-language-server` + `vscode-css-language-server` commands (and JSON, ESLint). |
### Alternatives worth knowing (for “sell the tool” conversations)
* **Python**
* **pyright-langserver**: very common; Pyright includes a language server in addition to CLI type checker.
* **jedi-language-server**: simple Jedi-driven language server (lighter weight, less type-checking emphasis).
* **TS/JS**
* **vtsls**: a VS Code TypeScript extension wrapper (some teams prefer it for VS Code parity).
* **HTML/CSS**
* Install individual servers, but `vscode-langservers-extracted` is usually the lowest-friction approach.
* **Optional “React ecosystem” add-ons**
* Tailwind CSS language server can be added for Tailwind-heavy repos (not required for the core bridge).
---
## How to package “all of them” into one Codex-usable tool (Codex CLI → MCP HTTP → LSP)
### 3 viable approaches (trade-offs)
1. **Single MCP HTTP bridge server (recommended)**
* **What:** One MCP server exposes tools (`go_to_definition`, `find_references`, …). Internally, it spawns multiple LSP servers and routes calls by file extension.
* **Pros:** One endpoint, simplest Codex config, easiest to “sell”, multi-language in one place.
* **Cons:** Runs multiple processes; needs all language servers installed where the bridge runs.
2. **One MCP server per language**
* **Pros:** Isolation; failures in one language server don’t impact others.
* **Cons:** You configure multiple MCP servers in Codex; harder UX.
3. **Remote/team deployment**
* **Pros:** Shared service; consistent tooling across a team; centralized observability.
* **Cons:** The bridge must have access to the repo content (mounted FS, remote workspace, or “sync code to server” design). Security model is more complex.
**Recommendation:** start with **(1)** locally (HTTP on localhost). It delivers the pitch (“IDE brain for Codex”) with minimal operational risk, and Codex supports connecting to MCP servers over **Streamable HTTP**.
---
## The architecture you asked for
### External architecture (Codex → MCP HTTP → LSP)
```
Codex CLI
│ MCP (Streamable HTTP)
▼
MCP LSP Bridge Server (FastMCP, /mcp)
│ LSP (JSON-RPC over stdio)
▼
Language Servers
- basedpyright / pyright
- rust-analyzer
- clangd
- typescript-language-server (JS/TS/Node/React)
- vscode-html-language-server
- vscode-css-language-server
```
Key points:
* Codex supports **Streamable HTTP MCP servers** and configures them in `~/.codex/config.toml`.
* FastMCP can run with `transport="http"` and exposes the MCP endpoint at `/mcp`.
### Internal architecture (what makes it “production-grade”)
* **Workspace root detection** (important for TS/Rust/C++ indexing)
* Detects repo roots by searching for `.git`, `package.json`, `Cargo.toml`, etc.
* **Client pool keyed by `(language, workspaceRoot)`**
* Prevents “index contamination” across repos.
* **Document sync**
* `didOpen` first time
* `didChange` (full text) on subsequent calls
* **Error isolation**
* One crashed LSP server should only affect that language/workspace client.
This is implemented in the provided project ZIP.
---
## How to connect everything to Codex CLI (HTTP MCP)
### 1) Run the MCP bridge over HTTP
FastMCP’s HTTP mode:
* `mcp.run(transport="http", host="127.0.0.1", port=8000)`
* Endpoint: `http://127.0.0.1:8000/mcp`
The included project provides a CLI:
```bash
codex-lsp-bridge serve --config ./config/default.toml --host 127.0.0.1 --port 8000
```
### 2) Configure Codex CLI to use it
Codex supports adding MCP servers (including Streamable HTTP) via config.
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.lsp_bridge]
url = "http://127.0.0.1:8000/mcp"
```
(If you want auth later, Codex supports bearer token env var config for HTTP MCP servers. )
### 3) Install the language servers on the same machine
* Python: basedpyright or pyright
* Rust: rust-analyzer
* C/C++: clangd and **compile_commands.json** generation
* TS/JS/Node/React: typescript-language-server (needs typescript/tsserver)
* HTML/CSS: vscode-langservers-extracted
---
## What you get “as tools” inside Codex
The project exposes these MCP tools (names in code):
* `go_to_definition(file_path, line, column)`
* `find_references(file_path, line, column, include_declaration=True)`
* `hover(file_path, line, column)`
* `document_symbols(file_path)`
* `workspace_symbols(query, max_results=200)`
* `diagnostics(file_path)`
* `rename_symbol(file_path, line, column, new_name)`
* `lsp_bridge_status()`
These map directly onto core LSP requests (`textDocument/definition`, `textDocument/references`, `textDocument/hover`, …).
---
## “Proper project” plan (what to build + how to sell it)
### MVP (what you demo in 5 minutes)
* Languages: Python + TS/React + C++ + Rust
* Tools: definition, references, hover, symbols
* Demo: “rename a symbol safely across the repo”
* show `find_references` → `rename_symbol` → apply WorkspaceEdit → tests pass
### Hardening (what makes it production-grade)
* Logging + structured errors (per-tool + per-language server)
* Timeouts + restart logic (auto-restart crashed LSP server)
* Diagnostics surfacing (“why does this code not compile?”)
* Optional multi-server composition (TS server + ESLint server for diagnostics)
### Team rollout
* Provide a “golden” config for language servers
* Add a preflight script that checks commands exist (`clangd`, `rust-analyzer`, etc.)
* Add security posture:
* local-only by default
* bearer-token for shared deployments (Codex supports this for HTTP MCP servers)
---
## Notes that matter in real repos
* **C/C++ quality depends on build metadata**
Without `compile_commands.json` (or equivalent), clangd’s definition/ref results degrade. For CMake, enable `-DCMAKE_EXPORT_COMPILE_COMMANDS=1`.
* **TS/React quality depends on project config**
`tsconfig.json` / `jsconfig.json` strongly affects indexing and module resolution; `typescript-language-server` depends on `tsserver`.
* **Remote deployment is not “free”**
An LSP server needs the codebase and dependency context; remote-only works if the server can access/mount the repo.
---
## What I produced (and where to look)
* **Presentation deck** (non-technical friendly + pitch framing):
[codex-lsp-bridge-presentation.pptx](sandbox:/mnt/data/codex-lsp-bridge-presentation.pptx)
* **Project ZIP** (code + docs + default multi-language config):
[codex-lsp-bridge.zip](sandbox:/mnt/data/codex-lsp-bridge.zip)
Inside the ZIP:
* `src/codex_lsp_bridge/server.py` → FastMCP tools + HTTP/stdio serve mode
* `src/codex_lsp_bridge/lsp_client.py` → JSON-RPC framing + LSP handshake + document sync
* `src/codex_lsp_bridge/lsp_manager.py` → multi-language routing + workspace pooling
* `config/default.toml` → python/rust/cpp/ts/html/css server commands & extension mapping
* `ARCHITECTURE.md`, `IMPLEMENTATION_GUIDE.md`, `README.md`
---
## If you want the “next step” improvements (high impact)
1. **Add `call_hierarchy` + `code_action` + `format_document`** (bigger “IDE parity” story)
2. **Multi-LSP per file** for web projects (TypeScript LSP + ESLint LSP diagnostics)
3. **Patch application helper** (optional): a tool that applies `WorkspaceEdit` safely (with diff + rollback)
4. **Repository-aware workspace selection**: explicit “workspaceRoot” parameter when Codex works across multiple repos simultaneously
