# Detailed Implementation Guide
This guide explains how the bridge works and how to extend it.
## 1) How Codex → MCP → LSP works
1. **Codex CLI** decides it needs semantic information (e.g., "where is this function defined?").
2. Codex calls an **MCP tool** exposed by this server (over Streamable HTTP).
3. The bridge routes the call to the correct **language server** (LSP) based on file extension and detected workspace root.
4. The language server returns a precise answer (locations/ranges/types/edits) based on a real parser+type checker.
5. Codex uses that response to perform edits safely.
## 2) MCP server setup
The bridge uses **FastMCP**. Running with `transport="http"` exposes the MCP endpoint at `/mcp`.
## 3) LSP client handshake
The LSP client does:
1. Start language server subprocess (`command` + `args`).
2. Send `initialize` (includes `rootUri`, capabilities, initialization options).
3. Send `initialized`.
4. On first file access: `textDocument/didOpen`.
5. On subsequent changes: `textDocument/didChange` (full text).
## 4) Adding a new language
Edit `config/default.toml` and add a new `[servers.<name>]` section:
```toml
[servers.go]
command = "gopls"
args = []
file_extensions = ["go"]
language_id = "go"
```
Then restart the bridge.
## 5) Common gotchas
### C/C++
* clangd needs compile flags. Prefer `compile_commands.json` generated by your build system.
### TypeScript/React
* Ensure your repo has `package.json` and `tsconfig.json` (or `jsconfig.json`) so tsserver can resolve modules.
### Python
* Type checkers (pyright/basedpyright) use config files (`pyrightconfig.json` or `pyproject.toml`) and need the right interpreter environment.
## 6) Next improvements (production hardening)
* Multi-LSP per file (TS + ESLint diagnostics)
* In-memory buffers (optional tool `sync_buffer(uri,text)`)
* Workspaces per Codex session (if running as shared service)
* Structured logging + tracing
