# Codex LSP Bridge (MCP)

Give Codex CLI **IDE-grade semantic navigation** by exposing Language Server Protocol (LSP) features as MCP tools.

## What you get

* **Go to definition** / **type definition** / **find references**
* **Hover** / **signature help** / **call hierarchy**
* **Document symbols** / **workspace symbols**
* **Code actions** (autofix/refactors) / **format document**
* Works across **Python, Rust, C/C++, TypeScript/JavaScript/Node, React (JSX/TSX), HTML, CSS/SCSS/Less**
* One endpoint: `http://127.0.0.1:8000/mcp` (Streamable HTTP) or stdio

## Quickstart

### 1) Install this bridge

```bash
# from the repo root
pip install -e .
```

### 2) Install language servers

On Debian/Ubuntu you can run `./install.sh` to install all supported language servers.

**Python** (pick one)
```bash
pip install basedpyright   # provides basedpyright-langserver
# OR
npm i -g pyright           # provides pyright-langserver
```

**Rust**
```bash
rustup component add rust-analyzer
```

**C/C++**
```bash
# install clangd via your platform (llvm package)
clangd --version
```

**TypeScript/JavaScript/Node/React**
```bash
npm i -g typescript typescript-language-server
```

**HTML/CSS**
```bash
npm i -g vscode-langservers-extracted
```

### 3) Run the server

```bash
codex-lsp-bridge serve --config ./config/default.toml --host 127.0.0.1 --port 8000
```

### 4) Connect Codex CLI

Edit `~/.codex/config.toml` (HTTP):

```toml
experimental_use_rmcp_client = true

[mcp_servers.lsp_bridge]
url = "http://127.0.0.1:8000/mcp"
```

Or use the Codex CLI helper:

```bash
codex mcp add lsp_bridge --url http://127.0.0.1:8000/mcp
```

## Using it effectively

Prompt pattern:

> When navigating or refactoring code, always use LSP tools instead of text search.

Example:

```bash
codex "Find all references to UserRepository and rename it to AccountRepository. Use LSP rename_symbol first."
```

Note: line/column positions are 0-indexed.
Tip: if line/column might be off, pass `fuzzy=true` (and optionally `fuzzy_radius`) to position-based tools.

## LSP tool coverage

Core tools:
- `go_to_definition`, `type_definition`
- `find_references`, `rename_symbol`
- `hover`, `signature_help`
- `document_symbols`, `workspace_symbols`
- `code_action`, `format_document`
- `call_hierarchy`, `diagnostics`, `wait_for_diagnostics`, `lsp_bridge_status`
- `resolve_symbol` (fuzzy name-based lookup)

## Smoke test (no file changes)

You can run a quick LSP smoke test against any file:

```bash
python scripts/lsp_smoke_test.py --file /abs/path/to/file.py --line 10 --column 5
```

Add `--call-hierarchy` if you want to test call hierarchy responses.

## Install language servers (Debian/Ubuntu)

If you are on Debian/Ubuntu, you can use the provided script:

```bash
./install.sh
```

This installs:
- basedpyright (Python)
- ruff + ruff-lsp (Python lint/autofix)
- rust-analyzer (Rust)
- clangd (C/C++)
- typescript-language-server + typescript (TS/JS/React)
- vscode-html-language-server + vscode-css-language-server (HTML/CSS)
- eslint (JS/TS lint)

Note: some commands may land in `~/.local/bin` or `~/.cargo/bin`. Ensure those are on `PATH` for the user that runs the bridge.

## Config

See `config/default.toml`. It maps file extensions to language server commands.

For Python, `config/default.toml` also enables stronger type checking settings and
excludes large folders like `.venv` to keep the LSP responsive.

You can point the bridge to a config file via:

```bash
export CODEX_LSP_BRIDGE_CONFIG=/path/to/config.toml
```

## MCP setup (HTTP vs stdio)

HTTP (bridge runs separately):

```toml
experimental_use_rmcp_client = true

[mcp_servers.lsp_bridge]
url = "http://127.0.0.1:8000/mcp"
```

Stdio (Codex spawns the bridge, no HTTP):

```toml
[mcp_servers.lsp_bridge]
command = "/absolute/path/to/codex-lsp-bridge"
args = ["serve", "--transport", "stdio", "--config", "/absolute/path/to/config/default.toml"]
```

## Multi-project behavior

- Each tool call includes a `file_path`.
- The bridge detects the workspace root by walking upward from that file and looking for markers like `.git`, `package.json`, `Cargo.toml`, etc.
- It starts an LSP per `(language, workspace_root)` so multiple repos do not contaminate each other.
- Absolute paths are recommended; relative paths resolve against the bridge's `default_root`.

You can also force a workspace root by passing `workspace_root` to any file-based tool call.

## Autofix + lint + strong types

The `code_action` tool returns quick fixes and refactors when a language server supports them.
For best results per language:

- Python: basedpyright/pyright for types. For lint+autofix, consider switching to `ruff-lsp`
  or `pylsp` with ruff/black plugins.
- TypeScript/JavaScript: types come from `typescript-language-server` and your `tsconfig.json`
  (use `strict: true` for strong types). For lint/autofix, use ESLint and its LSP server.
- Rust: rust-analyzer provides strong types and code actions (e.g., import/quickfix).
- C/C++: clangd provides diagnostics and some fixes; accuracy depends on `compile_commands.json`.

## System prompt snippet

See `SYSTEM_PROMPT_SNIPPET.md` for a short snippet you can append to your AI system prompt so it always prefers LSP tools.

## Security notes

* Local is safest: the bridge reads your repo files and launches local binaries.
* If you deploy remotely, only do so where the server has access to the same repo and protect it with auth.